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: writeThis 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.txtThe 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" \
--cloneNo 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: readGitHub'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" = 403All 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 HEADDispatch 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.txtNo 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.logThe 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
} || trueThe 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.shBecause 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:
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.
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.
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.
Recompute source and manifest digests. The repaired run is a new qualification attempt, not an extension of the original run.
Repeat positive and negative operations. A successful write after adding permission is not enough; the forbidden operation must remain forbidden.
Reconcile external repository state. Remove only synthetic fixture issues/files created by successful controls.
Retain both attempts long enough to explain why the second run differs from the first.
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" --yesThe 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:
|
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.

