Engineer reviewing GitHub Actions YAML where the workflow grants read access to contents and one job grants write access to issues.

A GitHub Actions Workflow Had a Token. Which Permissions Did the Job Receive?

Sat, Nov 21, 2026

A green GitHub Actions job proves that its steps reached a successful conclusion. It does not prove that the job received the GITHUB_TOKEN authority you intended. That distinction matters when a workflow sets permissions globally, a job replaces that declaration locally, unspecified permissions collapse to none, or a pull request crosses a fork trust boundary. GitHub documents each part of that model, but an operational admission decision still has to bind those semantics to the exact workflow revision, event, job, repository settings, API behavior, and evidence produced by the run.

This playbook treats permission validation as a release-gate problem, not as a YAML tutorial. The fixture is deliberately disposable and synthetic. It never asks for production credentials, deployment authority, cloud access, or a real release target. The test oracle is authored before execution; a read operation, denied write, or green step is evidence only when the source identity, runtime identity, event, timestamps, expected case, and observed state all reconcile.

The fixture has not been run. Every proposed runtime result is marked EXPECTED / NOT EXECUTED. The documentation and program details cited here were checked on November 21, 2026.

This playbook covers the token an ordinary workflow job receives. For workflows invoked through workflow_call, see the guide to reusable-workflow secrets and permissions. It covers secret mapping and inheritance, nested workflows, environments, and the rule that permissions cannot increase along a chain of calls.

Define the Exact Operational Acceptance Contract

The contract starts with GitHub's permission-calculation order. The token begins with the applicable enterprise, organization, or repository default. The workflow-level permissions map modifies that baseline. GitHub then applies jobs.<job_id>.permissions. Finally, for a forked pull request event other than pull_request_target, GitHub converts write permissions to read unless the relevant setting permits write tokens.

That order explains why checking whether the token exists is insufficient. GitHub creates a GITHUB_TOKEN for each job. An action can access the job token through github.token even when the workflow author did not explicitly pass ${{ secrets.GITHUB_TOKEN }}. Token availability and token authority are separate questions.

When a workflow or job specifies any entry in a permissions map, GitHub sets omitted permissions to none. A write permission includes read access. Consider this job-level declaration.

permissions:
  issues: write

This job requests issues: write. Its declaration replaces the workflow's permission map and remains subject to higher-level restrictions and event-based reductions. The documented syntax sets contents, actions, checks, and all other omitted permissions to none.

The acceptance contract for this fixture is therefore:

Evidence property

Acceptance requirement

Workflow identity

Exact repository, workflow path, commit SHA, and workflow-file digest are recorded

Job identity

Job name and event match the expected-case manifest

Permission source

Repository default, workflow permissions, job permissions, and event reduction are distinguished

Runtime

Runner label, run ID, run attempt, event name, GITHUB_SHA, start and finish timestamps are recorded

Positive control

An operation requiring an intended permission succeeds

Negative control

An operation requiring a permission that should be absent is denied

State oracle

External post-run inspection confirms that successful writes happened only in cases where they were expected

Fork boundary

Fork identity and event are proven before interpreting a denial

Decision

ACCEPT / REPAIR / RERUN / HOLD is derived only from the complete ledger

A workflow conclusion of success is insufficient by itself. The same problem arises when verifying GitHub Actions matrix coverage. An independent manifest lets you check that each required combination ran, even when other jobs were canceled. Here, each expected combination pairs a permission declaration with a triggering event.

A measurable rejection criterion follows directly. If the workflow SHA, event, job identity, permission declaration, repository setting, expected manifest entry, HTTP result, and independently inspected repository state cannot be associated with the same case, the decision is HOLD. Do not infer a permission merely because an API happened to return a result.

Establish the Runtime Boundary and Build the Disposable Fixture

GitHub REST API version 2026-03-10 was released on March 10, 2026, and was listed as supported on November 21, 2026. GitHub recommends sending the X-GitHub-Api-Version: 2026-03-10 header. The fixture pins that header so a later rerun does not silently change API semantics.

For action dependencies, GitHub's secure-use guidance recommends dependency lockfiles where available and, for repositories that do not use them, full-length commit-SHA pinning for actions. The fixture pins actions/checkout v7.0.1 to commit 3d3c42e5aac5ba805825da76410c181273ba90b1. GitHub lists v7.0.1 as the current v7 patch as of November 21, 2026, with the short commit ID 3d3c42e. The full SHA also appears in GitHub-hosted workflow source.

