How to Run a Workflow on a Fork Safely in GitHub Actions

By Daniel Zoghalchali·Latchkey

Fork PRs run with a read-only token and no secrets; keep it that way and never run fork code with privileges.

Build and test fork code on the safe pull_request event (no secrets). If you need a privileged follow-up, use pull_request_target but never check out and run the fork's code there.

Steps

• Run untrusted build/test on pull_request (no secrets exposed).
• Keep any privileged step on pull_request_target checked out at the base ref.
• Never execute fork-supplied scripts in the privileged context.

Workflow

on: [pull_request]
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

Gotchas

• pull_request_target checks out the base by default and HAS secrets; running fork code there is the classic exploit.
• Use environment protection rules to require approval before privileged jobs.

Verify it actually works

A workflow that runs is not a workflow that works. Confirm the behaviour on a real event rather than on a manual dispatch, because trigger conditions, permissions, and context values all differ between the two.

# 1. validate the file before pushing
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color

# 2. trigger the real event, not workflow_dispatch
git commit --allow-empty -m "ci: verify trigger" && git push

# 3. watch it and read the conclusion, not just the colour
gh run watch
gh run view --log-failed

What usually goes wrong first

• The workflow file must exist on the default branch before scheduled or dispatch triggers appear at all.
• GITHUB_TOKEN permissions default to read-only in many organisations. Declare a permissions: block listing every scope the job needs.
• Fork pull requests get a read-only token and no access to secrets, regardless of workflow configuration.
• actions/checkout gives you depth 1 on a detached HEAD, so anything needing history or a branch name needs fetch-depth: 0.

Frequently asked questions

Related guides

References

• GitHub Actions documentation