Introduction

GitHub Actions OIDC to AWS fails when the IAM trust policy does not match the token claims GitHub actually sends. Teams often get the OIDC provider created correctly but miss a detail in the trust conditions such as the repository name, branch ref pattern, audience value, or required workflow permission. The result is AssumeRoleWithWebIdentity denial even though the overall architecture is correct.

Symptoms

  • configure-aws-credentials fails with AccessDenied
  • AWS rejects AssumeRoleWithWebIdentity
  • The OIDC provider exists, but deployments still cannot assume the role
  • The workflow works from one branch or repository but not another

Common Causes

  • The trust policy sub condition does not match the repository or branch ref
  • The OIDC provider URL or audience is wrong
  • The workflow does not grant id-token: write
  • The trust policy is too restrictive for the intended trigger pattern

Step-by-Step Fix

  1. 1.Confirm the workflow grants OIDC token permission
  2. 2.Without id-token: write, GitHub cannot mint the token needed for AWS role assumption.
yaml
permissions:
  id-token: write
  contents: read
  1. 1.Check the IAM trust policy subject and audience conditions
  2. 2.The sub claim must match the exact repository and ref pattern GitHub sends for that workflow context.
json
{
  "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:myorg/myrepo:ref:refs/heads/main"
    }
  }
}
  1. 1.Verify the OIDC provider configuration
  2. 2.The provider URL must be token.actions.githubusercontent.com without drift in hostname or audience assumptions.
  3. 3.Retest from the exact branch and workflow context that failed
  4. 4.OIDC trust policies are very sensitive to branch, tag, and repository context. A successful test from one branch does not prove another branch is allowed.

Prevention

  • Treat IAM trust policy conditions as part of workflow configuration, not as a one-time AWS setup
  • Keep branch and repository matching logic documented in the role policy
  • Test OIDC role assumption after any branch strategy or repository rename change
  • Use the narrowest trust conditions that still match your real deployment workflow