The fixture uses two repositories because one repository cannot make both permission tests and public-fork tests equally strong. The private repository gives authenticated reads operational meaning: an unauthenticated caller cannot simply obtain the same private resource. The public repository exists only to exercise ordinary public-fork pull-request boundaries. Both repositories are disposable.

Pin and Record the Environment

Before creating the repositories, record the local tool versions and authentication context.

set -euo pipefail

export FIXTURE_REV="gha-token-scope-v1-2026-11-21"
export API_VERSION="2026-03-10"
export OWNER="$(gh api user --jq .login)"
export PRIVATE_REPO="gha-token-scope-lab-$RANDOM"
export PUBLIC_REPO="gha-token-fork-lab-$RANDOM"
export ROOT="$PWD/$FIXTURE_REV"

mkdir -p "$ROOT/evidence"
cd "$ROOT"

{
  printf 'fixture_revision=%s\n' "$FIXTURE_REV"
  printf 'utc_started=%s\n' "$(date -u +%FT%TZ)"
  printf 'owner=%s\n' "$OWNER"
  printf 'private_repo=%s\n' "$PRIVATE_REPO"
  printf 'public_repo=%s\n' "$PUBLIC_REPO"
  printf 'api_version=%s\n' "$API_VERSION"
  git --version
  gh --version
  curl --version | head -n1
} | tee evidence/environment.txt

gh auth status 2>&1 | tee evidence/gh-auth-status.txt

The measurable test is source identity. Before dispatching anything, the committed workflow digest and expected-case manifest digest must be recorded and the worktree must be clean. A dirty worktree, changed manifest, or unknown source SHA is an immediate rejection criterion: HOLD.

Create the two repositories:

gh repo create "$OWNER/$PRIVATE_REPO" \
  --private \
  --description "Disposable GITHUB_TOKEN permission-scope fixture" \
  --clone

gh repo create "$OWNER/$PUBLIC_REPO" \
  --public \
  --description "Disposable fork-boundary GITHUB_TOKEN fixture" \
  --clone

No command in this fixture targets an existing production repository. If either generated name already exists, stop and generate a different name rather than reusing a repository with unknown history.

The workflow-level permission baseline is explicit rather than inherited from mutable repository defaults:

permissions:
  contents: read

GitHub's secure-use guidance recommends minimizing GITHUB_TOKEN permissions and specifically calls a read-only contents default a good security practice, with job-specific increases only where required.

Save the private repository workflow as .github/workflows/token-scope-proof.yml.

