GITHUB_TOKEN, Workflow Permissions, Least Privilege, and API Access: Diagnostics, Failure Modes, and Production Practices

1. Preserve the first denied request before changing permissions

When a write returns 403, keep the original run ID/attempt, workflow/source SHA, event/actor/fork state, job permission block, method/endpoint, API version, status, GitHub request ID, accepted-permission hint, and rate-limit headers. Do not rerun with broader privileges first; that destroys the clean comparison.

run_id: 123456789
attempt: 1
event: workflow_dispatch
job: denied_write
requested_permissions: issues=read
request: POST /repos/OWNER/REPO/issues
status: 403
x-github-request-id: ...
x-accepted-github-permissions: issues=write
repository_effect: none

2. Evidence-first diagnostic sequence

flowchart TD
    A[Preserve run / attempt / response] --> B[Confirm event + repo + SHA]
    B --> C[Read workflow + job permissions]
    C --> D{Auth status class}
    D -->|401| E[Token presence / format]
    D -->|403| F[Scope / policy / fork / rate limit]
    D -->|404| G[Resource identity or hidden access]
    D -->|2xx| H[Verify exact repository effect]
    F --> I[Check accepted-permission + rate-limit headers]
    I --> J[Apply smallest permission/policy correction]
    J --> K[Rerun same request]
    K --> H

3. Failure mode: permissions: write-all

write-all may make an error disappear, but it converts diagnosis into privilege escalation. A job that creates an issue does not need write authority over Actions, contents, deployments, packages, pages, statuses, attestations, or other capabilities.

Use endpoint documentation and response permission hints to grant the narrow key, then repeat the same request.

4. Failure mode: using a PAT when GITHUB_TOKEN suffices

A PAT can make a same-repository permission failure disappear because it brings a different identity and policy surface. That also changes audit ownership, lifetime, revocation, cross-resource reach, recursion behavior, and secret-storage requirements. It is not a neutral troubleshooting step.

Only move to a GitHub App/PAT when the desired operation genuinely lies outside GITHUB_TOKEN's repository/resource capability or needs a deliberately different trigger identity.

5. Failure mode: assuming a requested write is granted on forks

For normal fork pull-request events, requested writes are typically downgraded to reads unless an administrator has explicitly enabled sending write tokens. Dependabot runs receive fork-like restrictions. A mutation that succeeds on workflow_dispatch may therefore be denied on a fork PR with identical source.

Do not “solve” this by running fork code under pull_request_target with a privileged token. That event executes in the base repository context and can expose powerful authority if untrusted code or artifacts are used unsafely.

6. Failure mode: leaking token-bearing headers

Debugging with curl -v, set -x, whole environment dumps, or copied HTTP transcripts can expose the bearer token. Automatic masking is not a substitute for safe logging, especially after transformations.

# Safe diagnostic shape: do not print Authorization.
status=$(curl -sS -D response.headers -o response.json -w '%{http_code}' \
  -H 'Accept: application/vnd.github+json' \
  -H "Authorization: Bearer $GH_TOKEN" \
  -H 'X-GitHub-Api-Version: 2026-03-10' \
  "$URL")
printf 'status=%s\n' "$status"
grep -i -E '^(x-github-request-id|x-accepted-github-permissions|x-ratelimit-remaining|retry-after):' response.headers || true

7. Failure mode: giving deploy credentials to build jobs

Build/test code frequently processes untrusted inputs and third-party dependencies. If it does not need deployment authority, it should not receive deployment credentials, OIDC issuance rights, package writes, or broad repository writes. Separate build evidence from mutation/deploy authorization into later jobs with explicit dependencies and policy gates.

8. Failure mode: retrying 403 as though it were a flaky network response

A 403 may represent insufficient permission, policy, fork downgrade, primary/secondary rate limiting, or another deliberate denial. Blind retries can worsen rate limiting and hide the true cause.

9. Intentionally broken example and causal repair

Broken job:

jobs:
  create_lab_issue:
    runs-on: ubuntu-24.04
    permissions:
      issues: read
    steps:
      - name: Create issue
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          # POST /repos/$GITHUB_REPOSITORY/issues
          # Expected first result: 403

Evidence points to issues=write. Repair only that line:

permissions:
  issues: write

Keep event, repository, endpoint, request body, runner and all unrelated settings constant. A new 201 plus exact issue verification demonstrates causal repair.

10. Production diagnostic checklist

1. Preserve first-failure run/attempt and response.
2. Confirm exact event/fork/Dependabot state and source/workflow SHA.
3. Read the job's explicit permission block.
4. Confirm API method/resource/API version.
5. Inspect status and safe response headers.
6. Separate permission/policy from auth, rate limit, network, runtime and resource-ID failures.
7. Apply the narrowest change.
8. Rerun the same request and verify the exact side effect.
9. Restore/close only the disposable resource created by the lab.

Knowledge check

Official references and version notes

• GITHUB_TOKEN concept — current token issuance, repository scope, lifetime, and workflow-trigger behavior.
• Use GITHUB_TOKEN for authentication in workflows — current examples for authenticating API/action requests and minimizing token permissions.
• Workflow syntax — permissions — current permission keys, workflow/job scope, calculation order, fork adjustment, and permissions: {} behavior.
• Managing GitHub Actions settings for a repository — current repository default workflow-permission settings and organization inheritance.
• Authenticating to the REST API — current bearer authentication and versioned REST request guidance.
• REST API — issues — current requirements for reading/creating/updating issues; issue creation requires Issues repository permission write for fine-grained/App-style tokens.
• Troubleshooting the REST API — current 401/403/404 diagnostics and X-Accepted-GitHub-Permissions guidance.
• Triggering a workflow — current recursion prevention when events are created with GITHUB_TOKEN and documented exceptions.
• Events that trigger workflows — current fork pull-request token/secrets restrictions and event trust boundaries.
• Dependabot on GitHub Actions — current read-only token/secrets restrictions for Dependabot-triggered runs.
• Secure use reference — least-privilege guidance, untrusted-input boundaries, and the fact that actions can access github.token.
• About authentication to GitHub — current recommendation to prefer built-in GITHUB_TOKEN in Actions and GitHub Apps for broader/cross-repository automation.