Protect the path from pull request to release

A build has two outputs: bytes and claims about those bytes. An attacker can change either, or arrange for a deployment job to consume different bytes from the ones reviewed. Start by asking who controls each input and which job can publish, sign, or deploy. Source code, test scripts, dependency installation hooks, workflow definitions, action references, restored caches, and downloaded archives can all execute or influence execution. Reviewing application code while ignoring those paths leaves the release boundary incomplete.

Consider the fictional Acorn service. A fork pull request runs tests on worker P. A merge to main runs a fresh build on worker R. Production accepts an image digest after a separate verification job. Worker P is deliberately outside the release trust boundary even when its tests pass. Test success answers whether assertions passed under those conditions; it says nothing about the contributor's authorization to issue a production release. Worker R must start from the approved immutable commit and resolve protected build inputs. Rebuilding a pull request after merge is a cost worth accepting when an earlier artifact came from a less trusted path.

GitHub's secure-use guidance supports minimal token permissions and immutable action references. Those choices are necessary but not sufficient. A read-only repository token does not remove a runner's cloud credentials, network access, or writable shared disk. Separate contribution workers from release workers, give a signing identity only to the job that needs it, and constrain the external identity trust policy to the repository, workflow and protected release context. An environment approval does not sanitize an already compromised worker.

The workflow below shows the pattern to remove. pull_request_target runs with the base repository token and secrets, write-all grants every scope, the checkout fetches the fork head commit, and the persistent self-hosted release runner keeps whatever the contributor script leaves behind. actions/checkout v7, since 2026-06-18, and the floating v2 to v6 major tags, since 2026-07-20, refuse that checkout unless allow-unsafe-pr-checkout: true is set. A SHA pin taken before that date does not get the guard, and run: steps that fetch the head with git or gh are not covered at all.

name: Test
on: pull_request_target
permissions: write-all
jobs:
  test:
    runs-on: [self-hosted, release]
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}
      - run: ./ci/test.sh

The repair runs the same tests on pull_request, which gives fork pull requests a read-only token and no secrets. It also sets contents: read explicitly, uses a GitHub-hosted runner that is discarded after the job, and pins checkout to the full commit SHA of v7.0.1 with the version in a comment. persist-credentials: false stops checkout from leaving the token for later steps; v6 and later store it under $RUNNER_TEMP instead of .git/config, where any step can still read it.

This job only runs tests; it does not publish. A distinct release workflow starts on a protected main push, checks out that exact event commit, builds from scratch, and passes an immutable digest to promotion. Repository rulesets and the identity provider trust policy are separate configuration, so this file alone is not evidence that the whole boundary exists.

name: Test
on: pull_request
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - run: ./ci/test.sh

The release workflow runs only for pushes to main. It starts with no token permissions at the workflow level and grants the build job only what attestation needs: id-token: write to obtain the OIDC token that Sigstore binds to the workflow identity, and attestations: write and artifact-metadata: write to store the result. actions/attest then signs SLSA build provenance for the exact file. The release environment can require reviewers and restrict deployment branches, and its name appears in the OIDC subject (repo:acorn/service:environment:release), so a cloud trust policy can require it.

Before promotion, run gh attestation verify dist/acorn.tar.gz --repo acorn/service --signer-workflow acorn/service/.github/workflows/release.yml --source-ref refs/heads/main --deny-self-hosted-runners and deploy the digest it verified. The release-verification project on this page builds and verifies a signed release end to end with the same checks.

name: Release
on:
  push:
    branches: [main]
permissions: {}
jobs:
  build:
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: read # check out the protected commit
      id-token: write # OIDC token that Sigstore binds to this workflow
      attestations: write # store the provenance attestation
      artifact-metadata: write # record the attested artifact
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - run: ./ci/build.sh dist/acorn.tar.gz
      - uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-path: dist/acorn.tar.gz

A tag is a movable pointer. In March 2025 an attacker repointed existing tags of tj-actions/changed-files, used by over 23,000 repositories, to a commit that dumped runner memory and printed secrets into public workflow logs (CVE-2025-30066, added to the CISA Known Exploited Vulnerabilities catalog). A full 40-character commit SHA from the action repository itself cannot be moved that way. Keep the release name in a comment, such as # v7.0.1, so reviewers and update tools know what the SHA is.

