CI guide: Zephyr · Declarable

Zephyr: make the SBOM

Zephyr’s own west spdx command writes the SBOM. You run it around the build, then upload the files it writes.

Where the key and the product id come from

Uploading from CI or the API is part of the Maker plan and the ones above it. On the Free plan the Settings page shows no key form. Without a key you can still run the free SBOM check and upload a release by hand in the app.

Sign in, open your product, then Settings → API keys. Create a key there — it is shown once. That same page shows these steps again with your product id already filled in, so once the key exists you may not need this page at all.

Ask west to record the build
Run this once, before west build, so the build leaves the data west spdx needs.
sh
```
west spdx --init -d build
```
Build as usual
Your normal build into the same directory.
sh
```
west build -b <your board> -d build
```
Write the SBOM
This writes app.spdx, zephyr.spdx, build.spdx and modules-deps.spdx into build/spdx. The upload takes all of them as one release.
sh
```
west spdx -d build
```
Send west.yml and the .config alongside them
Add west.yml and build/zephyr/.config beside the SPDX files. Without them the Zephyr version is unknown and its vulnerability matches stay low confidence. In the GitHub example below, the application repository is checked out at app/, so its west.yml is at app/west.yml; in a separate manifest-repository layout, west.yml sits at that repository’s own root instead, wherever your pipeline checks it out.

