Add the OIDC role next to the existing key, switch one workflow at a time, watch CloudTrail for the old key going quiet, then disable and later delete it. Running both side by side removes the risk of a failed cutover.
What changes and what does not
Today your pipeline reads a secret access key from the CI secret store. After the move, the job asks the CI platform for a signed token, exchanges it with your cloud for temporary credentials, and uses those. The permissions of the role stay the same unless you choose to tighten them. Only how the job proves who it is changes.
The AWS best practices page supports the direction: require workloads to use temporary credentials with IAM roles, and use a web identity token exchange for workloads outside AWS such as managed CI/CD platforms.
Plan
- Inventory. List every pipeline and repository that uses the key. Search secret stores, workflow files and runner environment variables. Use the key's last used information to confirm which services it touches.
- Create the identity provider. In AWS, add an OIDC provider for your CI platform. For GitHub the provider URL is
https://token.actions.githubusercontent.com, and the audience issts.amazonaws.comwhen using the official action. - Create the role. Copy the permissions the key's user has, then plan to trim them. Write a trust policy with exact matches on audience and subject. GitHub's guide says to define at least one condition.
- Grant the workflow permission to ask for a token. Set
id-token: writein the workflow or job. GitHub notes this does not grant write access to other resources. - Switch one low risk workflow. Use the official configure credentials action with
role-to-assume. Leave the old secret in place and unused. - Verify. Run the workflow and confirm in CloudTrail that the role assumption appears and the old key shows no new activity for that job.
- Repeat for each workflow, starting with pull request checks and ending with production deploys.
- Quiet period. Watch the old key's last used date for a full release cycle.
- Disable, then delete. Disable the key. If nothing fails after another cycle, delete it and remove the secret from the platform.
Things that go wrong
- Subject mismatch. The most common failure. Compare the token's subject to the trust condition. GitHub says repositories created after 15 July 2026 use an immutable subject format, and renames and transfers also move to it, so copy the format from current documentation.
- Deploys using environments. A job that references an environment presents the environment subject, not the branch. Your trust policy must match that.
- Role chaining. If your tooling assumes a second role, AWS caps the chained session at one hour.
- Long jobs. Credentials expire. Split long jobs or raise the role's maximum session duration to what you need, not the ceiling.
- Forgotten consumers. Another system, such as a scheduled job, may use the same key. The last used date will show you.
Tighten while you are here
Once the role works, generate a policy from CloudTrail history with Access Analyzer and replace the broad policy. Our post on trimming a CI role covers the steps.
Rollback
Because the old key is still enabled during the migration, rollback is a one line change back to the secret. That is the point of not deleting early.
Quick check
Do I need to rewrite my pipeline to use OIDC?
Mostly no. You add a token permission and a login step, then keep the same CLI and deploy commands.
When can I delete the old key?
After a quiet period of at least one release cycle with no use, and after disabling it for another cycle without failures.
Safeguard does not manage your cloud accounts. It scans your code and dependencies, applies pull request policies and gates, and automates compliance evidence. Free scan: gold.safeguard.sh/scan.
Sources
- AWS IAM User Guide: Security best practices in IAM
- GitHub Docs: OIDC in Amazon Web Services
- GitHub Docs: OpenID Connect reference
- AWS IAM User Guide: Roles terms and concepts
Last reviewed: 19 October 2026.
