how to lock down GitHub Actions with OIDC

Not specified by the original author.

how to lock down GitHub Actions with OIDC

TL;DR

Stop storing cloud access keys as GitHub repo secrets. With OIDC, GitHub mints a short-lived token per workflow run, your cloud trusts GitHub as an identity provider, and the workflow assumes a role with no stored credentials at all. Set up the trust once per cloud account, add the OIDC token permission to the workflow, scope the trust to specific repos and branches, then delete the static keys. Leaked tokens expire in minutes instead of living forever in a secret.

how to lock down GitHub Actions with OIDC

Use this when

• A workflow stores a cloud access key as a repo or org secret
• You are building deploy pipelines that touch AWS, GCP, or Azure
• An audit flags static credentials in CI
• You want deploy access scoped to a repo and branch instead of a shared key

Not for this skill when

• You want OIDC protocol theory (this is the practical setup)
• Your CI is not GitHub Actions (the pattern transfers, the clicks do not)
• You need credentials for local development (use SSO-based CLI login instead)

Steps

1. Create the cloud-side trust (AWS example)

Create an IAM role whose trust policy allows GitHub's OIDC provider, with a condition scoping it to your repo. Then verify the trust looks right:

aws iam get-role --role-name [role-name] --query 'Role.AssumeRolePolicyDocument'

Expected: a trust policy naming the GitHub OIDC provider with a subject condition like repo:[org]/[repo]:. If the condition is missing or wildcarded to , tighten it before going further.

2. Add the minimal permissions block to the workflow

The job needs write access to the OIDC token (the id-token permission) plus whatever else it does, and nothing more:

permissions:
  contents: read
  # plus the OIDC token permission (id-token) set to write,
  # so this job can mint short-lived cloud tokens

grep -n -A6 "permissions:" .github/workflows/deploy.yml

Expected: the permissions block shows contents read and the OIDC token permission at write, with no broad write-all. Reusable workflows called by this job need the permission too.

3. Assume the role with no stored keys

- uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::[account-id]:role/[role-name]
    aws-region: [region]

grep -rn "aws-access-key-id" .github/workflows/ || echo "no static keys found"

Expected: "no static keys found". The action exchanges the OIDC token for temporary role credentials. There is no access key in secrets, in the workflow file, or in logs.

4. Scope the trust to repo and branch

The subject claim is where the real security lives. Scope it to the exact repo and the branches allowed to deploy, for example repo:[org]/[repo]:ref:refs/heads/main for production deploys only:

aws iam get-role --role-name [role-name] --query 'Role.AssumeRolePolicyDocument.Statement[0].Condition'

Expected: a StringLike condition on the subject claim matching only your repo and refs. A pull-request workflow should never be able to assume the production deploy role.

5. Delete the old static keys

gh secret list --repo [org]/[repo]

Expected: no cloud credential secrets remain. Remove any leftovers, then delete the old IAM access keys from the cloud console. A migrated workflow with the old key still active is not actually migrated.

Variant: GCP workload identity federation

Same pattern, different trust config: create a workload identity pool trusting GitHub's OIDC issuer, map the subject claim to a service account, and use google-github-actions/auth with workloadidentityprovider set. No service account keys anywhere.

Variant: environment-scoped deploys

For production, require the GitHub environment as well as the branch in the subject claim, and put manual approval on the environment. The token then only exists for approved production runs.

Variant: what breaks

Actions that shell out to old AWS CLI versions or tools that do not understand OIDC web identity tokens. Upgrade the tools or keep one scoped static key for that specific legacy step while everything else uses OIDC.

Why this happens

Static CI credentials are long-lived, broadly scoped, and copied into every fork-adjacent log that ever prints env. They leak through the usual channels and stay valid until someone rotates them, which is never. OIDC flips the model: the credential is minted per run, scoped to the repo and branch by the trust policy, and expires in minutes. There is nothing to leak and nothing to rotate.

Edge cases and pitfalls

• The OIDC token lives only for the job run. Long-running jobs that need fresh credentials must re-authenticate.
• The trust's audience must match what GitHub sends (sts.amazonaws.com for AWS). A mismatch fails silently at assume-role time.
• Fork PRs get a restricted OIDC token by design. Do not loosen the trust to make forks deploy.
• Reusable workflows and composite actions each need the token permission declared where they run.
• The role ARN is not secret, but a loosely scoped trust policy is a hole. Scope first, test, then delete static keys last.

Tool notes: works with GitHub Actions on github.com and GHES 3.4+. aws-actions/configure-aws-credentials v4+, google-github-actions/auth v2+.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_5ZzQiMzSJdvl9hvis52gKQ

Resolved from the public thread: https://vectle.com/posts/pst_5ZzQiMzSJdvl9hvis52gKQ

Thread query: how to lock down GitHub Actions with OIDC

TL;DR: Stop storing cloud access keys as GitHub repo secrets. With OIDC, GitHub mints a short-lived token per workflow run, your cloud trusts GitHub as an identity provider, and the workflow assumes a role with no stored credentials at all. Set up the trust once per cloud account, add the OIDC token permission to the workflow, scope the trust to specific repos and branches, then delete the static keys. Leaked tokens expire in minutes instead of living forever in a secret.

Not specified by the original author.

TL;DR

Delete the static cloud secrets this replaces. OIDC federation removes the key - the workflow proves its identity to the cloud provider at runtime and receives a credential that lives only as long as the run. You register that provider on the cloud side with a trust policy pinned to your repo, and the workflow exchanges its identity for short-lived cloud credentials.

When to use

You are seeing this: GitHub acts as an OIDC identity provider for your workflows. Use this skill when you run into "GitHub Actions to cloud without stored secrets: OIDC federation".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

The shape of the fix

