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
- Install the CLI on your machine and run
sbombox login. - In your GitLab project's checkout, run
sbombox init. It picks the SBOMBox project, allows this GitLab project's pipelines to upload to it, and prints the lines to add. - To allow another GitLab project later, run
sbombox ci trustin it, orsbombox ci trust --repo group/project.sbombox ci showlists what is allowed.
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 scoreThe 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 repositoryWhat each run does
- Installs the CLI and a pinned, checksum-verified SBOM generator.
- Generates the SBOM with the most accurate tool for the project, and prints the full score breakdown in the job log.
- Uploads it keylessly, with the project path, commit, branch or tag and job verified by SBOMBox. These uploads are recorded at provenance level P2.
- Enforces the minimum score only after the upload, so failing runs are on record too.
- Keeps
sbom.jsonas a job artifact for 90 days, also when the job fails.
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"- On merge requests and the default branch,
SBOMBOX_UPLOAD: autouploads when the job has an identity and skips otherwise. - On tags,
SBOMBOX_UPLOAD: "true"fails the job when it cannot upload, so no release ships without a recorded SBOM. - To accept uploads from protected release branches only, allow them with
sbombox ci trust --branch <name>.
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
- Keyless upload works on self-managed GitLab too. The CLI sends your instance's address with the exchange, and SBOMBox fetches its signing keys from
<instance>/-/openid_connect/jwks.jsonover HTTPS. That address must be reachable from SBOMBox. - If your instance is not reachable from the internet, use a token instead: create a project API token in SBOMBox and store it as a masked, protected CI/CD variable named
SBOMBOX_TOKEN. The job uses it in place of the identity token, and uploads are recorded at P1. - If your runners cannot reach raw.githubusercontent.com, use the local include shown above.
Options
Set these under sbombox: variables:, or as CI/CD variables in the GitLab project settings.
| Variable | Default | What it does |
|---|---|---|
SBOMBOX_PROJECT | - | Project ID to upload to. Not a secret. |
SBOMBOX_FAIL_UNDER | 0 | Minimum quality score, 0-10. The job fails below it, after the upload. 0 turns the gate off. |
SBOMBOX_UPLOAD | auto | auto uploads when the job can sign in and skips otherwise. true fails without credentials. false never uploads. |
SBOMBOX_PATH | . | Directory to scan. |
SBOMBOX_FORMAT | cyclonedx | cyclonedx or spdx. |
SBOMBOX_TOKEN | - | Only if you prefer a stored token to keyless sign-in. Store it as a masked variable. |
SBOMBOX_GENERATOR | SBOMBox chooses | Force which generator runs, comma-separated in order of preference, e.g. npm-sbom or cyclonedx-npm,syft. |
SBOMBOX_VERSION | current version | Installer: pin the CLI version, e.g. 0.2.0, for reproducible builds. Versions below the supported minimum are refused. |
SBOMBOX_GENERATORS | auto | Installer: generators to install - syft, cyclonedx-py, cyclonedx-npm, cdxgen, auto, all or none. Add cdxgen for Java and Gradle. |
SBOMBOX_SYFT_VERSION | v1.57.1 | Installer: 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_URL | https://api.sbombox.com | Self-hosted SBOMBox: the API address, for both the installer and the CLI. |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
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 exist | Your 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 missing | The 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 required | The 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.