Skip to content

Upload SBOMs from GitHub Actions

The affectra/upload-sbom action uploads the SBOMs your build writes to the release they describe. Affectra then matches their components against vulnerability data and lists the findings on the release. To read them and record what they mean for your product, see Assess findings with VEX.

You name the release the way your pipeline knows it: the product, optionally a variant, and the version. Whatever does not exist yet is created, so a new version needs no setup in Affectra. See Products, variants and releases.

Before you start, you need:

  • an SBOM file written by your build, for example with Syft, cdxgen, Yocto or ESP-IDF. See Supported SBOM formats;
  • the slug of your organization, which you see in the address of the app, and the url to upload to. For trusted publishing, copy the url from the example workflow on the Trusted publishers page of the app: it can differ from the address of the app;
  • either a trusted repository (no secret) or an API key.
Trusted publishing API key
Stored secret none the key, in a GitHub secret
Set up by an admin, once per repository an admin, once per pipeline
Job permission id-token: write not needed

Use trusted publishing when you can. A key that leaks can be used by anyone until you revoke it. With trusted publishing, there is nothing to leak.

An admin of your organization trusts the repository once. Trusted publishers explains what this guards against.

  1. Open Trusted publishers in the app.
  2. Enter the repository as owner/name and select Trust repository.
  3. Optionally restrict it to a workflow file, such as release.yml, a ref pattern, such as refs/tags/v*, or a GitHub environment. All restrictions you set must match.
  4. For a private repository, Affectra cannot look the repository up. Enter its Owner ID and Repository ID too. Get both with gh api repos/OWNER/NAME --jq '.owner.id, .id'.

The repository is pinned by GitHub’s IDs. Renaming it keeps it trusted, and a new repository under the old name does not inherit the trust.

Then add the action to the workflow:

name: SBOM
on:
push:
tags: ["v*"]
permissions: {}
jobs:
sbom:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write # lets the job prove to Affectra which repository it runs in
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
# ... build, and write your SBOMs to build/sbom/
- uses: affectra/upload-sbom@9d96158dc5e1155428b006b8d1fa37458afb5e98 # v2.1.0
with:
url: https://affectra.example.com
organization: acme
product: Gateway
variant: rev-b # leave out for a product with one build
version: ${{ github.ref_name }}
sbom: |
build/sbom/*.cdx.json

Each run gets a short-lived token from GitHub that names its repository, workflow and ref. Affectra checks it against your trusted publishers. Nothing is stored in the repository, and Affectra’s logs show which repository and run uploaded. Runs of pull requests from forks get no token, so they cannot upload.

If your Affectra admin tells you to use another audience for the token, pass it as audience. The default is the url.

Use a key when your instance does not accept GitHub tokens, or when the repository cannot be trusted directly.

  1. In the app, open API keys (an admin can; see API keys) and select Create a key. Give it a name, such as the pipeline it is for, and set Access to Can propose changes. A Read only key cannot upload.
  2. Copy the key. It is shown once.
  3. In GitHub, open Settings, Secrets and variables, Actions and add a repository secret named AFFECTRA_API_KEY.
  4. Pass it to the action. The job does not need id-token: write.
permissions: {}
jobs:
sbom:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
# ... build, and write your SBOMs to build/sbom/
- uses: affectra/upload-sbom@9d96158dc5e1155428b006b8d1fa37458afb5e98 # v2.1.0
with:
url: https://affectra.example.com
organization: acme
api-key: ${{ secrets.AFFECTRA_API_KEY }}
product: Gateway
version: ${{ github.ref_name }}
sbom: build/sbom/*.cdx.json

When api-key is set, the action uses it and ignores the GitHub token. The key belongs to one organization, and organization must be that one.

Use one key per repository or pipeline, so you can revoke one without touching the others. Keys and trusted publishers can create releases and upload SBOMs. They cannot delete anything.

  • Pin every action to a full commit SHA and write the version in a comment, as above. A tag can be moved; a commit cannot. A tool such as Dependabot can propose new versions for you.
  • Give the job the least permissions it needs. Set permissions: {} for the workflow, then give each job contents: read, and id-token: write only when the job uses trusted publishing or signs an SBOM. Add attestations: write only for the jobs that call actions/attest-sbom or actions/attest-build-provenance.
  • Keep the key in a secret. Never write it into the workflow file, and never print it in a log.

The action sets outputs that later steps can read. For the full list, see the reference.

- id: upload
uses: affectra/upload-sbom@9d96158dc5e1155428b006b8d1fa37458afb5e98 # v2.1.0
with:
url: https://affectra.example.com
organization: acme
product: Gateway
version: ${{ github.ref_name }}
sbom: build/sbom/*.cdx.json
- run: echo "Release in Affectra: $RELEASE_URL"
env:
RELEASE_URL: ${{ steps.upload.outputs.release-url }}

Pass an output to a later step through env, as above, and not by writing ${{ ... }} into a shell script.

The step also writes a job summary with the result of each file and a link to the release.

  • Uploading the same file again changes nothing, so re-running a job is safe.
  • A warning when the step created a product or a named variant. This is expected the first time. After that it usually means a typo in the workflow. Delete the stray product in the app and fix the name.
  • A notice when the step created a release.
  • Warnings about the document, such as an invalid package URL. The upload still succeeds.
  • An error that fails the step when:
    • the key or token is rejected (401);
    • the key belongs to another organization, or the organization does not trust the repository, workflow or ref (404);
    • a file is not a supported SBOM, or its signature does not verify (400);
    • your organization requires signed uploads and the SBOM has no signature from a trusted publisher (403);
    • the job has neither api-key nor id-token: write;
    • Affectra cannot be reached, after retries.

Vulnerabilities appear on the release once Affectra has matched the components, usually within a minute. How matching works explains what Affectra compares. The step does not wait for that.

When Affectra answers 429 Too Many Requests, the step waits for the time in Retry-After and tries the file once more. If the wait is over 300 seconds, it does not wait and fails with Affectra’s message.

GitHub-hosted Linux, macOS and Windows runners work as they are. Self-hosted runners need bash, curl and jq.