The GitHub example runs in the pinned Zephyr CI container (ghcr.io/zephyrproject-rtos/ci, tag v0.29.4), which brings the compiler, and adds Node for the upload step; the board and the container tag are yours to change. A west spdx document names a module like mbedtls with no PURL or CPE, so a vulnerability scanner reading the file alone matches nothing against it — a real question makers have asked in public with no answer (zephyrproject-rtos/zephyr discussion #106620). Declarable writes the real upstream identifiers onto the module rows it recognises before matching runs. A module outside that table stays unidentified and is reported as a gap, not silently dropped.

What this file does not list

Source: the upstream documentation at https://docs.zephyrproject.org/latest/develop/west/zephyr-cmds.html, read 2026-10-09. Each point says whether the upstream page states it or whether it is our reading.

It lists the source files that went into the build, the build artifacts, and a document of module dependencies. It is not documented as a list of every part of your product. (stated upstream)
Binary blobs cannot carry a licence comment, so their licence comes only from a REUSE.toml file if someone wrote one. (stated upstream)
SBOM generation for the native_sim platform is not supported. (stated upstream)
Vendor HALs, prebuilt libraries and silicon-vendor SDKs kept outside the West workspace are not files west spdx is documented to read, so expect them to be missing or thin. (our reading)
The bootloader and any firmware you flash separately are built apart from this tree, so they are not in these files either. (our reading)

What to do: add the missing parts to the SBOM by hand, or ask the vendor of each part for their own SBOM. Declarable flags a component as a binary blob only when it is in your SBOM and matches one it already knows; a part the file never mentions is not found for you.

GitHub Actions example

An example to copy and adapt, not your actual workflow file. It ends with the Declarable Action, whose two files you download from the files page.

Each upload under a new version becomes the product’s current release, and what Declarable then shows and sends (open vulnerabilities, gaps, alerts) is about that release. So upload the builds you ship. The examples below build on every push but upload only for a tag or the default branch. To change that, edit the if: line on the GitHub upload step, or put your own rules: in the GitLab job that extends the template.

yaml

on: push

jobs:
  sbom:
    runs-on: ubuntu-latest
    container: ghcr.io/zephyrproject-rtos/ci:v0.29.4
    steps:
      - uses: actions/checkout@v4
        with:
          path: app
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: |
          west init -l app
          west update
          pip install -r zephyr/scripts/requirements-base.txt
      - run: |
          west spdx --init -d build
          west build -b <your board> app -d build
          west spdx -d build
      # The Action is not on the Marketplace yet. Download action.yml and upload.mjs from
      # https://declarable.io/docs/ci/files/action.yml and https://declarable.io/docs/ci/files/upload.mjs
      # into .github/actions/declarable/ in your repository and commit them: a vendored copy is code
      # you can read before it runs with your API key.
      - uses: ./app/.github/actions/declarable
        # A release is recorded for a tag and for the default branch only. Edit this line to change that.
        if: github.ref_type == 'tag' || github.ref_name == github.event.repository.default_branch
        with:
          api-key: ${{ secrets.DECLARABLE_API_KEY }}
          product-id: <your product id>
          sbom-path: build/spdx/*.spdx app/west.yml build/zephyr/.config

GitLab CI example

An example to copy and adapt, not your actual .gitlab-ci.yml. It ends with the Declarable job.

The job needs declarable.yml and a copy of upload.mjs in your repository, both on the files page. Put declarable.yml at the path the include: at the top of this example names, and upload.mjs at the path DECLARABLE_UPLOAD_SCRIPT names:

The upload job runs for a tag or the default branch only. A pipeline on another branch shows no declarable_upload job, and that is the template’s rule, not a fault.

yaml

include:
  - local: integrations/gitlab-ci/declarable.yml

build:
  image: ghcr.io/zephyrproject-rtos/ci:v0.29.4
  script:
    - west init -l .
    - west update
    - west spdx --init -d build
    - west build -b <your board> . -d build
    - west spdx -d build
  artifacts:
    paths:
      - build/spdx/
      - west.yml
      - build/zephyr/.config

declarable_upload:
  extends: .declarable_upload
  needs:
    - job: build
      artifacts: true
  variables:
    # The path of the upload.mjs you copied into your repository.
    DECLARABLE_UPLOAD_SCRIPT: "ci/declarable/upload.mjs"
    DECLARABLE_PRODUCT_ID: "<your product id>"
    DECLARABLE_SBOM_PATH: "build/spdx/*.spdx west.yml build/zephyr/.config"

Any other CI

A release script or another CI can run the same upload from a shell.

Read upload.sh before you run it, then point it at build/spdx/*.spdx west.yml build/zephyr/.config:

export DECLARABLE_API_KEY=...        # from your secret store, never typed into a script
export DECLARABLE_PRODUCT_ID="<your product id>"
export DECLARABLE_SBOM_PATH="build/spdx/*.spdx west.yml build/zephyr/.config"
sh integrations/curl/upload.sh

Nothing limits a script: run it from the job that builds a release.

Left unset, the version is the commit the build ran from; set DECLARABLE_VERSION to the tag for a tag build.

Inputs and exit codes

GitHub calls them inputs; GitLab and the shell script read the same settings as variables. The key scopes are in the API reference.

GitHub input	Variable	Default	What it does
`api-key`	`DECLARABLE_API_KEY`	none, required	Your API key (scopes releases:write and products:read). Keep it in your CI secret store, never in the file.
`product-id`	`DECLARABLE_PRODUCT_ID`	none, required	Which product the release belongs to. It is in the product page’s address.
`sbom-path`	`DECLARABLE_SBOM_PATH`	none, required	One or more SBOM files or globs, separated by newlines or spaces. Every match is sent in one release. A pattern that matches nothing stops the job.
none	`DECLARABLE_UPLOAD_SCRIPT`	none, required (GitLab only)	The path of the upload.mjs you copied into your repository. The GitLab job stops with exit 2 if it is empty.
`keep-paths`	`DECLARABLE_KEEP_PATHS`	"false"	Needed only by a reader that takes the environment from the file’s path (PlatformIO today). "true" sends each file under its path inside the project instead of its base name; without it every file uploads under its base name.
`version`	`DECLARABLE_VERSION`	the commit SHA	The release’s label. Re-running with a version that already exists records nothing new and checks the findings.
`api-base-url`	`DECLARABLE_API_BASE_URL`	https://declarable.io	Where Declarable runs. Change it only for a self-hosted or staging copy.
`replace`	`DECLARABLE_REPLACE`	"false"	"true" replaces the release already under this version when the files differ; otherwise different files are left alone.
`released-at`	`DECLARABLE_RELEASED_AT`	none (no date is sent)	Optional. The day the firmware shipped, as YYYY-MM-DD, read as a UTC date. Refused if it is in the future. Ignored when the same files were already uploaded under this version.
`commit`	`DECLARABLE_COMMIT`	the commit that triggered the build	The commit the firmware was built from, stored with the release. "none" sends no commit. At most 200 characters.
`build-id`	`DECLARABLE_BUILD_ID`	none (nothing is sent)	Optional. Your own label for the build, stored with the release. At most 200 characters.
`image-sha256`	`DECLARABLE_IMAGE_SHA256`	none (nothing is sent)	Optional. The SHA-256 of the firmware image, 64 hex characters. Stored as given; nothing checks it against a real image.
`supported-until`	`DECLARABLE_SUPPORTED_UNTIL`	none (nothing is sent)	Optional. The last day you will support this release, as YYYY-MM-DD. A value Declarable would refuse stops the job with exit 2. The four build fields are ignored when the same files were already uploaded under this version.
`fail-on-gap`	`DECLARABLE_FAIL_ON_GAP`	blocker	blocker, major, minor or none. Fails the job when the current release has a gap at that severity or worse; none never fails it.
`fail-on-exploited`	`DECLARABLE_FAIL_ON_EXPLOITED`	"true"	"true" fails the job when an open vulnerability is known to be exploited; "false" only reports it.

GitHub Action outputs (give the step an id): release-id is the id of the release the step uploaded, or of the one already under this version; release-url is that release’s address in Declarable; component-count is how many components the release holds (empty if the version exists with different files); recorded is "true" when a new or replaced release was recorded, "false" when the version already existed.

0: uploaded and inside your thresholds (or uploaded with the findings not checked, which the last line says).
1: a threshold was crossed.
2: the upload failed.

A worked example: build fields and outputs

One pipeline that hashes the image it built, sends the hash and the run id with the upload, and reads back the release’s address. Both fields are stored as sent; nothing checks them against the files you uploaded.

yaml

      - name: Hash the firmware image
        id: image
        run: echo "sha256=$(sha256sum build/firmware.bin | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
      - uses: ./.github/actions/declarable
        id: declarable
        with:
          api-key: ${{ secrets.DECLARABLE_API_KEY }}
          product-id: <your product id>
          sbom-path: build/*.spdx
          build-id: ${{ github.run_id }}
          image-sha256: ${{ steps.image.outputs.sha256 }}
      - run: echo "Recorded at ${{ steps.declarable.outputs.release-url }}"

The same two fields on GitLab, computed in before_script so the export reaches the job’s own script::

yaml

declarable_upload:
  extends: .declarable_upload
  needs:
    - job: build
      artifacts: true
  variables:
    DECLARABLE_UPLOAD_SCRIPT: "ci/declarable/upload.mjs"
    DECLARABLE_PRODUCT_ID: "<your product id>"
    DECLARABLE_SBOM_PATH: "build/spdx/*.spdx"
    DECLARABLE_BUILD_ID: $CI_PIPELINE_ID
  before_script:
    - export DECLARABLE_IMAGE_SHA256=$(sha256sum build/firmware.bin | cut -d' ' -f1)

And from a shell:

export DECLARABLE_API_KEY=...
export DECLARABLE_PRODUCT_ID="<your product id>"
export DECLARABLE_SBOM_PATH="build/spdx/*.spdx"
export DECLARABLE_BUILD_ID="$CI_JOB_ID"   # or any run id your own CI exposes
export DECLARABLE_IMAGE_SHA256=$(sha256sum build/firmware.bin | cut -d' ' -f1)
sh integrations/curl/upload.sh

Declarable prepares documentation for you to review. It is not legal advice and not certification. You sign your own declaration of conformity.