CI guide: ESP-IDF · Declarable

ESP-IDF: make the SBOM

Espressif’s esp-idf-sbom tool reads the build’s project description and writes the SBOM.

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.

Build your project
The tool reads a file the build writes, so build first.
sh
```
idf.py build
```
Install the tool
It is a Python package.
sh
```
pip install esp-idf-sbom
```
Create the SBOM
The default format is SPDX tag-value, which Declarable reads. For CycloneDX add --format cyclonedx-json and name the file sbom.cdx.json. Without --output-file the SBOM goes to stdout.
sh
```
esp-idf-sbom create --output-file sbom.spdx build/project_description.json
```
Send dependencies.lock alongside the SBOM
If your project uses managed components, idf.py writes dependencies.lock at the project root. Upload it beside the SBOM: it names the exact registry package and version of each managed component, so Declarable can identify components the SBOM left without an identifier. The examples below already send it. A project with no managed components has no such file; delete it from the upload path, because the upload stops when a listed file is missing.

The GitHub example builds in the espressif/idf container and installs Node for the upload step; the image tag (the examples use espressif/idf:v6.1) and your project are yours to change. Source for the options: the esp-idf-sbom README, read 2026-10-08. The tool commits no sample of its own output, so our sample for this platform is written by hand from the tool source; check your first upload.

What this file does not list

Source: the upstream documentation at https://github.com/espressif/esp-idf-sbom, read 2026-10-09. Each point says whether the upstream page states it or whether it is our reading.

Your own code carries no SBOM data unless you add an sbom.yml manifest for it. (stated upstream)
A licence that is not on the SPDX list is reported as NOASSERTION unless you define it with custom-licenses. (stated upstream)
Components that are not linked into the application are in the SBOM but are not marked as dependencies. (stated upstream)
The tool reads manifest files. A prebuilt library or binary blob with no manifest has nothing for it to read, so expect it to be missing or thin. (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: espressif/idf:v6.1
    steps:
      - uses: actions/checkout@v4
      # The idf image has no Node; the upload step below needs it.
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: |
          . $IDF_PATH/export.sh
          idf.py build
          pip install esp-idf-sbom
          esp-idf-sbom create --output-file sbom.spdx build/project_description.json
        shell: bash
      # 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: ./.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: sbom.spdx dependencies.lock

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: espressif/idf:v6.1
  script:
    - . $IDF_PATH/export.sh
    - idf.py build
    - pip install esp-idf-sbom
    - esp-idf-sbom create --output-file sbom.spdx build/project_description.json
  artifacts:
    paths:
      - sbom.spdx
      - dependencies.lock

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: "sbom.spdx dependencies.lock"

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 sbom.spdx dependencies.lock:

export DECLARABLE_API_KEY=...        # from your secret store, never typed into a script
export DECLARABLE_PRODUCT_ID="<your product id>"
export DECLARABLE_SBOM_PATH="sbom.spdx dependencies.lock"
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.