Workflow Triggers and GITHUB_TOKEN Permissions

What pull_request, pull_request_target, workflow_run, schedule and dispatch events check out, which secrets and token permissions they get, and how to write a deny-by-default permissions block.

The problem

A workflow labels pull requests from forks and works fine in testing, then fails in production with `Resource not accessible by integration` because the token it received was read-only. Another workflow runs on `pull_request_target` and checks out the PR head to run tests, which hands a fork's code the repository's secrets. The trigger decides which commit the workflow file comes from, whether secrets exist, and how powerful the `GITHUB_TOKEN` is, so choosing a trigger is a security decision before it is a convenience.

How it works

  • `pull_request` runs the workflow file from the PR's merge commit: `GITHUB_SHA` is the last merge commit and `GITHUB_REF` is `refs/pull/N/merge`; the head commit is `github.event.pull_request.head.sha`. Default activity types are `opened`, `synchronize` and `reopened`, and the workflow does not run while the PR has a merge conflict.
  • For fork PRs, per the docs, secrets are not passed except `GITHUB_TOKEN`, which is read-only; Dependabot PRs are treated as if they came from a fork. On public repositories, by default all first-time contributors need a maintainer's approval before workflows run. Fork code can edit the workflow file itself, which is why withholding secrets is the control, not trusting the YAML.
  • `pull_request_target` uses the base repository's default branch for both the workflow file and an `actions/checkout` without `ref`. It receives secrets and a read/write token, runs even with merge conflicts and regardless of fork approval settings, and is meant for labeling and commenting. Older GHES releases (before 3.20) use the base branch of the PR instead. The pwn request appears when a step checks out the PR head and runs it.
  • Token permissions are computed in order: the enterprise/organization/repository default, then workflow-level `permissions`, then job-level `permissions`, and finally, for a fork PR event other than `pull_request_target`, every `write` is lowered to `read` unless the repository enabled "Send write tokens to workflows from pull requests". The restricted default is `read` for `contents` and `packages` only; the permissive default is read and write for all. Repositories created in a personal account start restricted; repositories created in an organization inherit its setting, and an organization that picked restricted disables the permissive option for its repositories.
  • Setting any scope in `permissions` sets every unlisted scope to `none`, and `permissions: {}` disables all of them. Levels are `read`, `write` and `none` (`write` includes `read`), except `id-token`, which accepts only `write` or `none`. Shortcuts are `read-all` and `write-all`. Put `permissions: {}` or a minimal block at the top of every workflow and grant extra scopes per job, so a compromised step in one job cannot use another job's scopes.
  • `workflow_run` fires when another workflow is requested or completed, regardless of its conclusion, so filter on `github.event.workflow_run.conclusion`. It runs from the default branch and "is able to access secrets and write tokens, even if the previous workflow was not", which makes it the sanctioned bridge from an unprivileged PR build to a privileged comment step. Artifacts from the triggering run are untrusted data. Chains stop early: in the docs' example A to F, workflows E and F do not run.
  • `workflow_dispatch`, `schedule` and `repository_dispatch` only work from the default branch's copy of the file (the "Run workflow" button appears only then). `schedule` runs the default branch, has a 5-minute minimum interval, is delayed at the start of every hour under load, and in a public repository is disabled after 60 days without repository activity. `repository_dispatch` limits `event_type` to 100 characters and `client_payload` to 10 top-level properties and 65,535 characters.
  • Events created with `GITHUB_TOKEN` do not start new workflow runs, with the exception of `workflow_dispatch` and `repository_dispatch`; on github.com the docs add that `pull_request` runs (`opened`, `synchronize`, `reopened`) for a PR created or updated by the token are created but wait for approval by a user with write access (a rollout that is not documented for GHES as of 2026-10). A bot that opens a PR with the default token therefore does not get CI on it automatically; use a GitHub App token or a personal token for that, and `merge_group` needs its own trigger or required checks never report on queued merges.

Examples

Deny-by-default token: `permissions: {}` at the top, `contents: read` for the test job, and `pull-requests: write` only for the comment job, which skips fork PRs where the token would be read-only. actionlint 1.7.12 clean.

yaml
name: least-privilege
on:
  pull_request:
  push:
    branches: [main]
permissions: {}
jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
      - run: npm ci && npm test
  comment:
    if: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}
    needs: test
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - run: gh pr comment "$PR" --repo "$REPO" --body "tests passed"
        env:
          GH_TOKEN: ${{ github.token }}
          PR: ${{ github.event.pull_request.number }}
          REPO: ${{ github.repository }}

A safe use of `pull_request_target`: it never checks out or executes PR code and only calls the API with values passed through `env`. actionlint 1.7.12 clean; the trigger's runtime behavior is per the docs, not run here.

yaml
name: label-pr
on:
  pull_request_target:
    types: [opened, reopened, synchronize]
permissions: {}
jobs:
  label:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - name: Label by size using only the API
        env:
          GH_TOKEN: ${{ github.token }}
          PR: ${{ github.event.pull_request.number }}
          REPO: ${{ github.repository }}
        run: |
          files=$(gh api "repos/$REPO/pulls/$PR/files" --jq 'length')
          if [ "$files" -gt 50 ]; then
            gh pr edit "$PR" --repo "$REPO" --add-label "size/large"
          fi

The privileged half of the two-workflow pattern. A separate unprivileged workflow named `build-pr` runs on `pull_request` and uploads `report.json`; this one reads it as data only. actionlint 1.7.12 clean, not run here.

yaml
name: report-pr
on:
  workflow_run:
    workflows: [build-pr]
    types: [completed]
permissions:
  actions: read
  pull-requests: write
jobs:
  comment:
    if: ${{ github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v8
        with:
          name: report
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ github.token }}
      - name: Treat the artifact as data, never execute it
        env:
          GH_TOKEN: ${{ github.token }}
          REPO: ${{ github.repository }}
          PR: ${{ github.event.workflow_run.pull_requests[0].number }}
        run: |
          failed=$(jq '.stats.failures' report.json)
          gh pr comment "$PR" --repo "$REPO" --body "failures: $failed"

In practice

  • GitHub Actions — Defines the token model: default permissions from enterprise, organization and repository settings, narrowed by `permissions:` and lowered to read-only for fork pull requests.
  • actions/labeler — Labels pull requests from file globs; documented usage with `pull_request_target` is safe only because it reads the configuration from the base branch and never runs PR code.
  • Dependabot — Its pull requests are treated like fork PRs, so secrets and write tokens need a separate Dependabot secrets store rather than repository secrets.
  • actionlint — Type-checks `on:` filters, `permissions:` keys and `${{ }}` expressions, and flags untrusted inputs used inside `run:`.
  • GitHub merge queue — Runs the required checks against a temporary merge group ref, which only works if the workflow listens for `merge_group`.

Trade-offs

Pros

  • A deny-by-default `permissions:` block limits what a compromised step can do
  • Fork PRs run without secrets, so outside contributors cannot exfiltrate them
  • `workflow_run` separates untrusted building from privileged reporting
  • Defaults can be tightened once per organization instead of per workflow

Cons

  • Read-only tokens on fork PRs break comment and status steps that worked on same-repo PRs
  • Every job needs its own permission block, which is easy to forget when copying workflows
  • `pull_request_target` is easy to misuse and a common source of supply-chain incidents
  • Default-branch-only triggers cannot be tested from a feature branch before merging

← All CI/CD & GitOps entries