name: token-scope-proof

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  workflow_read_baseline:
    name: workflow-read-baseline
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Capture identity
        run: |
          mkdir -p evidence
          {
            echo "case=workflow_read_baseline"
            echo "event=$GITHUB_EVENT_NAME"
            echo "repo=$GITHUB_REPOSITORY"
            echo "sha=$GITHUB_SHA"
            echo "run_id=$GITHUB_RUN_ID"
            echo "run_attempt=$GITHUB_RUN_ATTEMPT"
            echo "runner_os=$RUNNER_OS"
            echo "runner_arch=$RUNNER_ARCH"
            date -u +started=%FT%TZ
          } | tee evidence/workflow-read-baseline.txt

      - name: Positive read control
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          code="$(
            curl -sS -o read.json -w '%{http_code}' \
              -H "Accept: application/vnd.github+json" \
              -H "Authorization: Bearer $GH_TOKEN" \
              -H "X-GitHub-Api-Version: 2026-03-10" \
              "https://api.github.com/repos/$GITHUB_REPOSITORY/contents/README.md"
          )"
          printf 'read_http=%s\n' "$code"
          test "$code" = 200

      - name: Negative write control
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          code="$(
            curl -sS -o denied.json -w '%{http_code}' \
              -X POST \
              -H "Accept: application/vnd.github+json" \
              -H "Authorization: Bearer $GH_TOKEN" \
              -H "X-GitHub-Api-Version: 2026-03-10" \
              "https://api.github.com/repos/$GITHUB_REPOSITORY/issues" \
              -d '{"title":"UNEXPECTED workflow-read write","body":"fixture"}'
          )"
          printf 'issue_write_http=%s\n' "$code"
          test "$code" = 403

  job_issue_write_override:
    name: job-issue-write-override
    runs-on: ubuntu-24.04
    permissions:
      issues: write
    steps:
      - name: Controlled positive write
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          code="$(
            curl -sS -o issue.json -w '%{http_code}' \
              -X POST \
              -H "Accept: application/vnd.github+json" \
              -H "Authorization: Bearer $GH_TOKEN" \
              -H "X-GitHub-Api-Version: 2026-03-10" \
              "https://api.github.com/repos/$GITHUB_REPOSITORY/issues" \
              -d '{"title":"TOKEN_SCOPE_FIXTURE","body":"synthetic disposable evidence"}'
          )"
          printf 'issue_write_http=%s\n' "$code"
          test "$code" = 201

      - name: Omitted contents permission negative
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          payload="$(printf 'should-not-exist\n' | base64 -w0)"
          code="$(
            curl -sS -o denied-content.json -w '%{http_code}' \
              -X PUT \
              -H "Accept: application/vnd.github+json" \
              -H "Authorization: Bearer $GH_TOKEN" \
              -H "X-GitHub-Api-Version: 2026-03-10" \
              "https://api.github.com/repos/$GITHUB_REPOSITORY/contents/unexpected.txt" \
              -d "{\"message\":\"unexpected write\",\"content\":\"$payload\"}"
          )"
          printf 'contents_write_http=%s\n' "$code"
          test "$code" = 403

All outputs above are EXPECTED / NOT EXECUTED. HTTP 200, 201, and 403 are assertions to test, not observations.

Author the Independent Expected-Case Manifest and Preserve Controls

The expected manifest must exist before the first dispatch. It cannot be generated by inspecting the workflow result because that would turn observation into its own oracle.

Save the following manifest as expected-cases.json.

{
  "fixture_revision": "gha-token-scope-v1-2026-11-21",
  "api_version": "2026-03-10",
  "cases": [
    {
      "id": "workflow_read_baseline",
      "event": "workflow_dispatch",
      "workflow_permissions": {"contents": "read"},
      "job_permissions": null,
      "expected_read_http": 200,
      "expected_issue_write_http": 403,
      "status": "EXPECTED / NOT EXECUTED"
    },
    {
      "id": "job_issue_write_override",
      "event": "workflow_dispatch",
      "workflow_permissions": {"contents": "read"},
      "job_permissions": {"issues": "write"},
      "expected_issue_write_http": 201,
      "expected_contents_write_http": 403,
      "status": "EXPECTED / NOT EXECUTED"
    },
    {
      "id": "omitted_permissions_none",
      "event": "workflow_dispatch",
      "job_permissions": {"issues": "write"},
      "documented_contents_permission": "none",
      "operation_level_probe": "PUT repository contents denied",
      "status": "EXPECTED / NOT EXECUTED"
    },
    {
      "id": "fork_pull_request",
      "event": "pull_request",
      "origin": "fork",
      "requested_permissions": {
        "contents": "read",
        "issues": "write"
      },
      "effective_boundary": "write permissions reduced absent write-token setting",
      "expected_read": "allowed as applicable",
      "expected_issue_write": "denied",
      "status": "EXPECTED / NOT EXECUTED"
    },
    {
      "id": "pull_request_target",
      "event": "pull_request_target",
      "expected_context": "base repository/default branch",
      "trust": "privileged; must not execute fork code",
      "status": "EXPECTED / NOT EXECUTED"
    },
    {
      "id": "negative_write_denial",
      "event": "workflow_dispatch",
      "permission": "contents:read only",
      "operation": "create issue",
      "expected": "denied",
      "status": "EXPECTED / NOT EXECUTED"
    },
    {
      "id": "positive_read_control",
      "event": "workflow_dispatch",
      "permission": "contents:read",
      "operation": "GET private README",
      "expected": "success",
      "status": "EXPECTED / NOT EXECUTED"
    }
  ]
}

GitHub documents the omitted-permissions rule directly: specifying one or more entries in a permissions map sets unspecified entries to none. The manifest therefore records contents: none for the job that specifies only issues: write. The proposed PUT /contents denial is an operation-level corroboration; it is not presented as introspection of an undocumented token-permission field.

