Skip to content
compiler.dev
Start free

What Is OIDC in GitHub Actions?

Last updated

OIDC (OpenID Connect) in GitHub Actions is a way for a workflow to prove its identity to a cloud provider and receive short-lived credentials, so you do not store long-lived access keys as repository secrets.

How it works

Each job can request a signed JSON Web Token (JWT) from GitHub. The token contains claims about the run: the repository, branch or tag, environment, workflow and more. You configure your cloud (AWS, Google Cloud, Azure and others) to trust GitHub's token issuer and to accept tokens only when their claims match rules you set, for example "repository is acme/api and branch is main".

At run time the job exchanges the token for temporary credentials, usually valid for an hour or less. They expire on their own, so a leaked log line is far less dangerous than a leaked permanent key.

The job needs permission to request the token, which is why workflows using OIDC set id-token: write.

Example

permissions:
  id-token: write   # allow requesting the OIDC token
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-deploy
          aws-region: us-east-1
      - run: aws sts get-caller-identity

The role's trust policy decides which repositories and branches may assume it. A step-by-step setup is in GitHub Actions OIDC with AWS.

Why use it

  • No secrets to rotate or leak.
  • Credentials are scoped to a single run.
  • Access rules can be tied to branch, tag or environment.
  • Cloud audit logs show which workflow assumed which role.

Common mistakes

  • Forgetting id-token: write. Without it the token request fails with a permissions error.
  • Trust policy too broad. A rule that matches repo:acme/* lets every repository in the organization assume the role. Pin the repository and, ideally, the branch or environment.
  • Setting permissions at the top and dropping contents: read. Once you list any permission, unlisted ones default to none.
  • Expecting it on fork pull requests. Workflows from forks do not get write-level tokens or secrets by default.
  • Treating the token as a secret store. It proves identity only. Authorization still lives in your cloud's policies.

OIDC works on any runner, including a self-hosted runner, since the token comes from GitHub, not the machine. More hardening tips are in securing GitHub Actions.

Related terms

FAQ

Does OIDC replace all secrets?

No. It replaces cloud access keys. API tokens for third-party services that do not support OIDC still need secrets.

Which clouds support GitHub OIDC?

AWS, Google Cloud and Azure all document it, as do HashiCorp Vault and many other tools. Check your provider's docs for exact setup.

Is it safe for pull requests?

Restrict trust policies to specific branches or environments so pull request code cannot assume deploy roles.

Related