PS Product SecurityKnowledge Base

GitLab Release Evidence

Release Evidence Chain

Intro: Release evidence is where the pipeline stops being a transient execution log and becomes a durable record. For security teams, this matters because a good release story is not only “the pipeline was green”. It is also “here is exactly what was built, tested, scanned, approved, and released.”

What this page includes

  • what GitLab release evidence captures and why it matters
  • how to preserve artifacts so evidence remains useful
  • practical GitLab snippets for tagging releases and collecting evidence snapshots

Working assumptions

  • auditability should be a by-product of engineering flow, not a separate ritual at the end of the quarter

What release evidence is for

Release evidence is a JSON snapshot associated with a GitLab release. It can include release metadata, linked milestones, and report artifacts from the relevant pipeline.

This is useful for:

  • external and internal audits;
  • release retrospectives;
  • proving that specific controls were executed;
  • reducing ambiguity when people ask “what exactly went live?”

What makes evidence valuable

Evidence only helps if the pipeline has preserved meaningful artifacts.

Artifact type Why it matters
test reports proves basic verification happened
SAST / DAST / SCA reports shows security controls were executed
SBOM or dependency report supports supply-chain review
signed package or image metadata ties the release to a verified build artifact
changelog or release notes explains intent and scope
approval data shows that risky releases were deliberately authorized

Design rule: keep the proof alive long enough

If your security jobs write artifacts but those artifacts expire before evidence is collected, the release record will be weaker than it should be.

Use artifact retention intentionally:

artifacts:
  paths:
    - rspec.xml
    - semgrep.json
    - zap/zap.html
  reports:
    junit: rspec.xml
  # Pick a retention period that fits your audit and incident-review needs.
  expire_in: 30 days

Minimal tag-and-release pattern

create_release:
  stage: release
  image: registry.gitlab.com/gitlab-org/cli:latest
  script:
    - >-
      glab release create "$CI_COMMIT_TAG"
      --ref "$CI_COMMIT_SHA"
      --notes-file CHANGELOG.md
  rules:
    - if: $CI_COMMIT_TAG

This works well when:

  • tags are your release boundary;
  • release notes are generated or maintained as code;
  • package and security checks have already passed.

Collect an extra evidence snapshot

GitLab collects release evidence automatically when the release is created, but it can also collect an additional snapshot later through the API.

collect_release_evidence:
  stage: release
  image: registry.gitlab.com/gitlab-org/cli:latest
  needs: [create_release]
  script:
    - >-
      glab api -X POST
      "/projects/$CI_PROJECT_ID/releases/$CI_COMMIT_TAG/evidence"
  rules:
    - if: $CI_COMMIT_TAG

Use an additional snapshot when:

  • some artifacts become available only after initial release creation;
  • you want evidence after a downstream verification step;
  • you need a new point-in-time record for compliance or change control.

A more complete release job with attached assets

create_release:
  stage: release
  image: registry.gitlab.com/gitlab-org/cli:latest
  needs:
    - package_image
    - security_gate
    - zap_baseline
  script:
    - |
      glab release create "$CI_COMMIT_TAG"         --ref "$CI_COMMIT_SHA"         --notes-file CHANGELOG.md         --assets-links='[
          {"name":"Container image digest","url":"https://registry.example.com/product-api@'$IMAGE_DIGEST'"},
          {"name":"SBOM","url":"https://gitlab.example.com/$CI_PROJECT_PATH/-/jobs/$CI_JOB_ID/artifacts/file/sbom.json"},
          {"name":"ZAP HTML report","url":"https://gitlab.example.com/$CI_PROJECT_PATH/-/jobs/$CI_JOB_ID/artifacts/file/zap/zap.html"}
        ]'
  rules:
    - if: $CI_COMMIT_TAG

What a security team should verify before trusting the evidence

  1. The release was created from the correct ref or tag.
  2. Artifacts belong to the expected pipeline and commit.
  3. Security jobs were not skipped silently.
  4. Artifact retention is long enough for audit and incident-review needs.
  5. Evidence snapshots are collected after the right control points.

Good pairings

Release evidence becomes much stronger when combined with:

  • Security Quality Gates and Release Blocking
  • signed images and commits from the snippets branch;
  • protected environments and manual production approval;
  • SBOM retention and provenance metadata;
  • a changelog that maps release scope to issues or milestones.

Common mistakes

Mistake Why it hurts
creating releases without preserved artifacts evidence has very little to point to
treating evidence as an audit-only feature teams miss its operational value during incidents or rollbacks
collecting evidence before security outputs exist snapshot is incomplete
relying on mutable external links only future investigators cannot reconstruct the release cleanly

Author attribution: Ivan Piskunov, 2026 - Educational and defensive-engineering use.

Use this page with