Skip to content
ScaleBop← Back to app

OIDC token validation

The deploy step uses OpenID Connect (OIDC) — it does not store AWS access keys. It assumes a short-lived deploy role in your AWS account from a trust relationship with your GitHub account. If the deploy job fails at the credential step while trying to assume the role, start here.

The setup itself — the provider, role, and the repository secrets — is documented in Connect GitHub Actions to your AWS account (OIDC). That page’s “If assumption still fails” table maps the three common failure shapes to their fixes. The most common ones are:

  • Could not assume role with OIDC: The web identity token provided could not be validated. — the provider URL or its audience (Client ID list) is wrong. The provider must be https://token.actions.githubusercontent.com with audience sts.amazonaws.com.
  • AccessDenied / Not authorized to perform sts:AssumeRoleWithWebIdentity — the role’s trust sub does not match this run. The policy must contain both subject shapes, repo:ORG/REPO:… (legacy) and repo:ORG@…/REPO@…:… (immutable), or assumption fails.
  • Missing OIDC token / the credential step cannot mint a token — the generated workflow’s permissions block is required. Do not strip it out.

Check in this order

Section titled “Check in this order”

The generated deploy job reads two repository secrets: AWS_DEPLOY_ROLE_ARN and AWS_REGION.

  1. AWS_DEPLOY_ROLE_ARN points at a GitHub OIDC deploy role — not a different role, and not a hand-managed role pointing elsewhere.
  2. The provider URL and audience are https://token.actions.githubusercontent.com / sts.amazonaws.com.
  3. The role trust policy sub allows both subject shapes for this repo (and the branch you are deploying from).
  4. The region in AWS_REGION matches the region where the role and provider live.

If you see one of the three error shapes above, go straight to the “If assumption still fails” table on the OIDC page.

Once the credential step assumes the role successfully, the workflow proceeds to bootstrap and deploy. See CDK bootstrap if the next failing step is the bootstrap check, and Stack rollback for CloudFormation-level failures.