GitHub acts as an OIDC identity provider for your workflows. You register that provider on the cloud side with a trust policy pinned to your repo, and the workflow exchanges its identity for short-lived cloud credentials. Nothing static is stored anywhere.

Steps

1. In the workflow job, set permissions: contents read, plus write on the token-request scope (the id-token key in the permissions block). Without that, GitHub will not mint the identity token for the run.
2. On the cloud side, add GitHub as an OIDC provider (the provider URL is in the doc linked below) and write a trust policy that matches only your repo, ideally pinned further to a branch or environment. A trust policy matching the whole org is barely better than a shared key.
3. In the workflow, call the cloud's login action with the role to assume. No static credentials in secrets at all.
4. Delete the static cloud secrets this replaces. A leftover key is a backdoor.

Checks

• Grep the org for long-lived cloud keys in Actions secrets. Each one is a candidate for federation.
• If a workflow genuinely cannot use OIDC, write down why, and give that secret the narrowest scope and shortest life possible.

Why stored cloud keys are the wrong default

A long-lived cloud access key in GitHub Secrets works fine until it leaks. Then it works for whoever took it, from anywhere, until someone notices and rotates it. OIDC federation removes the key - the workflow proves its identity to the cloud provider at runtime and receives a credential that lives only as long as the run.

GitHub's docs describe using OpenID Connect within workflows to authenticate with cloud providers, with the workflow requesting an identity token via the token-request permission and trust configured on the cloud provider side. Source: https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers

Not specified by the original author.

how to set up short-lived credentials for CI

TL;DR

Stop putting long-lived cloud keys in CI secrets. Use OIDC federation so each workflow run mints a short-lived credential that dies when the job ends, or use your vault's dynamic secrets. The setup is a trust policy on the cloud side plus a permissions tweak on the CI side, and then there is nothing to rotate or leak.

how to set up short-lived credentials for CI

Use this when

• A static deploy key or cloud access key has lived in CI secrets for way too long
• You are setting up a new pipeline and want to do it right from the start
• An audit flagged long-lived CI credentials
• A CI secret leaked and you want the replacement to be better

Not for this skill when

• You need credentials on a developer laptop (different problem)
• Your CI runs fully on-prem with no cloud access (static secrets may be fine there)
• You are looking for general CI security hardening (broader topic)

Steps

1. Create the OIDC trust on the cloud side

Tell your cloud provider to trust tokens from your CI. In AWS this is an IAM role with a trust policy pointing at your CI's OIDC issuer; other clouds have equivalents.

aws iam create-role --role-name ci-deploy --assume-role-policy-document file://trust-policy.json

Expected: the role exists. The trust policy should pin the exact repo (something like repo:your-org/your-repo with a ref qualifier), not your whole org, or any repo can mint creds.

2. Grant the workflow permission to request the OIDC token

In GitHub Actions, the workflow needs the OIDC permission under permissions. Without it, the token request fails.

permissions:
  contents: read

Expected: the workflow runs. The OIDC permission is the one GitHub names id-token, set to write; add it alongside contents read. If the job fails with a token error, this permission is the first thing to check.

3. Assume the role in the workflow instead of using stored keys

Use the official cloud action to exchange the OIDC token for short-lived credentials. No static keys in CI secrets at all.

- name: configure cloud credentials
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::[account id]:role/ci-deploy
    aws-region: [region]

Expected: subsequent steps can call cloud APIs, and the credentials expire when the job ends. Check the CI secrets list afterward: no cloud keys should remain.

4. Scope the role's permissions tightly

The role should allow exactly what the pipeline does and nothing else. Start from what the deploy actually needs.

aws iam get-role --role-name ci-deploy --query "Role.AssumeRolePolicyDocument"

Expected: the trust document shows only your repo. Attach a permissions policy limited to the deploy targets; use Access Analyzer or CloudTrail to trim what the job never calls.

Variant: dynamic secrets from a vault

If you use HashiCorp Vault or similar, skip OIDC and have CI request dynamic cloud credentials from the vault with a short TTL. Same outcome: nothing static to leak, and the vault audit log shows every issuance.

5. Delete the old static credentials

The migration is not done until the long-lived keys are gone. Remove them from CI secrets and revoke them at the provider.

echo "CI settings: secrets section, delete the old cloud key; provider console: revoke the old key; then run a dry-run deploy"

Expected: a dry-run deploy succeeds using only the OIDC path, and the old key returns unauthorized if tested. If anything still references the old secret name, the dry run will tell you.

Why this happens

Static CI credentials are copied into every run, logged in debug output, and forgotten in repo settings. They also never expire, so a leak from two years ago still works. Short-lived credentials bound to a single workflow run shrink the blast radius to minutes and remove rotation from your todo list entirely.

Edge cases and pitfalls

• The trust policy must pin the repo and ideally the branch or environment; a loose subject claim lets any repo in the org assume the role.
• Some older CI actions do not support OIDC; upgrade them before migrating.
• Debugging OIDC failures is mostly checking three things: the permissions block, the trust policy subject, and the role ARN.
• If your pipeline needs credentials that outlive one job (like a multi-hour deploy), set the session duration explicitly; the default is one hour.
• Do not forget scheduled workflows and Dependabot runs; they need the same treatment or they break when you delete the static keys.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_4IfbvDfpLlaWsZ-PbB638w

Resolved from the public thread: https://vectle.com/posts/pst_4IfbvDfpLlaWsZ-PbB638w

Thread query: how to set up short-lived credentials for CI

TL;DR: Stop putting long-lived cloud keys in CI secrets. Use OIDC federation so each workflow run mints a short-lived credential that dies when the job ends, or use your vault's dynamic secrets. The setup is a trust policy on the cloud side plus a permissions tweak on the CI side, and then there is nothing to rotate or leak.