Preserve a Failing Case Before Repair

The failing case is the write attempted by a job with only contents: read. Its expected denial must not be removed after the first inconvenience.

EXPECTED / NOT EXECUTED: the private-repository README request should succeed, while creating an issue from the same job should be denied. GitHub's token-authentication documentation shows that issues: write is required in its issue-creation example and separately recommends the least required token permissions.

The rejection criterion is not simply "curl returned nonzero." Save the response code and response body. A DNS failure, API outage, invalid token, malformed JSON, or nonexistent repository is not valid evidence of permission denial. The negative case is acceptable only when the authenticated request reaches the intended repository and GitHub returns an authorization denial consistent with the expected missing permission.

A deliberately invalid negative control should also remain visible. This step proves nothing about scope:

- name: INVALID negative control - token merely exists
  env:
    GH_TOKEN: ${{ github.token }}
  run: test -n "$GH_TOKEN"

EXPECTED / NOT EXECUTED: it should be green whenever the token variable is nonempty. Reject that result as a permission test. GitHub explicitly notes that actions can reach github.token; existence does not identify the authority granted to it.

GitHub Actions artifact attestation uses a similar test. Successful verification establishes facts about an artifact's provenance. A separate promotion policy determines whether to accept that artifact. Here, the evidence concerns one job token under a particular event and workflow revision.

Compare Workflow Scope, Job Overrides, and Pull-Request Trust Boundaries

The controlled comparison is strongest when two jobs in the same workflow run differ only in the permission declaration that matters. In the core fixture, the workflow defines contents: read. workflow_read_baseline inherits it. job_issue_write_override declares only issues: write; GitHub's documented rule means omitted permissions in that job become none, rather than inheriting contents: read.

That yields the following predeclared comparison:

Case

Effective model being tested

Expected operation

Status

Workflow read baseline

top-level contents: read

private README GET succeeds

EXPECTED / NOT EXECUTED

Workflow read baseline

issues omitted

issue POST denied

EXPECTED / NOT EXECUTED

Job override

job declares issues: write

issue POST succeeds

EXPECTED / NOT EXECUTED

Job override

contents omitted in job map

contents PUT denied

EXPECTED / NOT EXECUTED

Token-presence-only control

token is nonempty

step succeeds but proves no scope

EXPECTED / NOT EXECUTED

This is the point at which a "green job" becomes counterintuitive. job_issue_write_override can be completely green even though contents: read, present at workflow scope, is no longer part of its declared job map. Conversely, the workflow-level baseline can be green because the denied issue write is the expected negative result. Exit status has meaning only after the expected case is known.

For pull requests, the event becomes part of permission calculation. GitHub documents that, for pull requests from forked repositories, GITHUB_TOKEN is read-only and other Actions secrets are withheld. In the workflow-syntax reference, GitHub is more precise about the calculation order: after default, workflow-level, and job-level adjustments, a forked PR other than pull_request_target has write permissions changed to read when the "Send write tokens to workflows from pull requests" setting is not selected.

For the public fork repository, add:

name: fork-token-boundary

on:
  pull_request:
  pull_request_target:

permissions:
  contents: read
  issues: write

jobs:
  ordinary_pr_probe:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-24.04
    steps:
      - name: Record fork identity
        run: |
          test "${{ github.event.pull_request.head.repo.fork }}" = "true"
          echo "head_repo=${{ github.event.pull_request.head.repo.full_name }}"
          echo "base_repo=${{ github.repository }}"
          echo "head_sha=${{ github.event.pull_request.head.sha }}"
          echo "base_sha=${{ github.event.pull_request.base.sha }}"

      - name: Attempt synthetic issue write
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          code="$(
            curl -sS -o pr-write.json -w '%{http_code}' \
              -X POST \
              -H "Authorization: Bearer $GH_TOKEN" \
              -H "Accept: application/vnd.github+json" \
              -H "X-GitHub-Api-Version: 2026-03-10" \
              "https://api.github.com/repos/$GITHUB_REPOSITORY/issues" \
              -d '{"title":"UNEXPECTED fork write","body":"fixture"}'
          )"
          echo "write_http=$code"
          test "$code" = 403

  target_metadata_only:
    if: github.event_name == 'pull_request_target'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Record trusted base context only
        run: |
          echo "event=$GITHUB_EVENT_NAME"
          echo "repo=$GITHUB_REPOSITORY"
          echo "sha=$GITHUB_SHA"
          echo "pr_head=${{ github.event.pull_request.head.sha }}"
          echo "pr_base=${{ github.event.pull_request.base.sha }}"
          echo "No fork checkout or fork code execution is permitted in this job."

