actions/checkout Fork PR Fails: Handle pull_request_target Safely

Separate the two workflow trust models#

These triggers are not interchangeable:

The GitHub secure-use guidance explains why pull_request_target exists and where it becomes dangerous. The event is not automatically unsafe; checking out and executing unreviewed fork code in that context is the dangerous combination.

Use pull_request for ordinary CI#

If the job only needs to compile or test the submitted change, use the lower-privilege event:

1
name: Test pull request
2

3
on:
4
  pull_request:
5

6
permissions:
7
  contents: read
8

9
jobs:
10
  test:
11
    runs-on: ubuntu-latest
12
    steps:
13
      - uses: actions/checkout@v7
14
      - run: npm ci
15
      - run: npm test

The workflow still executes code from the pull request, so it must not receive long-lived secrets or run on a persistent self-hosted runner with access to private infrastructure. The point is that the trigger’s default token and secret boundary is designed for untrusted pull request code.

If the project uses pnpm, replace the install command with the repository’s pinned package-manager flow. The GitHub Actions cache warning guide covers why an untrusted trigger may restore a cache but cannot save to a protected cache scope; that warning is separate from checkout refusal.

Use pull_request_target for metadata-only work#

Many privileged jobs do not need the repository files at all. A labeler, triage workflow, or comment bot can use the event payload and GitHub API without running a checkout step:

1
name: Label pull requests
2

3
on:
4
  pull_request_target:
5
    types: [opened, synchronize, reopened]
6

7
permissions:
8
  pull-requests: write
9
  contents: read
10

11
jobs:
12
  label:
13
    runs-on: ubuntu-latest
14
    steps:
15
      - name: Operate on pull request metadata
16
        run: echo "Use the event payload or GitHub API; do not execute PR files."

The shell step is only a placeholder for a narrowly scoped API operation. Use an action or API client that you have reviewed, keep the token permissions minimal, and do not add npm install, npm test, make, or any command that can load files from a pull request.

This pattern keeps the privileged job from creating a “pwn request.” GitHub’s June 2026 changelog calls out this failure mode and the rollout to supported checkout versions.

Understand the new checkout refusal#

The current actions/checkout README documents allow-unsafe-pr-checkout as an explicit opt-in. A workflow can fail when it contains a ref such as:

1
- uses: actions/checkout@v7
2
  with:
3
    ref: ${{ github.event.pull_request.head.sha }}

The checkout step itself does not execute the fork’s code. The danger begins when a later step runs a Makefile, package script, test command, build hook, configuration file, or dependency from that checkout. Treat a checkout refusal as a security boundary that deserves a workflow redesign, not as a missing YAML flag.

If the job does not need the fork’s files, remove the ref and the checkout. If it needs to test the change, move that work to pull_request or split the workflow into unprivileged and privileged jobs with a clear artifact contract.

If you must inspect a fork, keep it inert#

There are narrow cases where a privileged workflow needs to read a pull request’s files without executing them. For example, a policy checker may inspect text or a diff. In that case, make the risk visible and isolate the checkout path:

1
- uses: actions/checkout@v7
2
  with:
3
    ref: ${{ github.event.pull_request.head.sha }}
4
    path: pr-source
5
    allow-unsafe-pr-checkout: true
6

7
- name: Inspect text only
8
  run: git -C pr-source diff --check

This is not a safe build template. Do not run package managers, compilers, test runners, shell scripts, Docker builds, or language tooling that loads project configuration from pr-source. Do not use a self-hosted runner that can reach internal services. Review the exact permissions and the code path before enabling the opt-in.

GitHub’s guidance says the opt-in is appropriate only after you confirm that the checkout is not executed. The input also does not protect other ways of fetching untrusted code, such as git fetch, gh pr checkout, or downloading an artifact produced by a fork workflow.

Split secret-dependent tests from untrusted tests#

If a test really needs a private registry or deployment credential, separate the concerns:

1. Run normal compilation and tests from pull_request with no secrets.
2. Produce only the data the privileged step needs.
3. Review how that data crosses the trust boundary.
4. Run the smallest trusted operation in pull_request_target or a carefully designed follow-up.
5. Keep artifacts from fork-triggered workflows untrusted until their contents are validated.

Do not “fix” the refusal by moving the entire test job to pull_request_target. That grants a privileged context to every command in the job, including commands introduced by the pull request.

If the only error after changing the trigger is a Node24 runner message, that is a separate runtime issue. actions/checkout v5 and Node24 covers the action-runtime and runner-version boundary; this article covers which pull request code the privileged job is allowed to fetch and execute.

Verify the workflow at the trust boundary#

Before merging a change, inspect the rendered workflow and answer:

1. Which event supplies the workflow file?
2. Which repository and ref does checkout fetch?
3. Does any later command execute files from that checkout?
4. Which token permissions and secrets are available to those commands?
5. Is the runner ephemeral and isolated from private infrastructure?

Test both a same-repository pull request and a fork pull request. Confirm that ordinary CI still reports results, that the privileged metadata job does not check out source, and that a deliberately unsafe checkout fails closed until a reviewer approves the explicit opt-in.

The practical rule is to choose the trigger from the code’s trust level. Use pull_request for untrusted builds, keep pull_request_target metadata-only when possible, and treat allow-unsafe-pr-checkout as a reviewed exception rather than a generic compatibility switch.

FAQ#