Release Provenance

Attaching SLSA provenance, build attestations, checksums, and Git tags to every release.

7 min readCI/CD & GitOpsPlatform

What Is Provenance?

Provenance is metadata about how an artifact was built. It includes the source repository, the commit hash, the build system, the build process, and the dependencies used. Provenance answers the question: where did this artifact come from and how was it made?

Without provenance, you have to trust that an artifact was built correctly. With provenance, you can verify it. This is essential for supply chain security — it prevents attackers from substituting malicious builds for legitimate ones.

SLSA Framework

SLSA Level	Requirements
Level 1	Provenance is documented and available
Level 2	Provenance is signed by the build service, hosted platform
Level 3	Build platform is hardened, provenance is non-falsifiable
Level 4	Hermetic, reproducible builds with two-party review

GitHub Build Provenance

GitHub Actions build provenance


jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      id-token: write
      attestations: write

    steps:
      - uses: actions/checkout@v4

      - name: Build artifact
        run: npm ci && npm run build

      - name: Build Docker image
        id: docker
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ghcr.io/myorg/myapp:${{ github.sha }}

      - name: Attest build provenance
        uses: actions/attest-build-provenance@v1
        with:
          subject-name: ghcr.io/myorg/myapp
          subject-digest: ${{ steps.docker.outputs.digest }}
          push-to-registry: true

      - name: Generate SLSA provenance
        run: |
          cat > provenance.json << 'EOF'
          {
            "_type": "https://in-toto.io/Statement/v0.1",
            "predicateType": "https://slsa.dev/provenance/v0.2",
            "subject": [{
              "name": "ghcr.io/myorg/myapp",
              "digest": {"sha256": "${{ steps.docker.outputs.digest }}"}
            }],
            "predicate": {
              "buildType": "https://github.com/actions/workflow",
              "builder": {
                "id": "https://github.com/actions/runner"
              },
              "invocation": {
                "configSource": {
                  "uri": "git+${{ github.server_url }}/${{ github.repository }}@refs/heads/${{ github.ref_name }}",
                  "digest": {"sha1": "${{ github.sha }}"}
                }
              },
              "metadata": {
                "buildInvocationId": "${{ github.run_id }}",
                "startedOn": "${{ github.event.head_commit.timestamp }}",
                "finishedOn": "${{ github.event.head_commit.timestamp }}"
              }
            }
          }
          EOF

      - name: Attach provenance
        run: |
          cosign attest --yes \
            --predicate provenance.json \
            --type slsaprovenance \
            ghcr.io/myorg/myapp:${{ github.sha }}

GitHub's attest-build-provenance action generates SLSA provenance automatically. It signs the provenance with the GitHub OIDC identity and attaches it to the image. The manual SLSA JSON shows what provenance data is captured.

Git Tag Strategy

Automated git tagging


jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Configure git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Create version tag
        run: |
          VERSION=$(jq -r .version package.json)
          git tag -a v${VERSION} -m "Release v${VERSION}"
          git push origin v${VERSION}

      - name: Create GitHub release
        uses: softprops/action-gh-release@v1
        with:
          tag_name: v${{ steps.version.outputs.version }}
          name: Release v${{ steps.version.outputs.version }}
          generate_release_notes: true
          files: |
            dist/*
            sbom.json
            provenance.json

Annotated git tags capture the version and release message. The GitHub release links to the tag and auto-generates release notes from conventional commits. Release artifacts (SBOM, provenance) are attached to the release.

Checksums and Hashes

Generate and verify checksums


jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build artifacts
        run: npm ci && npm run build

      - name: Generate checksums
        run: |
          cd dist/
          sha256sum * > checksums-sha256.txt
          cat checksums-sha256.txt

      - name: Verify checksums
        run: |
          cd dist/
          sha256sum -c checksums-sha256.txt

      - name: Attach to release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            dist/*
            dist/checksums-sha256.txt

Checksums provide a simple way to verify artifact integrity. sha256sum generates hashes for all files, and -c verifies them. Attach checksums to releases so consumers can verify downloads.

Complete Release Workflow

CI runs on every push — lint, test, build, scan.
Merge to main triggers release-please or semantic-release.
Release tool creates a PR with version bump and changelog.
Merge the release PR to trigger the release workflow.
Release workflow builds, signs, generates SBOM and provenance.
Artifacts are published to registries with attestations.
Git tag and GitHub release are created with checksums.

Provenance is not optional

SLSA provenance is becoming a regulatory requirement. The US Executive Order on Cybersecurity, EU Cyber Resilience Act, and FDA medical device guidelines all require software provenance. Start generating provenance now to stay compliant.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Stage 5 · Platform

Build, Version & Release