The pull_request_target case deliberately does not check out the contributor's head. GitHub states that pull_request_target runs in the base repository's default-branch context and warns that executing untrusted pull-request material in that privileged context can expose secrets or write authority. GitHub's guidance on securely using pull_request_target explains the distinction. A pull_request workflow can run untrusted contribution code with restricted credentials. A pull_request_target workflow receives privileged base-repository credentials on the assumption that it will run trusted base-branch code.

There is an important date boundary. GitHub's Actions-policy documentation, accessed November 21, 2026, says a default policy blocking pull_request_target in public repositories will be enforced on December 2, 2026. A fixture executed after that date may therefore fail at policy admission before its metadata-only job starts unless the applicable policy permits the event. Do not misclassify that as a token-permission failure.

Reject an Invalid Negative Control

A negative control is invalid when the expected failure can be produced without the permission boundary under test. For example, POSTing to a typoed repository name could produce a 404 even with write permission. Sending malformed JSON could produce a 422 even when authorization is correct. Losing network connectivity could make curl fail before GitHub sees the request.

The valid negative comparison uses the same repository identity and API route as the positive case, differing only in effective permission. workflow_read_baseline expects issue creation to be denied; job_issue_write_override expects issue creation to succeed. Both are EXPECTED / NOT EXECUTED.

For the fork case, record the fork relationship before interpreting the HTTP result. The workflow must prove github.event.pull_request.head.repo.fork == true and preserve the head/base repositories and SHAs. Otherwise a same-repository pull request could accidentally be mistaken for a fork-boundary validation.

The guide to staged and untracked Git build inputs describes a similar evidence problem. An empty default diff covers only one tree comparison. Here, a 403 becomes evidence of the expected permission boundary only after you identify the repository, route, authentication, and event.

Capture Evidence, Reconcile Identity, and Separate Documentation From Observation

Commit the fixture and capture its identifiers before dispatch.

cd "$ROOT/$PRIVATE_REPO"

git add .
git commit -m "Add token scope fixture"

git rev-parse HEAD | tee ../evidence/private-source-sha.txt

sha256sum \
  .github/workflows/token-scope-proof.yml \
  expected-cases.json \
  reconcile.py \
  | tee ../evidence/private-source-sha256.txt

test -z "$(git status --porcelain=v1)"
git push origin HEAD

Dispatch with:

gh workflow run token-scope-proof.yml \
  --repo "$OWNER/$PRIVATE_REPO"

RUN_ID="$(
  gh run list \
    --repo "$OWNER/$PRIVATE_REPO" \
    --workflow token-scope-proof.yml \
    --limit 1 \
    --json databaseId \
    --jq '.[0].databaseId'
)"

printf '%s\n' "$RUN_ID" | tee ../evidence/private-run-id.txt

No run was dispatched for this fixture.

Capture the run and job records with the pinned API version:

gh api \
  -H "X-GitHub-Api-Version: $API_VERSION" \
  "/repos/$OWNER/$PRIVATE_REPO/actions/runs/$RUN_ID" \
  > ../evidence/run.json

gh api \
  -H "X-GitHub-Api-Version: $API_VERSION" \
  "/repos/$OWNER/$PRIVATE_REPO/actions/runs/$RUN_ID/jobs?filter=all" \
  > ../evidence/jobs.json

gh run view "$RUN_ID" \
  --repo "$OWNER/$PRIVATE_REPO" \
  --log \
  > ../evidence/run.log

The external state oracle must inspect the repository after the run instead of trusting the step's own claim. The expected issue should exist exactly once; the prohibited file should not exist:

gh api \
  -H "X-GitHub-Api-Version: $API_VERSION" \
  "/repos/$OWNER/$PRIVATE_REPO/issues?state=all&per_page=100" \
  > ../evidence/issues.json

