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
urlto upload to. For trusted publishing, copy theurlfrom 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.
Choose how the job signs in
Section titled “Choose how the job signs in”| 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.
Upload with trusted publishing
Section titled “Upload with trusted publishing”An admin of your organization trusts the repository once. Trusted publishers explains what this guards against.
- Open Trusted publishers in the app.
- Enter the repository as
owner/nameand select Trust repository. - Optionally restrict it to a workflow file, such as
release.yml, a ref pattern, such asrefs/tags/v*, or a GitHub environment. All restrictions you set must match. - 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: SBOMon: 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.jsonEach 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.
Upload with an API key
Section titled “Upload with an API key”Use a key when your instance does not accept GitHub tokens, or when the repository cannot be trusted directly.
- 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.
- Copy the key. It is shown once.
- In GitHub, open Settings, Secrets and variables, Actions and add a repository secret named
AFFECTRA_API_KEY. - 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.jsonWhen 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.
Keep the workflow safe
Section titled “Keep the workflow safe”- 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 jobcontents: read, andid-token: writeonly when the job uses trusted publishing or signs an SBOM. Addattestations: writeonly for the jobs that callactions/attest-sbomoractions/attest-build-provenance. - Keep the key in a secret. Never write it into the workflow file, and never print it in a log.
Use the outputs
Section titled “Use the outputs”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.
What you see
Section titled “What you see”- 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-keynorid-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.
Runners
Section titled “Runners”GitHub-hosted Linux, macOS and Windows runners work as they are. Self-hosted runners need bash, curl and jq.
- Sign the SBOMs: Sign SBOMs.
- Upload from another CI system: Upload SBOMs from other CI.
- All inputs and outputs:
upload-sbomreference.