An immutable pin also freezes out fixes: the July 2026 checkout guard reached floating major tags only. Dependabot and Renovate both update SHA pins together with the version comment; the configuration below groups action updates weekly and waits seven days before proposing a new release. Since 2025-08-15 an enterprise, organization or repository policy can require full-SHA pins, so workflows with unpinned actions fail, and can block a specific action or version by prefixing it with !. Immutable releases, generally available since 2025-10-28, stop a publisher from moving or replacing a release tag and its assets, but floating major tags such as v4 are moved by design.

Run zizmor and actionlint on every workflow change. zizmor flags unpinned actions, dangerous triggers, template injection and credential persistence; GitHub code scanning default setup can also run CodeQL queries for Actions workflows.

version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
    cooldown:
      default-days: 7
    groups:
      actions:
        patterns: ["*"]

Several platform changes since mid-2025 alter what a workflow review should expect. Check each against the workflows and pins you actually run.

Use a small decision table before trying the change on a live service. The release invariant is a conjunction: approved source, expected builder, authenticated statement, matching subject digest, and deployment of that same digest. One false or missing condition prevents ordinary promotion. A signed statement naming main without a commit cannot resolve a branch that moved between approval and build. A matching tag is also insufficient because tags can refer to new bytes later.

For the fixture, the approved source is c111 and the approved image is sha256:aa11; these are deliberately shortened desk-exercise identifiers. Run 72 is a pull-request artifact. Run 73 was produced by the release workflow but used c112, which was not approved. Run 74 satisfies the stated policy. If production fetches a mutable tag after verifying run 74, the check and the use can still diverge. Carry sha256:aa11 into the deployment specification and compare the runtime image identity afterward. Retain the verifier result and policy revision as well as the statement, because future policy changes may otherwise make an old decision impossible to explain.

The builder must be trusted to report its inputs accurately. SLSA provenance supplies structured build evidence; a statement alone does not establish a SLSA level or show that the source is benign. A compromised approved dependency could be reproduced and signed correctly. Application tests, dependency review and incident detection remain relevant, each with a different claim. Evidence about build integrity must not be relabeled as proof of application security. The case studies mark the edges of this boundary: a compromised build server in /domains/supply-chain/builds/case-study-solarwinds/, a downloaded CI tool that sent every job secret to an attacker in /domains/supply-chain/ci-cd/case-study-codecov/, and the repository rules that protect what the build starts from in /domains/supply-chain/ci-cd/source-repository-protection/.

Operating this boundary trades speed and availability for stronger release identity. Clean rebuilds consume time, while a verifier or identity-provider outage can stop promotion. Define a separately authorized emergency process with an exact digest, reason, expiry and post-release review; silently turning verification off changes the policy for every release. In a real validation use synthetic credentials and harmless marker files to test isolation. The fixture below is a desk analysis; it does not run those isolation probes. For hands-on practice, the release-verification project on this page builds, signs and verifies a release, and the lab at /labs/artifact-policy/ has you reject a validly signed release from the wrong producer.

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. GitHub Actions: secure use reference
2. SLSA v1.2: build provenance. v1.2 (approved November 2025).
3. GitHub Docs: script injections
4. GitHub changelog: SHA pinning and blocking in the allowed actions policy (2025-08-15)
5. GitHub changelog: immutable releases are generally available (2025-10-28)
6. GitHub changelog: pull_request_target and environment branch protection changes (2025-11-07)
7. GitHub changelog: safer pull_request_target defaults for actions/checkout (2026-06-18)
8. GitHub changelog: read-only Actions cache for untrusted triggers (2026-06-26)
9. GitHub changelog: Dependabot default package cooldown (2026-07-14)
10. CISA: Supply chain compromise of third-party tj-actions/changed-files (CVE-2025-30066) and reviewdog/action-setup@v1 (CVE-2025-30154). 18 March 2025.
11. actions/attest: generate signed attestations
12. GitHub CLI manual: gh attestation verify
13. zizmor audit rules
14. OWASP Top 10 CI/CD Security Risks: CICD-SEC-9 Improper Artifact Integrity Validation. v1.0 (2022).
15. CISA, NSA and ODNI (Enduring Security Framework): Securing the Software Supply Chain, Recommended Practices Guide for Developers, section 2.4 Harden the Build Environment. August 2022.

Reference information

Tags

CI/CD securityBuild integrity and provenance

SDLC phase

DevelopmentRelease

Role

DevelopersPlatform engineers and SREs

CAPEC attack patterns

• CAPEC-444 at MITRE

Download this guide as Markdown

Continue exploring