Uploads one existing CycloneDX JSON or XML BOM using Python's standard library and the Dependency-Track API. The component defines one job, no global stages, workflow, services or variables. Use any stage already declared by the consuming pipeline.
Usage
Store a service API key in the masked DEPTRACK_API_KEY GitLab CI variable. The
key needs BOM upload permission and, when enabled, project creation permission.
Use the API server URL, not the separate frontend URL. HTTPS certificate checks
are enabled; SSL_CERT_FILE can point to the CA bundle for a private service.
stages: [build, check]
include:
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/dependency-track@main
inputs:
stage: check
base-api-url: https://dependency-track.example.com/api
sbom-file: release/application.cyclonedx.json
needs: [build:sbom]
The build:sbom producer must generate the file and publish it as a GitLab
artifact. This component does not generate a BOM or deploy Dependency-Track.
Inputs
| Input | Default | Purpose |
|---|---|---|
name | $CI_PROJECT_NAME | Job suffix for dependency-track:<name>. |
stage | test | An existing consumer stage. |
base-api-url | empty | API URL including /api; falls back to DEPTRACK_BASE_API_URL. |
project-id | empty | Existing project UUID; overrides name/version selection. |
project-name | $CI_PROJECT_PATH | Name used without a project UUID. |
project-version | $CI_COMMIT_REF_NAME | Version used without a project UUID. |
auto-create | true | Create the named project when missing. |
sbom-file | bom.json | One CycloneDX JSON/XML file, at most 20 MiB. |
wait-for-processing | true | Wait for the BOM processing token to finish. |
processing-timeout | 300 | Positive processing wait limit in seconds. |
poll-interval | 2 | Positive polling interval in seconds. |
image | CI Tools python:main | Python 3 image; override to pin an image. |
needs, tags | [] | BOM producer dependencies and runner tags. |
rules | MR/default branch | Override the job scheduling rules. |
Authentication is read only from the environment, never from an input or command argument. Redirects are rejected so the service key is not forwarded elsewhere. Plain HTTP is supported only on local host addresses for isolated tests. Invalid input, HTTP errors, invalid responses and processing timeouts fail the job. Requests are not silently retried after a possibly accepted upload.
Results and migration
The small release/dependency-track.json artifact records accepted or
processed, the BOM size and quality_gate_evaluated: false. It contains neither
credentials, processing tokens nor BOM content. Processing completion does not
prove vulnerability analysis or policy evaluation has completed, and this job
does not implement a vulnerability quality gate.
This is an independent Python implementation addressing the global-stage composition problem in the upstream request. It is not a drop-in replacement for every upstream scanner option: project trees, multi-BOM merging, VEX uploads and risk-score gates are not provided. Generate one complete BOM for each project/version before uploading; repeated uploads to the same project are not merged by this component. Use separate named component instances for distinct projects.
The component CI uses a local HTTP protocol fixture and compiles a pipeline with
only a custom check stage. It verifies upload payloads, processing, failure
propagation and credential isolation without contacting a production service.
Inputs
| Name | Description | Default | Type |
| --- | --- | --- | --- |
| auto-create | Allow Dependency-Track to create the named project if it is missing. | true | boolean |
| base-api-url | Dependency-Track API base URL including /api; defaults to DEPTRACK_BASE_API_URL. | string | |
| image | CI Tools Python image providing Python 3 and trusted CA certificates. | registry.gitlab.com/xrow-public/ci-tools/python:main | string |
| name | Job name suffix. | $CI_PROJECT_NAME | string |
| needs | Producer jobs from which to download BOM artifacts. | [] | array |
| poll-interval | Seconds between BOM processing checks. | 2 | number |
| processing-timeout | Maximum seconds to wait for BOM processing. | 300 | number |
| project-id | Existing Dependency-Track project UUID; overrides name and version. | string | |
| project-name | Project name used when project-id is empty. | $CI_PROJECT_PATH | string |
| project-version | Project version used when project-id is empty. | $CI_COMMIT_REF_NAME | string |
| rules | Rules controlling when the upload job runs. | [{"if":"$CI_PIPELINE_SOURCE == \"merge_request_event\""},{"if":"$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH"}] | array |
| sbom-file | One existing CycloneDX JSON or XML BOM to upload. | bom.json | string |
| stage | Existing consumer pipeline stage for the upload job. | test | string |
| tags | Runner tags. | [] | array |
| wait-for-processing | Wait for BOM processing; this is not a vulnerability or policy quality gate. | true | boolean |