CI guide: nRF Connect SDK

nRF Connect SDK: make the SBOM

The nRF Connect SDK (NCS) is Nordic’s own version of Zephyr, built with west. The SBOM comes from the same west spdx command as a plain Zephyr project; only the manifest and the board name change.

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.

Point west at the Nordic manifest
Your application’s west.yml imports the sdk-nrf manifest repository (github.com/nrfconnect/sdk-nrf), where a plain Zephyr project imports zephyr. The pipelines below start from your application repository, so west init -l reads that file. Nothing else about the steps differs.
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 for your Nordic board
Use a board name from Nordic’s list. The examples use the nRF52840 DK; replace it with yours.
sh
```
west build -b nrf52840dk/nrf52840 -d build
```
Write the SBOM
This writes the same four .spdx files into build/spdx as a plain Zephyr build. 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 module version is unknown and its vulnerability matches stay low confidence. The example below checks the application repository out at app/, so its west.yml is at app/west.yml there.

The GitHub example runs in the pinned Zephyr CI container (ghcr.io/zephyrproject-rtos/ci, tag v0.29.4), which brings a compiler, and adds Node for the upload step; the board and the nRF Connect SDK version your manifest pins are yours to change. Declarable reads your manifest to tell Nordic’s forks of modules such as MCUboot from the upstream projects of the same name. That matching has been checked against the real v3.4.0 manifests, but not yet against the SBOM of a complete nRF Connect SDK build.

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 nrf52840dk/nrf52840 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:
    - pip install west
    - west init -l .
    - west update
    - west spdx --init -d build
    - west build -b nrf52840dk/nrf52840 . -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.