ADR 002: Generate SLSA Provenance in GitLab Rails backend

Architecture Decision Record for where to generate SLSA provenance statements

Context

SLSA (Supply chain Levels for Software Artifacts) is a security framework that helps ensure the integrity of software artifacts. As part of implementing SLSA Level 3 compliance, GitLab needs to generate provenance statements for artifacts produced by CI/CD pipelines. These statements contain metadata about how an artifact was built, including repository URL, commit SHA, build ID, runner ID, CI/CD variables, and artifact digests.

Currently, SLSA 1.0 provenance statements are generated by Runner helpers. However, this approach doesn’t meet SLSA Level 3 requirements, which specify that provenance must be generated by the control plane (within the trust boundary) and not by a tenant of the build platform.

This ADR documents the decision on where to generate SLSA provenance statements within GitLab’s architecture.

Options Considered

1. Runner Helper (Current Implementation)

Pros:

  • Already implemented.
  • Can track files read and written by the build job (not implemented).
  • Easy setup, enabled by a single CI/CD variable.

Blockers:

  • Not in control plane.

2. Runner

Pros:

  • Can track files read and written by the build job.

Cons:

  • Can’t trust the runner identity. Self-reported runner ID could be falsified.

Blockers:

  • Not in control plane.
  • Has no access to the artifacts, and can’t get their digests. Artifacts are uploaded by Runner helpers.

3. GitLab Rails Backend

Pros:

  • In control plane.
  • Easy deployment, maintenance, and monitoring.
  • Easy setup: provenance generation could be enabled in GitLab UI
  • Compliance: provenance an be enforced regardless of what’s defined in CI/CD configuration.
  • Security: Rails backend can check the runner’s identity.
  • Already has access to necessary metadata (job payload and artifact digests).

Cons:

  • Cannot track files read and written by the build job.

4. GitLab Workhorse

Pros:

  • Already generates artifacts metadata, which are similar to provenance statement.
  • Has access to the artifacts. Workhorse uploads them to object storage, generates their digests, and posts artifact metadata to the Rails backend.

Blockers:

  • Cannot provide all necessary metadata.
  • Cannot verify runner identity in a trusted way.

5. CI/CD Component

Pros:

  • Visibility: advertised in the CI/CD catalog
  • Maintenance: new releases can be published at any time

Cons:

  • Air gap: CI/CD components don’t ship with GitLab, requiring extra setup.
  • Complex setup for users. Users must configure their CI/CD pipelines in order to pass build metadata over to the provenance generation component.

Blockers:

  • Not in control plane.

6. New Service

Pros:

  • Clear trust boundaries.
  • Independent scaling.

Cons:

  • New service to maintain.
  • Additional infrastructure required.
  • Significant integration effort.

Blockers:

  • No direct access to provenance metadata.

Decision

We will generate SLSA provenance statements in the GitLab Rails backend.

This is the only option that satisfies the critical SLSA Level 3 requirement that provenance must be generated within the control plane, and that provides all necessary build metadata.

The Rails backend has access to all necessary metadata to generate complete provenance statements, including:

  1. build ID (from job record)
  2. runner ID (verified by the backend)
  3. build ID (from job record)
  4. runner ID (verified by the backend)
  5. repository URL and commit SHA (from job payload)
  6. CI/CD variables (from job payload)
  7. artifact digests (stored in ci database accessible from backend)

The performance impact of generating provenance statements is expected to be minimal compared to other operations performed by the Rails backend when jobs complete. If needed, provenance generation can be handled by background jobs to further minimize performance impact.

Consequences

Positive

  • SLSA Level 3 compliance is achievable.
  • Provenance generation is integrated with existing GitLab infrastructure.
  • User experience is simplified through GitLab UI configuration.
  • No additional services or infrastructure required.

Negative

  • Cannot track files read by the build job. Tracking these files would make it possible to generate the resolvedDependencies field. However, SLSA L3 requirements state that completeness of that field is best effort.
  • Cannot track files written by the build job. Tracking these fields would make it possible to generate the byProducts field. However, this field isn’t required.

Future Considerations

  • The signing of provenance statements is being addressed separately in issue #537060
  • Future enhancements may explore ways to capture resolvedDependencies and byProducts, potentially through integration with the runner while still generating the provenance in the control plane.
Last modified May 23, 2025: Add ADR 002 to SLSA design doc (4d191521)
View page source - Edit this page - please contribute. Creative Commons License