SBOMs in GitHub Actions
Run SBOMBox on every pull request and release in every repository, from one workflow you maintain centrally. Uploads are keyless, so there is no secret to create, store or rotate. For every input and output of the Action itself, see the GitHub Action reference.
Before you start
- Install the CLI on your machine and run
sbombox login. - In each repository, run
sbombox init. It picks the project and allows that repository's workflows to upload to it. To allow another repository later, runsbombox ci trustin it;sbombox ci showlists the repositories that can upload. - For a single repository,
sbombox initalso writes a ready workflow and you are done. The rest of this page is for rolling SBOMBox out across many repositories.
Add the pipeline
The recommended pattern for an organization is a reusable workflow in a central repository, such as acme/.github, that every repository calls. You change the SBOM policy in one place, and every repository picks it up when it moves to the new commit.
First, the reusable workflow in the central repository:
# In your central repository, e.g. acme/.github:
# .github/workflows/sbom.yml
name: SBOM
on:
workflow_call:
inputs:
project:
description: SBOMBox project ID (not a secret)
required: true
type: string
path:
description: Directory to scan
required: false
type: string
default: "."
fail-under:
description: Minimum quality score, 0-10
required: false
type: string
default: "7"
permissions:
contents: read
id-token: write
jobs:
sbom:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7
- uses: sbombox/action@v1
with:
project: ${{ inputs.project }}
path: ${{ inputs.path }}
fail-under: ${{ inputs.fail-under }}Then, in each repository, a short caller. Put in your project ID:
# In each repository: .github/workflows/sbom.yml
name: SBOM
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
id-token: write # lets the job prove who it is - no secret needed
jobs:
sbom:
uses: acme/.github/.github/workflows/sbom.yml@<commit-sha>
with:
project: 0193c0de-... # your project ID- Pin the call to a full commit SHA, not a branch, so a change to the central workflow is reviewed before it reaches any pipeline. Do the same for
sbombox/actionif your policy requires it. - No `secrets: inherit` is needed. The job signs in with its own OIDC identity. The caller must still grant
id-token: write, because a reusable workflow can only use permissions the caller gives it. - Private central repository: under its Settings, Actions, General, allow access from repositories in your organization.
What each run does
- Generates an SBOM with the most accurate tool for the project and scores it from 0 to 10.
- Uploads it keylessly, with the repository, commit, branch and run verified by SBOMBox. These uploads are recorded at provenance level P2.
- Writes the score, grade and any compliance results to the job summary, and keeps the SBOM with the run for 90 days.
- Enforces the minimum score only after the upload, so failing runs are on record too.
Pull requests from forks get no identity token, so with the default upload: auto the upload is skipped with a notice and the score gate still runs. Nothing from a fork reaches your project.
Pull requests vs releases
Keep the caller above for pull requests and pushes to main: it scores and gates every change, and uploads whenever the job can sign in. Add a second workflow for release tags. It insists on the upload, checks compliance rulesets, and signs the SBOM as a GitHub attestation bound to the artifact you ship:
# .github/workflows/release-sbom.yml
name: Release SBOM
on:
push:
tags: ["v*"]
permissions:
contents: read
id-token: write # keyless upload and signing
attestations: write # store the attestation
artifact-metadata: write # record the attested artifact
jobs:
sbom:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7
- name: Build
run: make dist # your build; produces dist/app.tar.gz
- uses: sbombox/action@v1
id: sbom
with:
project: 0193c0de-...
upload: "true" # a release must be on record
fail-under: "7"
profiles: ntia-2021,cra-readiness
- uses: actions/attest@v4
with:
subject-path: dist/app.tar.gz
sbom-path: ${{ steps.sbom.outputs.sbom-path }}upload: "true"fails the job if the SBOM cannot be uploaded, instead of skipping. A release without a recorded SBOM is not allowed through.- The score gate runs before signing, so an SBOM below the minimum is never attested.
actions/attestsigns with the job's identity through Sigstore and stores the attestation with the repository. It replacesactions/attest-sbom, which is now a wrapper around it and is being deprecated.- Attestations work in public repositories on every plan. Private and internal repositories need GitHub Enterprise Cloud. GitHub Enterprise Server is not supported.
Anyone with access to the repository can then check that the SBOM belongs to the artifact:
gh attestation verify dist/app.tar.gz \
--repo acme/app \
--predicate-type https://cyclonedx.org/bomFor how these stages fit together, from a developer's machine to a release, see the end-to-end guide.
Monorepos
Run one job per service with a matrix. Give each job its own path and a distinct artifact-name, or the jobs overwrite each other's artifact. Use one project per service when each ships on its own:
jobs:
sbom:
runs-on: ubuntu-24.04
strategy:
fail-fast: false
matrix:
include:
- service: api
project: 0193c0de-...
- service: web
project: 0193c0df-...
steps:
- uses: actions/checkout@v7
- uses: sbombox/action@v1
with:
project: ${{ matrix.project }}
path: services/${{ matrix.service }}
artifact-name: sbom-${{ matrix.service }} # one artifact per job
fail-under: "7"To report the whole repository as one product, upload each service's SBOM and combine them in SBOMBox. See Unify SBOMs.
Force a generator
SBOMBox picks the generator for you. When a project needs a specific one - to match what another team uses, or because a tool handles your build better - set the Action's generator input. Names are tried in order, and one that is not installed or fails falls through to the next:
- uses: sbombox/action@v1
with:
project: 0193c0de-...
generator: cyclonedx-npm,syft # try cyclonedx-npm, then syftNames: npm-sbom, pnpm-sbom, pnpm-sbom-lockfile, uv-cyclonedx, cyclonedx-py, cyclonedx-npm, cargo-cyclonedx, cyclonedx-gomod, cdxgen, syft. Install extra tools with the generators input, e.g. cdxgen for Java and Gradle. The language guides give the recommended choice per ecosystem.
Container images
Set the Action's image input to describe the image you ship instead of the source. It uses the SBOM BuildKit attached to the image when there is one, else scans it with syft, which the installer puts on the runner. The upload is keyless here too. For a private registry, run docker/login-action before this step:
jobs:
image-sbom:
runs-on: ubuntu-24.04
permissions:
contents: read
id-token: write
env:
IMAGE: ghcr.io/acme/app:${{ github.sha }}
steps:
- uses: actions/checkout@v7
- name: Build image
run: docker build -t "$IMAGE" .
- uses: sbombox/action@v1
with:
project: 0193c0de-... # a project for the image
image: ${{ env.IMAGE }} # scan the image instead of the source
artifact-name: sbom-image
fail-under: "6" # OS packages carry no hashes; see ContainersSee Containers for base images, layers and what to expect in the result.
Options
Configure the Action through its inputs; the GitHub Action reference lists them all with their outputs. When you call the CLI directly, as in the container job above, these environment variables apply:
| Variable | Default | What it does |
|---|---|---|
SBOMBOX_PROJECT | - | Project ID to upload to. Not a secret. |
SBOMBOX_TOKEN | - | Only if you prefer a stored API token to keyless sign-in. It takes precedence, and uploads are then recorded at P1. |
SBOMBOX_OIDC_AUDIENCE | sbombox-api | Audience requested for the identity token. Change it only if your SBOMBox deployment uses another. |
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. |
Runners that cannot reach sbombox.com can point the Action's installer-url input at an internal copy of the installer. It still downloads its tools, so allow those downloads or mirror them too.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Notice SBOMBox upload skipped: No credentials: add 'permissions: id-token: write' to the job | The job has no identity token: either a pull request from a fork, which is expected, or the permission is missing. | For your own branches, add id-token: write to the workflow or job permissions, and to the caller of a reusable workflow. |
The workflow does not start: the nested job is requesting id-token: write but is only allowed none | The caller of the reusable workflow does not grant the permission. | Add permissions: id-token: write to the calling workflow. |
Authentication failed: SBOMBox refused the CI identity (403) (exit 5) | This repository is not allowed to upload to the project, or a branch rule excludes this branch. | Run sbombox ci trust once in the repository. sbombox ci show lists what is allowed. |
SBOM score too low: Score 6.4 is below the minimum 7. | The quality gate failed after the upload. | Open the job summary, or run sbombox score sbom.json --format detailed locally, and fix the weakest checks. |
| The attestation step fails on permissions | attestations: write or artifact-metadata: write is missing, or the repository is private without GitHub Enterprise Cloud. | Add both permissions next to id-token: write, as in the release workflow. |
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. |
| Exit 6, upgrade required | The pinned CLI version is below the minimum SBOMBox accepts. | Raise or remove SBOMBOX_VERSION. |
Frequently asked questions
Do I need to store an SBOMBox secret in GitHub?
No. The job proves its identity with GitHub's OIDC token, which SBOMBox exchanges for a 15-minute token that can only upload to one project. Set token only if your policy requires a stored credential.
Why upload before the score gate?
So every run is recorded, including the ones that fail. Auditors can see when quality dropped and when it was fixed, not only the passing builds.
Can I pin versions for reproducible builds?
Yes. Pin the reusable workflow and sbombox/action to commit SHAs, the CLI with the version input, and syft with syft-version.