The sbom component#
This page shows how to add the sbom component to an app's .gitlab-ci.yml: it generates a CycloneDX SBOM with cyclonedx/cyclonedx-php-composer, validates it, and publishes it as an artifact. The SBOM is the aircraft's parts manifest (nothing flies that is not on the list); start with the include, then read what the job does and which inputs it takes.
Include the component#
Add the include to the app's .gitlab-ci.yml, pinned to a commit SHA with the tag in a trailing comment:
include:
- component: $CI_SERVER_FQDN/enterprise-apps/preflight/sbom@fb73b538f3980292119b5b306ff64383d760a214 # 0.9.0
inputs:
output: sbom.cdx.json
A tag or branch can move; a SHA cannot.
What the job does#
The job lands in the test stage by default, is interruptible: true, and has a timeout: 30 minutes. It runs four steps:
-
Install the app's dependencies:
composer install --no-interaction --no-progress --prefer-dist --no-scripts --ignore-platform-reqsThe default image is a composer image, which already ships Composer, so no install step for Composer itself is needed. The SBOM lists what the lock installs, so the app's Composer scripts never run here, and the app's PHP version and extensions are not required.
-
Allow the CycloneDX plugin:
composer global config --no-plugins allow-plugins.cyclonedx/cyclonedx-php-composer true -
Install the plugin globally:
composer global require cyclonedx/cyclonedx-php-composer:^6.2The plugin is installed globally, so the app's
composer.jsonis never touched. -
Generate the SBOM.
--validatefails the job on an invalid SBOM:omit_dev true (default)
composer CycloneDX:make-sbom --output-format=JSON --output-reproducible --validate --omit=dev --output-file=sbom.cdx.jsonomit_dev false
composer CycloneDX:make-sbom --output-format=JSON --output-reproducible --validate --output-file=sbom.cdx.json--omit=devis present only whenomit_devistrue;--output-filetakes theoutputinput (defaultsbom.cdx.json).
Artifacts#
The job publishes the SBOM file as an artifact:
artifacts:
paths:
- sbom.cdx.json
expire_in: 30 days
The path is the output input, and the artifact expires in 30 days.
Inputs#
| Input | Type | Default | What it does |
|---|---|---|---|
stage |
string | test |
Pipeline stage for the job. |
job_name |
string | sbom |
Name of the job. Set it when you include this component more than once. |
image |
string | composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 |
Docker image for the job. |
image_prefix |
string | ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX} |
Registry path in front of image: the job pulls image_prefix/image. The default is the group's GitLab Dependency Proxy, so Docker Hub is asked once and GitLab serves the cached copy. Outside a group with the proxy, set docker.io. No trailing slash. |
omit_dev |
boolean | true |
Whether to omit dev dependencies from the SBOM. |
output |
string | sbom.cdx.json |
Path of the SBOM file to publish, relative to the project root. It must be a relative path; GitLab refuses the pipeline at creation if it is not. |
job_name must match ^[A-Za-z0-9_][A-Za-z0-9_.-]*$.
Verify#
Push the change. The components are ordinary jobs, so the sbom job runs whenever the app's pipeline runs, in the test stage by default. A green job means the SBOM was generated, validated, and published.
Related#
- The composer-audit component: the companion dependency check.
- Include a component twice: the
job_nameinput when one project includes the same component more than once. - When the components run: the
workflow:rulesblock that belongs in the app's own file. - Reference: every component, with its inputs and defaults.