GitHub Actions AWS OIDC: Replace Access Keys Without Widening Trust

Replace the credential without widening the trust

Moving a deployment workflow from stored AWS access keys to OpenID Connect is useful security work. The important part is deciding exactly which workflow context may assume which role. A short-lived credential with excessive permissions can still make a damaging change.

This guide is a migration and verification checklist for an existing GitHub Actions deployment. It is deliberately narrower than a general CI/CD security review.

Separate three decisions

Think about the integration in three parts:

1. Identity: which GitHub repository and execution context are making the request?
2. Trust: under which conditions will AWS let that identity assume the role?
3. Permission: what can the resulting AWS session actually do?

OIDC removes the need to keep a long-lived AWS key in GitHub for this deployment path. It does not choose sensible AWS permissions or protect the workflow from unreviewed code. GitHub describes the integration and required token permission in its AWS OIDC guide.

Inventory the current deployment first

Record the workflow files, environments, branches or tags, target AWS accounts, current IAM identity and resources being changed. Include scheduled, manually dispatched and reusable workflows that may share the existing key.

A key named "production" may be used by more than the obvious production workflow. Search references and review credential usage before deciding the migration is complete. Do not print secret values into logs or copy them into the ticket.

Use this inventory to define separate roles where environments need different permissions. A staging job should not gain production access merely because both deploy the same application repository.

Match the subject format your repository actually uses

AWS trust conditions should constrain the token audience and subject to the intended identity. Avoid a broad wildcard over every repository or deployment context. Follow the AWS IAM instructions for GitHub's OIDC provider.

There is an easy trap when copying an older example: GitHub documents an immutable subject format for repositories created after July 15, 2026, or repositories that opt in. Environment-based subjects also differ from branch-based subjects. Verify your repository's actual subject format using GitHub's current OIDC reference, then write the condition to match it.

Inspect claims only through your approved diagnostic process. Do not log or upload an entire identity token. A useful review records the expected claim shape and the conditions being enforced, without retaining a usable token.

Keep AWS permissions tied to deployment actions

Start from the resources and operations your deployment needs. Separate permission to authenticate from permission to publish an image, update a service or change infrastructure. Where wildcard resources are unavoidable for a particular API, document why rather than defaulting the whole role to administrator access.

Treat the role's trust policy and its permission policies as different review items. A perfectly constrained repository identity does not make an overly broad permission policy safe.

Give role sessions an identifiable name so operators can relate AWS activity to a workflow run. Avoid putting personal data or secrets in those names.

Run a read-only identity check before a deployment

The official configure-aws-credentials action exchanges the workflow identity for AWS credentials. Pin the action to a reviewed full commit and use its documented inputs for your AWS environment. Keep the required id-token: write permission scoped to the job that needs it.

Start the migration with an identity check:

aws sts get-caller-identity \
  --query '{Account:Account,Arn:Arn}'

Verify that the returned account and assumed-role identity are the intended ones. This proves authentication, not deployment correctness. Follow with the smallest representative action in a test environment before moving the production workflow.

Do not paste an example workflow wholesale into production. Preserve your existing artifact review, environment approval and deployment gates.

Test both permission and denial

A useful acceptance checklist contains negative tests as well as a successful run:

• The intended protected deployment context can assume the expected role.
• A different repository or disallowed branch cannot assume it.
• A job that only builds or tests does not receive deployment credentials.
• The role can perform the required deployment operations.
• An unrelated write operation is denied.
• Audit events can be connected to the workflow run.

Run denial checks in a controlled test setup without weakening the production policy to make testing easier. Review how pull requests, forks and reusable workflows are handled before allowing them anywhere near production credentials.

Retire the old key after the migration is proven

Switch one known deployment path at a time. Once all legitimate callers use the new path, disable the old credential through your normal access-change process, observe for missed dependencies, and remove it according to your retention policy. Do not keep an active administrator key as an undocumented rollback plan.

If the old credential was exposed, handle it as an incident instead of waiting for a routine migration window.

For help turning this into a reviewed change, talk to InstaDevOps about your deployment pipeline. We can scope the trust policy, least-privilege role, migration sequence and acceptance evidence. The objective is a deployment your team can explain and operate, not just one more green workflow run.