gh api \
  -H "X-GitHub-Api-Version: $API_VERSION" \
  "/repos/$OWNER/$PRIVATE_REPO/contents/unexpected.txt" \
  > ../evidence/unexpected-content.json 2> ../evidence/unexpected-content.err \
  && {
    echo "REJECT: prohibited content exists" >&2
    exit 42
  } || true

The evidence ledger should be case-oriented:

Case

Expected state

Observation

Required evidence

Decision before run

Workflow-level read-only fixture default

private contents read succeeds

EXPECTED / NOT EXECUTED

run log + run identity

HOLD

Write API attempt under read-only job

issue creation denied

EXPECTED / NOT EXECUTED

HTTP response + no issue

HOLD

Job-level override

issue write succeeds

EXPECTED / NOT EXECUTED

HTTP 201 + issue ID + post-run issue inventory

HOLD

Omitted contents after job override

contents write denied

EXPECTED / NOT EXECUTED

HTTP denial + absent file oracle

HOLD

Positive read API

private README read succeeds

EXPECTED / NOT EXECUTED

HTTP 200 + repository identity

HOLD

Fork pull_request

requested write reduced under applicable default settings

EXPECTED / NOT EXECUTED

fork identity + HTTP denial + settings

HOLD

pull_request_target

base-context metadata job only

EXPECTED / NOT EXECUTED

event + base SHA; no fork checkout

HOLD

Invalid token-presence control

step green but unusable as scope evidence

EXPECTED / NOT EXECUTED

log only

REJECT AS EVIDENCE

Detect Missing Evidence and Duplicates

Evidence completeness is mechanical. Every expected case must have exactly one corresponding record for the chosen run attempt. The reconciling code should reject unknown, absent, or duplicate case identities rather than guessing.

A minimal reconcile.py:

#!/usr/bin/env python3
import json
import pathlib
import sys
from collections import Counter

manifest = json.loads(pathlib.Path("expected-cases.json").read_text())
expected = [c["id"] for c in manifest["cases"]
            if c["event"] == "workflow_dispatch"]

records_path = pathlib.Path("evidence/case-records.json")
if not records_path.exists():
    print("HOLD: missing case-records.json", file=sys.stderr)
    raise SystemExit(10)

records = json.loads(records_path.read_text())
observed = [r["case_id"] for r in records]

counts = Counter(observed)
duplicates = sorted(k for k, v in counts.items() if v != 1)
missing = sorted(set(expected) - set(observed))
unexpected = sorted(set(observed) - set(expected))

print(json.dumps({
    "expected": expected,
    "observed": observed,
    "missing": missing,
    "duplicates": duplicates,
    "unexpected": unexpected
}, indent=2))

if missing or duplicates or unexpected:
    raise SystemExit(20)

The rejection criterion is strict. Missing output is not a successful denial. Duplicate case records are not "extra confidence." A record from a different run attempt, source SHA, or event cannot fill a gap.

Source reconciliation comes next. GITHUB_SHA, workflow source SHA, run ID, and run attempt must refer to the tested workflow execution. For pull_request, GitHub documents that the default GITHUB_SHA refers to the pull request's merge commit, while github.event.pull_request.head.sha identifies the contributor's head. For pull_request_target, GitHub documents GITHUB_SHA as the last commit on the base repository's default branch and GITHUB_REF as the default branch. Recording the wrong SHA therefore changes the meaning of the evidence.

The separation of claim types should be explicit:

Claim

Classification

Status

Workflow/job permissions can alter GITHUB_TOKEN access

GitHub documented semantics

Confirmed in docs

Unspecified permissions become none once a map specifies permissions

GitHub documented semantics

Confirmed in docs

Fork PR write permissions are reduced absent the applicable write-token setting

GitHub documented semantics

Confirmed in docs

pull_request_target runs in privileged base context

GitHub documented semantics

Confirmed in docs

Fixture issue POST will return 403 in the read-only case

Local test expectation

EXPECTED / NOT EXECUTED

Job override issue POST will return 201

Local test expectation

EXPECTED / NOT EXECUTED

The prohibited contents file will remain absent

Local test expectation

EXPECTED / NOT EXECUTED

Any particular runner build, latency, response request ID, or timestamps occurred

