Checkpoint Lab — GITHUB_TOKEN, Workflow Permissions, Least Privilege, and API Access

1. Checkpoint charter and authorization ceiling

2. Required predictions before execution

1. The read job can authenticate and read README.md at the run's exact source SHA.
2. The read job cannot be assumed to mutate issues merely because authentication succeeded.
3. The denied job's POST issue request will return 403 and create no issue.
4. The mutation job with issues: write will receive 201 and create exactly one issue.
5. The created issue author may appear as github-actions[bot], while github.actor identifies the workflow initiator.
6. Closing the exact issue number is cleanup; no other issue may be modified.

3. Revision A — preserve the under-privileged denial

Use the full guided workflow from Lesson 2, but stop after denied_write or temporarily omit the mutation job. Dispatch once and preserve:

• workflow/source SHA;
• event and actor;
• run ID and attempt;
• read job contents: read declaration and 200 response;
• denied job issues: read declaration;
• POST /repos/OWNER/REPO/issues status 403;
• X-GitHub-Request-Id, X-Accepted-GitHub-Permissions and rate-limit headers when present;
• proof no issue with the synthetic denied title exists.

4. Diagnose Revision A before repair

YAML parsed, the workflow run exists, the runner executed, authentication was valid enough for earlier API use, and the POST targeted the correct repository. The job requests issues: read, while issue creation requires write. The causal layer is therefore the issue permission.

If your evidence instead shows 410, stop: Issues may be disabled. If it shows rate limiting, address that. The checkpoint only proceeds to a permission repair when the preserved evidence supports that conclusion.

5. Revision B — change only the mutation capability

Add or enable the mutation job with:

mutate_issue:
  needs: denied_write
  runs-on: ubuntu-24.04
  permissions:
    issues: write

Reuse the same request shape, API version, repository, synthetic naming convention, and runner. The only security-relevant change is the requested issue capability on this one job.

6. Execute Revision B and verify the exact effect

Dispatch again. Require:

• read request 200;
• the intentionally denied job still proves 403 under issues: read;
• mutation request 201 under issues: write;
• issue title = ch06-write-<run-id>-<attempt>;
• GET by returned issue number = 200/open;
• close PATCH on that exact number = 200/closed.

The final workflow can contain both the denial-control job and the authorized mutation job. Their different results under different capability declarations are the core experiment.

7. Required evidence packet

8. Trust-context simulation without privileged execution

Do not run the mutation workflow from an untrusted fork for the mandatory lab. Instead, add an architecture note predicting that fork/Dependabot context can downgrade write permissions. Explain why the appropriate design is to keep untrusted CI read-only and move trusted mutations behind a separate reviewed boundary.

If the learner has a safe disposable fork and wants an optional observation, use a read-only workflow only. Do not enable “send write tokens” or introduce pull_request_target merely for this exercise.

9. Record the recursion boundary

The issue create/close actions are repository events caused by GITHUB_TOKEN. Current GitHub behavior generally prevents such events from recursively starting new workflows, subject to documented exceptions. Record this as a limitation: the checkpoint proves issue authorization, not event-chaining behavior.

10. Verification checklist

• Exactly one disposable repository is targeted.
• Top-level permissions: {} remains.
• Read job has only contents: read.
• Denied job has only issues: read and preserves 403.
• Mutation job has only issues: write.
• No token/header/context dump appears in logs.
• Issue title contains run ID + attempt.
• Returned issue number is independently verified.
• Cleanup closes only that issue number.
• No PAT/GitHub App secret/external action/cloud/deployment/self-hosted runner is introduced.

11. Cleanup / rollback

1. Verify the synthetic issue is closed.
2. Keep the closed issue and workflow runs until checkpoint review is complete; they are the audit trail.
3. After review, delete the learner-owned disposable repository if desired. Do not attempt ambiguous “delete latest issue” cleanup.
4. If a repository setting was changed manually outside this checkpoint, restore it explicitly; the mandatory lab itself requires no settings mutation.

12. What Chapter 06 adds to the production operating model

Chapter 06 adds the capability contract: every job has an explicit automation identity, trust context, permission set, resource boundary, token lifetime, API/action request set, expected denial/success behavior, side-effect guard, evidence record, and cleanup/compensation path. Authentication success is not authorization success, and a green job is not proof of the intended repository effect.

Chapter 07 builds on this foundation by separating secrets, environments, variables, redaction, and credential hygiene—where protected values come from and how they should be exposed to only the jobs that need them.

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.