Secrets, Configuration Variables, GITHUB_TOKEN, Fine-Grained Permissions, and OIDC: Configuration, Design Choices, and Tradeoffs

1. Secret versus variable versus repository file

Configuration drift is possible whenever a hosted variable can change without a commit. For critical non-secret policy inputs, decide whether repository review is more valuable than operator flexibility.

2. Choose the GitHub identity that actually owns the automation

Do not choose a PAT merely because it “works everywhere.” Its human ownership and often-longer lifecycle are operational liabilities. Conversely, do not build an App for a five-minute personal API experiment if a narrow, expiring fine-grained PAT is appropriate.

3. Workflow-level versus job-level permissions

A workflow-level policy is convenient when every job needs the same GitHub authority. Job-level permissions are stronger isolation when only one job performs a write. A useful pattern is a deny-by-default workflow plus explicit job grants:

permissions: {}

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read

  publish-report:
    needs: test
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write

The test job cannot inherit the write authority simply because another job has it. That matters when a build executes complex toolchains or third-party code but only a narrow reporting step needs to mutate GitHub state.

4. Long-lived cloud secret versus OIDC federation

OIDC does not eliminate authorization policy. It moves the credential source from “stored key” to “verified workload assertion.” A permissive trust policy can still be dangerous.

5. Design a trust policy around immutable repository identity

For a newly created August 2026 GitHub.com repository, start from its actual immutable subject format—not a copied historical name-only subject. The default subject uses one context such as branch or environment. The following provider-neutral policy fixture intentionally shows multiple checks as policy intent; map them to the capabilities of your real provider.

{
  "issuer": "https://token.actions.githubusercontent.com",
  "audiences": ["https://cloud.example.invalid"],
  "subject": "repo:octo-org@123456/octo-repo@456789:environment:production",
  "required_claims": {
    "repository_owner_id": "123456",
    "repository_id": "456789",
    "ref": "refs/heads/main",
    "environment": "production",
    "workflow_ref": "octo-org/octo-repo/.github/workflows/deploy.yml@refs/heads/main"
  }
}

If the provider can bind only sub and aud, use the strongest supported subject and enforce the remaining branch/environment/workflow restrictions inside GitHub through environments, branch protections, and reusable-workflow governance. Never pretend a provider enforces claims it ignores.

6. Git checkout credentials are another persistence boundary

If a workflow checks out source but does not need authenticated Git commands afterward, do not leave credentials available longer than necessary. Current actions/checkout supports persist-credentials: false. This is separate from GITHUB_TOKEN issuance: the token may exist for the job, while checkout decides whether Git credential configuration is persisted for later Git operations.

- uses: actions/checkout@FULL_REVIEWED_COMMIT_SHA
  with:
    persist-credentials: false

Pin the action to a reviewed full commit SHA according to your supply-chain policy. Chapter 18 established why a mutable action tag and an immutable commit reference have different update and compromise tradeoffs.

7. Plan and deployment boundaries

• Personal public lab: use repository secret/variable + explicit GITHUB_TOKEN permissions. This is the mandatory path.
• Private environment workflows: verify the current plan and environment-feature availability before assuming reviewer/wait-timer behavior from Chapter 19.
• Organization configuration: verify organization policy and repository-access selection. Do not assume a Free private repository can consume every organization-scoped value.
• GHES: do not copy GitHub.com's post–July 15, 2026 immutable default subject rollout; verify the server version and OIDC documentation.

8. Worked production decision

A release pipeline needs to read repository metadata, publish one GitHub deployment status, and deploy to a cloud production account. The build job executes a large dependency tree; the deploy job is short.

This design optimizes maintainability (explicit contracts), security (least privilege and no static cloud key), governance (reviewed workflow/environment), reliability (short-lived credentials tied to the run), compatibility (provider-neutral interface), and cost (no paid cloud required merely to learn the model).

Knowledge checks

Lesson summary

Choose configuration by sensitivity and audit requirements, choose GitHub identity by ownership and resource boundary, scope token authority to the smallest job, and use OIDC when a provider can safely exchange verified workflow identity for short-lived credentials. The next lesson diagnoses what happens when any of those boundaries are wrong.

Further reading

• GitHub Docs — GITHUB_TOKEN
• GitHub Docs — Workflow syntax: permissions
• GitHub Docs — Secrets
• GitHub Docs — Variables
• GitHub Docs — OpenID Connect reference
• GitHub Docs — Secure use reference
• GitHub Docs — Personal access tokens
• GitHub Docs — Deciding when to build a GitHub App
• GitHub REST API — API versions