Runtime observation

NOT EXECUTED

The same distinction between documented semantics, expected behavior, and observed results applies when diagnosing a missing ID with PostgreSQL ON CONFLICT DO NOTHING RETURNING. In both cases, a documented rule tells you what to test. The outcome still requires evidence from the run.

Bound the Repair, Recovery, and Rerun Protocol

The safest repair is normally a narrower permission declaration. GitHub recommends granting GITHUB_TOKEN the minimum access required. Job-level permissions let each job carry its own rights. If only one job creates an issue, scope issues: write to that job.

A safer shape is:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - run: ./test.sh

  report:
    needs: test
    runs-on: ubuntu-24.04
    permissions:
      issues: write
    steps:
      - run: ./create-report-issue.sh

Because job-level declarations replace the relevant permission map, repeat contents: read in report only if that job genuinely needs it. Do not leave it implicit on the assumption that top-level permissions are additive.

Bound the Scope of the Fix

The measurable repair test is exact equivalence between required operation and requested authority. If a job only needs to read repository contents, adding issues: write, pull-requests: write, actions: write, or a personal access token is outside the demonstrated requirement.

GitHub's documentation also notes that when the built-in GITHUB_TOKEN cannot provide the permissions required by a workflow, a GitHub App installation token or a PAT are possible alternatives. That is not permission to escalate automatically. This playbook's repair boundary ends before designing a broader credential architecture.

pull_request_target requires a different repair discipline. GitHub's secure-use guidance says to avoid the event unless the privileged context is necessary and to avoid combining privileged triggers with untrusted pull-request code. A repair that changes pull_request to pull_request_target merely to restore write access is therefore unacceptable if the job then checks out and executes the fork's head.

There is also a 2026-specific checkout boundary worth recording. actions/checkout v7 adds safer handling for fork pull requests under privileged events and refuses unsafe fork checkout by default for pull_request_target and workflow_run; opting into unsafe checkout requires an explicit input. Do not treat that action-level protection as a substitute for event and permission design, but do pin the action version so the fixture's checkout behavior is attributable.

Recovery follows a bounded sequence:

  1. Freeze the failed run's evidence before editing YAML: run JSON, job JSON, logs, source SHA, workflow digest, manifest digest, event payload fields, repository state, and applicable settings.

  2. Classify the discrepancy. A documented expectation violated with reliable evidence is a REPAIR candidate; incomplete evidence is HOLD; transient collection failure with unchanged source may justify RERUN.

  3. Make one narrow source-control change. Do not alter both the permission declaration and the oracle in the same repair unless the contract itself was wrong and that change is independently reviewed.

  4. Recompute source and manifest digests. The repaired run is a new qualification attempt, not an extension of the original run.

  5. Repeat positive and negative operations. A successful write after adding permission is not enough; the forbidden operation must remain forbidden.

  6. Reconcile external repository state. Remove only synthetic fixture issues/files created by successful controls.

  7. Retain both attempts long enough to explain why the second run differs from the first.

  8. Tear down the repositories after the evidence packet is complete.

Every result in that procedure remains EXPECTED / NOT EXECUTED here.

Assign Ownership and Escalation

Ownership is evidence-specific. The workflow owner owns the declared permission contract. The repository administrator owns repository- and organization-level settings that can constrain or broaden the effective result. The CI/platform owner owns the fixture and evidence collector. The release owner makes ACCEPT / REPAIR / RERUN / HOLD decisions from the reconciled packet, not from a screenshot.

Escalate to HOLD when the observed behavior conflicts with current GitHub documentation, particularly around fork reduction or pull_request_target. GitHub's docs now include a future-dated public-repository pull_request_target policy change effective December 2, 2026. A run before and after that enforcement date may differ at event admission without any change to your workflow file. That is a platform-policy boundary, not evidence that permission YAML changed.

A rerun keeps the source constant. Changing a permission creates a new fixture revision or repair attempt. Tests of Python asyncio.create_task context snapshots use the same discipline. Record the expected state before execution and keep it intact when interpreting later observations.

The teardown commands are intentionally destructive and must be run only against the generated disposable names:

set -euo pipefail

test -n "${OWNER:-}"
test -n "${PRIVATE_REPO:-}"
test -n "${PUBLIC_REPO:-}"

