CI/CD

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

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

What each run does

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 }}

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/bom

For 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 syft

Names: 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 Containers

See 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:

Environment variables
VariableDefaultWhat 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_AUDIENCEsbombox-apiAudience requested for the identity token. Change it only if your SBOMBox deployment uses another.
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.

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

Common problems
SymptomCauseFix
Notice SBOMBox upload skipped: No credentials: add 'permissions: id-token: write' to the jobThe 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 noneThe 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 permissionsattestations: 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 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.
Exit 6, upgrade requiredThe 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.