GitHub Actions with AWS
Let GitHub Actions deploy to AWS using short-lived OpenID Connect credentials instead of repository-stored AWS access keys.
Integration boundary
GitHub's OIDC token can be exchanged through AWS STS for a constrained IAM role when the token claims match the role trust policy.
Supported approaches
OIDC role assumption
Recommended for hosted or self-hosted workflows because no long-lived AWS secret is stored in GitHub.
Static access keys
Supported by tooling but creates a rotation and exfiltration burden; avoid for new deployments.
Prerequisites
- GitHub OIDC provider configured in AWS IAM
- An IAM role with a narrowly scoped trust policy
- Workflow id-token: write permission
- Pinned or reviewed actions
Implementation
Constrain the trust policy
Match the expected repository and branch, tag or environment in the token subject; validate the audience.
Grant workflow token permission
Set id-token: write and the minimum repository permissions required by the job.
Configure credentials
Use the official AWS credentials action to request the selected role and region.
Verification
Print caller identity
Confirm account and assumed-role ARN without exposing credentials.
aws sts get-caller-identity
Test an untrusted ref
Verify that a branch or repository outside the trust condition cannot assume the role.
Review CloudTrail
Confirm role sessions are attributable to the expected workflow context.
Common failure modes
- Trust policy accepts every repository or branch
- Workflow lacks id-token permission
- Forked pull request reaches a privileged deployment job
- Third-party action is referenced by a mutable tag
Related engineering templates
Follow GitHub Actions and Amazon Web Services failures and fixes
A useful digest about twice a week with new error references, tools, integration notes and production lessons. No daily noise.