SCM metadata YAML spec

Reference for YAML emitted by cce scm describe. This is SCM API metadata only; it does not scan source code or emit Backstage catalog entities.

Package design (providers, auth, extension rules, future work): pkg/scmmeta/README.md

Command

cce scm describe \
  --provider gitlab \
  --base-url https://gitlab.com \
  --repo group/sub/project \
  --token "$GITLAB_TOKEN" \
  --pull-request-limit 5 \
  --commit-status-limit 5 \
  -o repo.yaml

--provider selects the SCM type (default gitlab). Self-hosted GitLab CE/EE: set --base-url to your instance root (for example https://gitlab.example.com).

Envelope

Key	Meaning
`schema_version`	Core schema version (`"3"` today)
`fetched_at`	RFC3339 UTC when metadata was fetched
`provider`	SCM provider id from `--provider`
`host`	API host (`gitlab.com` or self-hosted host)
`repo`	Canonical repo path (`group/sub/project`)

Core sections

`repository`

Cross-provider repository metadata: id, name, full_name, description, default_branch, visibility, clone/html URLs, created/updated timestamps, archived, empty, fork.

`activity`

Sub-key	Source (GitLab v1)
`pull_requests`	Open and recently closed merge requests (default cap 5; `--pull-request-limit`)
`commit_statuses`	CI statuses on default-branch HEAD (default cap 5; `--commit-status-limit`)
`pipelines`	Reserved (`supported: false`, empty `items`)

Commit lists are not included: they dominate YAML size. HEAD is still resolved internally so commit_statuses stays accurate.

Lists are sorted for stable diffs: pull requests by number descending, commit statuses by context name.

Extensions

Provider-native fields that do not map cleanly to core keys live under extensions.<provider>.

GitLab v1 example:

extensions:
  gitlab:
    path_with_namespace: group/sub/project
    topics:
      - platform
    merge_requests_enabled: true

Adding a core key requires a schema_version bump. Prefer extensions first when only one provider exposes a field.

Relationship to Backstage export

pkg/backstage enriches local checkout metadata for cce --format backstage. pkg/scmmeta fetches live SCM API activity and repository fields. The packages stay separate; a future workflow may merge API metadata hints with Backstage resolver precedence.

See also pkg/scmmeta/README.md (scmmeta vs pkg/source clone auth vs backstage).

Relationship to GitHub scan (`--repo`)

cce --repo owner/repo uses pkg/source (go-git clone, Basic x-access-token auth) to materialize a checkout for static analysis. That is unrelated to cce scm describe, which uses go-scm REST + Bearer and does not clone.

Limitations

Implemented provider today: GitLab (--provider gitlab)
No pipeline list (activity.pipelines.supported: false)
No code scan, classification, or Glean integration