Opscraft
GitHub Actions · Lesson 5 of 10 · 4 min read

Secrets, environments and OIDC

Secrets and variables

  • Secrets at repository, environment and organisation level (org secrets can be limited to selected repos). Masked in logs; not passed to workflows triggered from forks.
  • Variables (vars.*) for non-sensitive configuration.
  • Never echo secrets or write them into artifacts; a transformed secret (base64) isn't masked — use ::add-mask:: for derived values.
Enlarge diagramOrganisation secrets (limit to selected repos)Repository secretsEnvironment secrets: productiononly for jobs with environment: production that passed its rules
Figure 1. Where secrets live. The narrower the scope, the fewer jobs can read them; production secrets belong in a protected environment.
Swipe sideways to see all of it, or tap to open it full screen.

The GITHUB_TOKEN and permissions

Each job gets an automatic, short-lived GITHUB_TOKEN scoped to the repository. Set least privilege explicitly:

permissions:
  contents: read
  pull-requests: write     # only if the job comments on PRs
  id-token: write          # only for OIDC
  packages: write          # only to push to GHCR

Set the organisation default to read-only and grant per workflow/job.

Environments and approvals

Environments (staging, production) add:

  • Required reviewers — a job targeting production waits for approval.
  • Wait timers and deployment branch/tag rules (only main or v* tags can deploy to prod).
  • Environment-scoped secrets and variables — prod credentials only available to jobs that passed the gate.
  • A deployment history per environment.
deploy-prod:
  needs: deploy-staging
  runs-on: ubuntu-latest
  environment:
    name: production
    url: https://shop.example.com
  steps:
    - run: ./deploy.sh prod
Enlarge diagramdeploy-stagingenvironment:stagingwaitingrequiredreviewers, branchrulesapprovedby a reviewerdeploy-prodgets productionsecrets
Figure 2. Environments gate production: the prod job waits for a reviewer and only then gets the production secrets.
Swipe sideways to see all of it, or tap to open it full screen.

OIDC to AWS: no stored access keys

GitHub can issue a short-lived OIDC token for each job; AWS trusts it and returns temporary credentials.

Enlarge diagramJobid-token: writeGitHub OIDCtoken.actions…AWS STSIAM roletrust: sub + audrequest tokensigned JWTAssumeRoleWithWebIdentitysub = repo:acme/orders:…?credentials (about 1 h)
Figure 3. OIDC from GitHub Actions to AWS: no stored keys. AWS checks the token's repo, branch or environment before giving credentials.
Swipe sideways to see all of it, or tap to open it full screen.
  1. Create an IAM OIDC identity provider for token.actions.githubusercontent.com (audience sts.amazonaws.com).
  2. Create an IAM role whose trust policy restricts which repo, branch or environment may assume it:
{
  "Effect": "Allow",
  "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": {
    "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" },
    "StringLike":   { "token.actions.githubusercontent.com:sub": "repo:acme/orders:environment:production" }
  }
}
  1. In the workflow:
permissions:
  id-token: write
  contents: read
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/gha-orders-prod-deploy
      aws-region: ap-south-1
  - run: aws sts get-caller-identity

The sub claim looks like repo:ORG/REPO:ref:refs/heads/main, repo:ORG/REPO:pull_request, or repo:ORG/REPO:environment:NAME. Always constrain it — a trust policy with only the aud condition (or repo:acme/*) lets any repo or branch in scope assume the role. Use separate roles per environment with least-privilege policies. The same pattern works for Azure, GCP, Vault and others.