Deploying to AWS with GitHub OIDC
Use GitHub OIDC to obtain short-lived AWS role credentials without storing a long-lived access key. Restrict the role trust policy to the intended audience and repository context, protect deployment environments, and keep role permissions scoped to the exact deployment operation.
Inside this article 5 sections +
OIDC removes the need to store a long-lived AWS access key in GitHub, but it does not decide which workflows should deploy. That decision lives in the AWS role trust policy and the GitHub controls around the accepted identity. A broadly trusted short-lived credential can still be too powerful.
Design one deployment path at a time. For an application deployed to a production AWS account, identify the repository, approved GitHub environment, trusted workflow source, target resources, and required AWS actions. Keep build verification separate from the job that receives deployment authority.
Separate who may assume the role from what it may do
The trust policy answers which federated identity may obtain a session. The role's permissions answer which AWS API calls that session may make. A restrictive permission policy cannot fully compensate for a role trusted by unintended repositories, and a precise trust policy does not justify administrator permissions.
Configure the GitHub OIDC provider in the target AWS account and use the intended audience. For the commonly documented AWS credentials flow, that audience is sts.amazonaws.com. Verify the actual claims generated by the selected GitHub context, especially if organization-level subject customization is enabled.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::111122223333:oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
"token.actions.githubusercontent.com:sub": "repo:example-org/customer-portal:environment:production"
}
}
}]
}
This illustrative trust policy uses a fictional account and repository and assumes the documented environment-shaped subject. Replace them with verified deployment identities before use. A repository or organization using a customized subject must match that actual format rather than copying this string blindly.
Protect the environment that appears in the subject
A job associated with a GitHub environment has a different subject shape from a plain branch job. Do not combine a branch-shaped expectation with an environment job and then loosen the policy to a wildcard when authentication fails. Inspect the identity and align the trust policy with the intended path.
Restrict which branches or tags can deploy to the production environment and configure the review requirements appropriate to the release process. The environment name in a subject is not, by itself, proof that the code was reviewed. The surrounding repository and environment rules establish who can reach that job.
| Context | Expected outcome | Control being tested |
|---|---|---|
| Approved repository and production environment | Role assumption allowed | Exact audience and subject match |
| Same repository, unrelated branch job | Denied | Environment identity boundary |
| Different repository | Denied | Repository scope |
| Unapproved deployment reference | Stopped before privileged execution | Environment branch/tag protections |
| Allowed identity, unrelated AWS resource | AWS action denied | Role permission scope |
Grant token issuance only to the deployment job
The GitHub job needs id-token: write to request an OIDC token. That permission enables token issuance; it does not itself grant AWS permissions. Add only the other GitHub permissions the job needs, such as repository read access when it must obtain trusted deployment configuration.
Use a reviewed credentials action pinned to a verified full commit SHA, or an equivalently reviewed authentication implementation. Resolve the pin from the action's actual release history. Keep the role ARN, AWS region, and target environment explicit, and avoid allowing an untrusted input to select an arbitrary role.
Do not run untrusted pull-request code in the privileged job. Build artifacts and deployment metadata are inputs with a provenance requirement, not automatically trusted because another workflow produced them. Associate the artifact with the reviewed source revision and authorized build run before assuming the role.
Scope the AWS session to the deployment operation
For ECS, distinguish publishing an image, registering a task definition, and updating a particular service. The job may not need all three operations if image publication occurs earlier. Restrict resources and any role-passing authority to the task roles the application is allowed to use.
Keep production and non-production roles separate, preferably aligned with the account boundaries already used by the organization. A staging job should not be able to choose production merely by changing a parameter. Session naming and audit records should identify the repository run and release operation without exposing tokens.
Choose a session duration sufficient for the bounded deployment, and handle expiration explicitly. Short-lived credentials reduce standing exposure, but they can still be used until they expire unless other controls intervene. Removing an old long-lived key should follow a verified cutover so the team knows the new path works before eliminating the fallback.
Do not persist the returned temporary credentials in artifacts, caches, or workflow outputs. Later jobs should authenticate through their own authorized context instead of inheriting a copied session. This keeps the trust decision attached to the job that performs the action and avoids extending credential exposure through diagnostic storage.
When a reusable workflow performs deployment, test the effective identity from a real supported caller. Reuse changes where implementation lives, but the trust policy must still match the identity issued for the calling deployment context.
Test trust changes as security-sensitive configuration
Validate JSON and policy structure locally, then test role assumption in an isolated account or appropriately scoped environment. Exercise both accepted and rejected identities, and confirm that the session cannot modify unrelated resources. Record the effective role and target before mutation so a misrouted deployment fails visibly.
Review trust changes alongside workflow and environment changes. The secrets rotation guide helps retire old credentials, while AWS account boundaries establishes environment ownership. Deployment implementation should deliver a testable authorization boundary, not merely a successful login step.