case "$PRIVATE_REPO" in
  gha-token-scope-lab-*) ;;
  ) echo "Refusing teardown: unexpected private repo name" >&2; exit 90 ;;
esac

case "$PUBLIC_REPO" in
  gha-token-fork-lab-) ;;
  *) echo "Refusing teardown: unexpected public repo name" >&2; exit 91 ;;
esac

gh repo delete "$OWNER/$PRIVATE_REPO" --yes
gh repo delete "$OWNER/$PUBLIC_REPO" --yes

The name guards are part of rollback safety. Never replace them with a broad repository-selection command.

Decide ACCEPT, REPAIR, RERUN, or HOLD From Evidence

The decision matrix is intentionally stricter than GitHub's workflow conclusion. It is a local operational policy, not a claim about a built-in GitHub release state.

Evidence state

Decision

Required action

Source/run/event identity matches; every manifest case appears exactly once; positive controls succeed; forbidden operations are denied; external state oracle agrees

ACCEPT

Preserve ledger and close fixture

Complete, attributable evidence proves a permission declaration is broader/narrower than the intended contract

REPAIR

Change the smallest permission surface, create new source revision, rerun all affected controls

Evidence collector or transient run failed, but source, manifest, settings, and event contract are unchanged and no contradictory state was created

RERUN

Preserve failed attempt and repeat qualification

Missing/duplicate evidence; unknown settings; wrong event; source digest mismatch; unexpected mutation; docs conflict with observed behavior; fork identity unproved

HOLD

Resolve ambiguity before any permission or release conclusion

Test has never been run

HOLD

Do not convert expected behavior into observation

The current decision is HOLD. All fixture outcomes remain EXPECTED / NOT EXECUTED. There is no run ID, API response, issue inventory, fork PR, or runner log to reconcile.

The decision flow can be expressed mechanically:

github-actions

The most important operational distinction is between requested and effective permissions. A workflow file expresses a request within GitHub's broader policy calculation. Repository, organization, or enterprise restrictions may prevent requested write authority; a forked pull_request can reduce requested writes; and pull_request_target changes the trust model rather than merely "fixing" a denied write.

The docs also contain a potentially confusing pair of statements that should be read together. Workflow syntax says pull_request_target receives read/write repository permission even for public forks, while the security and event references emphasize that its safety depends on running trusted base-repository code and not executing the fork's contents. These are not contradictory. One describes authority; the other describes the trust assumption that makes that authority tolerable. The forthcoming December 2, 2026 default policy for public repositories adds another admission layer on top.

Check the repository settings before drawing a conclusion about fork pull requests. GitHub documents an administrative exception for sending write tokens to fork pull-request workflows. Private-repository fork settings expose a specific send_write_tokens_to_workflows control. Record the actual setting whenever it changes the expected permission boundary.

The same restraint applies to omitted permissions. The documented fact is strong: omitted keys become none when a map specifies permissions. The proposed contents-write denial corroborates that rule at the operation level, but one failed API call does not independently enumerate every permission on the token. Do not turn a bounded probe into an unsupported guarantee.

Develop the Relevant Skills With Refonte Learning

As of November 21, 2026, Refonte Learning describes its QA Automation Engineering program as a three-month program with a workload of 12–14 hours per week. It covers QA fundamentals, test automation frameworks, automated test-script writing, CI/CD pipeline integration, performance-test automation, security and compliance testing, manual and automated testing practices, and practical QA engineering applications.

The program lists a bachelor's-degree-related prerequisite, describes project-oriented learning, and identifies an educational mentor. It offers a Training Certificate and a Certificate of Internship upon successful completion. Listed career paths include QA Automation Engineer, QA Engineer, and Software Tester.

Engineers seeking broader practice in automated testing and CI/CD integration can review the QA Automation Engineering program. The GitHub documentation linked above covers the specific token permissions and fork behavior tested in this playbook.

For this permission check, retain the fixture revision, SHA-pinned checkout action, REST API version, independent expected-case manifest, positive comparison, valid negative control, external state oracle, fork-event identity, teardown guards, and evidence ledger. Until a run supplies that evidence, the fixture outcomes remain EXPECTED / NOT EXECUTED and the admission decision is HOLD.