Dependency-Track policy violation fails the CI upload gate

By Daniel Zoghalchali·Latchkey

Your CI uploaded an SBOM (often generated by cdxgen) to Dependency-Track, and after analysis a policy condition (for example a banned license) was violated, so the CI gate that checks project status failed the build.

What this error means

The upload succeeds but the follow-up gate reports policy violations for the project, listing the component and the license (or vulnerability) that breached a policy, and exits non-zero.

Policy violations found for project my-app:
  component: some-lib 1.4.0
  violation: LICENSE - "GPL-3.0" is prohibited by policy
  state: FAIL

Common causes

A component license breaches a Dependency-Track policy

A policy condition of type License (or License Group) matches a component in the uploaded SBOM, producing a FAIL-level violation that your gate treats as a failure.

The gate reads project status too early

If the gate checks policy status before Dependency-Track finishes processing the BOM, it may act on incomplete or stale results.

How to fix it

Resolve or suppress the violation

1. Open the project in Dependency-Track and review the policy violation.
2. Remediate the component, or suppress the violation with a documented reason.
3. Re-run the pipeline so the gate sees a clean policy state.

# generate SBOM then upload to Dependency-Track
cdxgen -o bom.json .
curl -X POST "$DT_URL/api/v1/bom" \
  -H "X-Api-Key: $DT_API_KEY" \
  -F "project=$DT_PROJECT" -F "bom=@bom.json"

Wait for processing before gating

Poll the BOM token/processing endpoint until analysis completes, then check policy status so the gate acts on final results.

# poll until processing is false before checking violations
curl -H "X-Api-Key: $DT_API_KEY" \
  "$DT_URL/api/v1/bom/token/$TOKEN"

Make the gate meaningful

• Fail the build on the severity you actually intend to block, and set it explicitly. A scanner that reports without failing is documentation, not a gate.
• Scan the artifact you ship, not the source tree. A vulnerability in a base image will not appear in a source scan.
• Pin the scanner version and its database snapshot for reproducibility, then update deliberately; a floating database turns an unrelated push into a red build.
• Give the job a way to record accepted risk, or people will disable the gate rather than triage it.

How to prevent it

• Keep Dependency-Track license policies aligned with legal requirements.
• Poll for processing completion before evaluating policy in CI.
• Track suppressions with reasons so exceptions stay auditable.

Frequently asked questions

Related guides

References

• GitHub Actions documentation