CI/CD

SBOMs in GitLab CI

Two lines in .gitlab-ci.yml give every pipeline a scored SBOM, uploaded with the project, commit and job verified by SBOMBox. The job signs in with a GitLab-issued identity token, so there is no secret to create, store or rotate.

Before you start

Add the pipeline

Add this to .gitlab-ci.yml and put in your project ID:

# .gitlab-ci.yml
include:
  - remote: 'https://raw.githubusercontent.com/sbombox/sbombox-com/main/gitlab/sbombox-component.yml'

variables:
  SBOMBOX_PROJECT: "0193c0de-..."   # your project ID (not a secret)

sbombox:
  variables:
    SBOMBOX_FAIL_UNDER: "7"         # optional: fail below this score

The include adds one job, sbombox, in the test stage, running on python:3.12-slim. It declares the identity token for you:

id_tokens:
  SBOMBOX_ID_TOKEN:
    aud: "sbombox-api"

The CLI exchanges that token for a 15-minute token that can only upload to this one project. Override any of the job's settings by redefining keys under sbombox:, as the example does for SBOMBOX_FAIL_UNDER. Set the job's options under sbombox: variables:, not top-level variables:, because the job's own defaults take precedence over top-level ones.

The include above follows main. For audited pipelines, replace main in the URL with a commit SHA of the sbombox-com repository, or keep a reviewed copy in your repository and include it locally:

include:
  - local: ci/sbombox-component.yml   # a reviewed copy in your repository

What each run does

Pull requests vs releases

Use rules: to run the job on merge requests, the default branch and release tags, and to require the upload on tags:

include:
  - remote: 'https://raw.githubusercontent.com/sbombox/sbombox-com/main/gitlab/sbombox-component.yml'

variables:
  SBOMBOX_PROJECT: "0193c0de-..."

sbombox:
  variables:
    SBOMBOX_FAIL_UNDER: "7"
  rules:
    # Merge requests: score, gate, and upload when the job can sign in.
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    # The default branch: keep the latest SBOM on record.
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    # Release tags: the upload must succeed.
    - if: $CI_COMMIT_TAG =~ /^v/
      variables:
        SBOMBOX_UPLOAD: "true"

Check compliance rulesets on releases with sbombox compliance sbom.json -p cra-readiness in a later job that uses the sbom.json artifact. See the end-to-end guide for the full flow.

Monorepos

Run the job once per service with parallel:matrix. Each matrix job scans its own directory and can upload to its own project:

include:
  - remote: 'https://raw.githubusercontent.com/sbombox/sbombox-com/main/gitlab/sbombox-component.yml'

sbombox:
  variables:
    SBOMBOX_FAIL_UNDER: "7"
  parallel:
    matrix:
      - SBOMBOX_PATH: services/api
        SBOMBOX_PROJECT: "0193c0de-..."
      - SBOMBOX_PATH: services/web
        SBOMBOX_PROJECT: "0193c0df-..."

To report the whole repository as one product, combine the uploads in SBOMBox. See Unify SBOMs.

Self-managed GitLab

Options

Set these under sbombox: variables:, or as CI/CD variables in the GitLab project settings.

Job variables
VariableDefaultWhat it does
SBOMBOX_PROJECT-Project ID to upload to. Not a secret.
SBOMBOX_FAIL_UNDER0Minimum quality score, 0-10. The job fails below it, after the upload. 0 turns the gate off.
SBOMBOX_UPLOADautoauto uploads when the job can sign in and skips otherwise. true fails without credentials. false never uploads.
SBOMBOX_PATH.Directory to scan.
SBOMBOX_FORMATcyclonedxcyclonedx or spdx.
SBOMBOX_TOKEN-Only if you prefer a stored token to keyless sign-in. Store it as a masked variable.
SBOMBOX_GENERATORSBOMBox choosesForce which generator runs, comma-separated in order of preference, e.g. npm-sbom or cyclonedx-npm,syft.
SBOMBOX_VERSIONcurrent versionInstaller: pin the CLI version, e.g. 0.2.0, for reproducible builds. Versions below the supported minimum are refused.
SBOMBOX_GENERATORSautoInstaller: generators to install - syft, cyclonedx-py, cyclonedx-npm, cdxgen, auto, all or none. Add cdxgen for Java and Gradle.
SBOMBOX_SYFT_VERSIONv1.57.1Installer: the syft version to install. It is checked against its published SHA-256.
SBOMBOX_NO_MODIFY_PATH-Installer: set to 1 so CI shell profiles are left alone. Add $HOME/.local/bin to PATH yourself, as the examples do.
SBOMBOX_API_URLhttps://api.sbombox.comSelf-hosted SBOMBox: the API address, for both the installer and the CLI.

Troubleshooting

Common problems
SymptomCauseFix
No credentials (e.g. fork pipeline): skipping upload.The job has no identity token and no SBOMBOX_TOKEN.Expected on fork pipelines. Otherwise check that the job still declares id_tokens if you overrode it.
Authentication failed: SBOMBox refused the CI identity (403) (exit 5)This GitLab project is not allowed to upload to the SBOMBox project, or a branch rule excludes this ref. Merge requests from forks run in the fork and are refused too.Run sbombox ci trust once in the repository; sbombox ci show lists what is allowed. For fork merge requests, set SBOMBOX_UPLOAD: "false" with a rule.
Authentication failed: No CI identity token available. Declare id_tokens: SBOMBOX_ID_TOKEN: aud: sbombox-api on the job, or set SBOMBOX_TOKEN. (exit 5)A custom job runs sbombox push without an identity token.Add the id_tokens block shown above to that job.
No credentials for upload. (exit 5)SBOMBOX_UPLOAD is true and the job could not sign in.Check the identity token or SBOMBOX_TOKEN as in the rows above.
sbombox job: chosen stage does not existYour pipeline defines stages: without test.Add test to stages:, or set sbombox: stage: to one of yours.
Could not detect project ecosystem in <dir>: no supported manifest or lockfile. (exit 4)The scan ran in a directory without a manifest.Pass the right directory with sbombox generate --dir <path>. In a monorepo, run one job per service.
No lockfile for npm: transitive dependencies may be missingThe lockfile is not committed, so versions are guessed.Commit the lockfile (package-lock.json, uv.lock, go.sum and so on). See Languages.
Generation failed: No SBOM generator found for ecosystems [...] (exit 4)No generator for this ecosystem is installed on the runner.Run the installer in the same job, or add one with SBOMBOX_GENERATORS, e.g. cdxgen for Java.
Generation failed: SBOMBOX_GENERATOR names unknown generator(s) ... (exit 4)A typo in SBOMBOX_GENERATOR.Use a name from the list the message prints.
Score 6.4 is below threshold 7.0. (exit 1)The quality gate failed. The SBOM was already uploaded, so the run is on record.Run sbombox score sbom.json --format detailed to see the weakest checks, or lower SBOMBOX_FAIL_UNDER while you improve it.
Exit 6, upgrade requiredThe pinned CLI version is below the minimum SBOMBox accepts.Raise or remove SBOMBOX_VERSION.

Frequently asked questions

Does keyless upload work on GitLab.com and self-managed?

Yes, on both. Self-managed instances must be reachable from SBOMBox so it can check the token's signature.

Can I see what the included job runs?

Yes. The component file is short and commented. Review it, then pin it to a commit or copy it into your repository.