GitLab CI components

OrbitalReg ships a catalog of six reusable GitLab CI/CD Components under tools/gitlab-components/. Each component is self-contained, OIDC-authenticated, and works against any OrbitalReg endpoint.

The components eliminate per-project copies of upload + scan + promote boilerplate, and they pair with the OIDC token-exchange flow so pipelines never need a long-lived bearer token in CI variables.

OIDC token exchange

Every component uses the same auth shape: GitLab's CI_JOB_JWT_V2 is exchanged at OrbitalReg's /api/v1/auth/oidc-exchange endpoint for a short-lived bearer token. The trust policy (which (issuer, audience, sub-pattern) tuples are accepted) lives in oidc_trust_policies, managed under Admin → OIDC → Trust policies.

A typical trust policy:

issuer:        "https://gitlab.example.com"
audience:      "https://orbitalreg.example.com"
sub_pattern:   "project_path:acme/.+:ref_type:branch:ref:main"
project_id:    "0e2d…"
service_account_id: "1f3e…"
expires_in:    "1h"

Pipelines targeting main branches under acme/* are matched and mint a 1-hour token scoped to that service account.

Catalog

Component	Purpose
upload-maven	Wrapper around mvn deploy; OIDC-auth
upload-npm	Wrapper around npm publish; OIDC-auth
upload-pypi	Wrapper around twine upload; OIDC-auth
upload-docker	Wrapper around docker push; OIDC-auth + cosign keyless
scan-and-promote	Promotion gated by Detection findings + license policy
block-list-check	HEAD-probe against published block list, fail fast in CI

Quickstart — upload-maven

# .gitlab-ci.yml
include:
  - component: gitlab.example.com/orbitalreg/components/upload-maven@1.0.0
    inputs:
      endpoint: https://orbitalreg.example.com
      project: acme
      repo: internal-maven
      jar_path: target/my-lib-1.0.0.jar

stages:
  - test
  - publish

publish-to-orbital:
  stage: publish
  needs: [test]
  extends: .orbitalreg/upload-maven

The component:

1. Exchanges CI_JOB_JWT_V2 for an OrbitalReg bearer token
2. Wires <server> block in a generated settings.xml
3. Runs mvn deploy:deploy-file against the configured endpoint
4. Surfaces the artifact ID and Detection scan link in the job log

Quickstart — scan-and-promote

include:
  - component: gitlab.example.com/orbitalreg/components/scan-and-promote@1.0.0
    inputs:
      endpoint: https://orbitalreg.example.com
      project: acme
      from_repo: maven-staging
      to_repo: maven-releases
      coordinates: com.example:my-lib:1.0.0
      max_severity: HIGH
      license_policy: strict

promote-to-prod:
  stage: deploy
  needs: [publish]
  extends: .orbitalreg/scan-and-promote

The promotion gate:

1. Polls /api/v1/detection/findings?artifact_id=… until the scan completes (or times out)
2. Fails the job if any finding's severity is above max_severity
3. Fails the job if any detected license is outside license_policy
4. POSTs /api/v1/projects/<p>/repos/<from>/promote/<to> with the gated artifact's ID
5. Surfaces the new artifact's URL in the job log

block-list-check

For early failure on consumed-but-blocked artifacts:

include:
  - component: gitlab.example.com/orbitalreg/components/block-list-check@1.0.0
    inputs:
      endpoint: https://orbitalreg.example.com
      coordinates_file: dependencies.txt

check-block-list:
  stage: test
  extends: .orbitalreg/block-list-check

The component HEAD-probes each coordinate; any 451 fails the job and echoes the X-Orbital-Block-Reason header so the developer sees the operator-supplied message inline.

Air-gapped GitLab + air-gapped OrbitalReg

The components are pure shell + curl + the relevant client tool; they don't pull anything from the public internet at runtime. For air-gapped GitLab installs, copy the component versions into your private GitLab catalog and adjust the include: URL accordingly.

Catalog publishing

Components live in the OrbitalReg repo's tools/gitlab-components/ tree. Each tagged release rebuilds the catalog descriptor and (if you've configured a private GitLab catalog target) pushes new versions automatically.

Phase status

The component catalog ships in three phases. All three are released:

• Phase A — upload-maven, upload-npm, upload-docker ✅
• Phase B — upload-pypi, scan-and-promote, block-list-check ✅
• Phase C — CI tests, catalog-submission polish, CATALOG.md operator guide ✅

The full release log lives in tools/gitlab-components/CHANGELOG.md.