GitHub cannot assume the AWS role

Symptom

Diagnostic scenario: Configure AWS credentials fails with the repository’s recorded error, “Not authorized to perform sts:AssumeRoleWithWebIdentity.” No AWS deployment has started.

Read the error first

AWS STS, the service issuing temporary credentials, refused the role exchange. This is Allowed: the role’s trust policy decides who may assume it. It is not a database password or a security group problem. An ECR permission added to the role cannot repair its trust policy.

Decide

flowchart TB
  A[OIDC login failed] --> B{Job can request token?}
  B -->|No| C[Check id-token permission]
  B -->|Yes| D{Correct role and account?}
  D -->|No| E[Correct GitHub variable]
  D -->|Yes| F{Audience and subject match?}
  F -->|No| G[Repair exact trust conditions]
  F -->|Yes| H[Check provider and recent IAM changes]

Likely causes

Check in this order for this symptom; this is a diagnostic ranking, not measured frequency.

1. Wrong subject: publish expects main; deploy expects the dev environment. Immutable repository ids also matter.
2. Wrong role ARN or missing provider in the account selected by the GitHub variable.
3. Wrong audience, missing id-token: write, or a recent IAM change not yet visible.

How to check

Console

GitHub → Actions → failed job: check role selection and environment. IAM → Roles → minitickets-dev-gh-publish or minitickets-dev-gh-deploy → Trust relationships. Both require audience sts.amazonaws.com. Check IAM → Identity providers for GitHub’s issuer.

CLI

export AWS_PROFILE=ticketlite
aws iam get-role --role-name minitickets-dev-gh-publish --query Role.AssumeRolePolicyDocument
aws iam get-role --role-name minitickets-dev-gh-deploy --query Role.AssumeRolePolicyDocument
gh api repos/maheshnd/minitickets/actions/oidc/customization/sub

CloudTrail

Search AssumeRoleWithWebIdentity; compare requestParameters.roleArn, session name, errorCode and errorMessage. On a successful comparison run, inspect only responseElements.audience and responseElements.subjectFromWebIdentityToken. Never export credentials or whole token-bearing records.

Fix

Correct the specific job variable or exact trust condition in infra/src/cicd.ts → createCicd. Publish uses the branch subject; deploy uses the environment subject. Have the owner apply reviewed trust changes before retrying CD.

Prevent

Keep the roles separate and compare subject configuration whenever job context changes. Follow OIDC’s immutable-subject case instead of widening trust to every repository.

Say it in 30 seconds

Say it like this (20-30 seconds)

An AssumeRoleWithWebIdentity failure happens before AWS gives the job credentials. I check which role the job requested, whether it can request a token, and whether the audience and subject match the trust policy. MiniTickets publishes from main but deploys from an approved environment, so those subjects differ. I repair that exact mismatch and keep repository identity checks narrow.

Advanced: Evidence boundaries

AWS documents the recorded subject and audience fields. A failed exchange may have no response fields. Absence of a CloudTrail event alone does not prove a request succeeded or identify a cause. GitHub settings for required reviewers are external to this repository; an environment subject alone does not prove a human approved the job.