A cloud deployment secret stored in GitHub can outlive the job that needs it, accumulate permissions, and become difficult to retire because several workflows depend on it. OpenID Connect offers a different approach: a workflow presents its identity, the cloud provider evaluates a trust policy, and the accepted job obtains temporary credentials for a defined role.
The security outcome depends on that trust policy and the workflow around it. Replacing a secret with a broadly trusted identity can preserve the original exposure in a different form. This documentation-led GitHub Actions OIDC migration plan was researched on October 19, 2026. We have not executed it in your repository or cloud account. Treat the examples as acceptance criteria to adapt and test, not a universal configuration recipe.
What OIDC changes, and what it does not
GitHub’s OIDC documentation describes exchanging a workflow identity for short-lived cloud credentials. Your cloud provider must decide which identities it trusts and which permissions the resulting session receives. OIDC does not decide whether the deployment is safe, whether a dependency is trustworthy, or whether a production change has business approval.
Think of three distinct controls: the workflow’s ability to request an identity token, the cloud’s decision to accept that identity, and the role’s authorization to change resources. Test each separately. A successful token request is not proof that the cloud role is narrowly scoped, and a successful deployment is not proof that an unintended workflow would be rejected.
The useful migration result is therefore a documented boundary: the intended deployment context can perform its required task; inappropriate contexts cannot assume the role; credentials stay out of durable artifacts; and the replaced credential is retired after its consumers are accounted for.
Inventory the old credential before changing the workflow
Identify the secret by its management identifier, not its value. Record its cloud principal, permissions, location in GitHub, known consumers, rotation owner, and current deployment purpose. Never paste the credential into a ticket, prompt, screenshot, or test log. Your inventory needs evidence of ownership and use, not another copy of the secret.
Look beyond the obvious production workflow. Reusable workflows, environment-level secrets, organization-level secrets, maintenance jobs, release processes, and disaster-recovery procedures may share the same credential. Ask the owners to confirm dependencies. Where permitted, use cloud audit evidence to understand actual use, while recognizing that a quiet observation period does not prove a credential is unused.
Separate unrelated jobs before migration. If one credential performs deployment, infrastructure maintenance, and data export, do not simply reproduce that combined permission set in a single new role. Define the pilot’s job narrowly and leave other consumers explicitly tracked until their own migration decisions are made.
Write a rollback plan that does not require exposing the old secret. Define who can authorize rollback, which change would be reverted, and when the old credential becomes permanently unavailable. Rollback is a temporary operational decision, not a reason to retain an unnecessary credential indefinitely.
Define the deployment identity the cloud should accept
Describe the trusted context in ordinary language first: this repository, this approved deployment environment, this workflow or reusable workflow where supported, and this release path. Then map those requirements to the claims and policy conditions supported by the actual cloud integration. Have both the repository owner and cloud identity owner review that mapping.
GitHub’s AWS OIDC guide discusses audience and subject restrictions and environment considerations. Subject formats and repository behavior can change; current documentation includes changes affecting some repositories created in 2026. Do not copy a subject string from an old blog post and assume it describes the token your repository now receives.
Inspect identity metadata through a supported diagnostic method in a controlled context. Avoid printing raw identity tokens into shared logs. Record the relevant claim names and expected values, their provenance, and the exact policy conditions used. If you cannot establish what a claim means for your configuration, stop the migration at that boundary and resolve it before allowing production access.
Avoid broad wildcard trust unless a reviewed requirement genuinely needs it and the resulting exposure is understood. A repository name alone may not express the release boundary you intended. Consider untrusted contributions, branch changes, environment protections, reusable workflow relationships, and repository administration as part of the trust design.
Keep role permissions separate from trust permissions
A trust policy answers who may obtain the cloud role. The role’s permissions answer what that accepted identity can do. Document both. A perfectly constrained subject still receives excessive power if its role can administer unrelated resources.
Build a permission worksheet from the actual deployment: resources it reads, resources it changes, supporting service operations, and any required delegation. Where the provider supports resource and condition restrictions, evaluate them against the real task. Do not treat a successful broad administrator-role pilot as the final authorization design.
Consider the blast radius of the deployed artifact as well. Permission to update an application can affect the data and identities that application reaches. Infrastructure changes may create new credentials or access paths. Review meaningful indirect consequences rather than measuring least privilege only by the number of policy lines.
For the broader allocation of cloud duties, use our cloud shared-responsibility guide. In this migration record, name the person responsible for cloud trust, role authorization, workflow integrity, and production acceptance; “the cloud handles it” is not an ownership assignment.
Harden the workflow that requests the identity
Grant token-request permission only where the job needs it. In GitHub Actions, id-token: write permits requesting an OIDC token; it is not itself blanket write permission over cloud resources. Keep the workflow token’s other permissions similarly deliberate and document why each job needs them.
Review which code runs before and after credentials become available. An approved cloud trust condition does not make arbitrary shell commands or third-party actions safe. Untrusted inputs, dependency changes, and mutable action references deserve explicit review. GitHub’s secure-use reference is the current starting point for those workflow controls.
Use the platform’s supported deployment environment protections where appropriate. Confirm who can approve a deployment, change its rules, modify the workflow, or administer the repository. An approval step that an untrusted contributor can bypass does not provide the intended boundary.
Ensure temporary credentials and identity tokens are not copied into build artifacts, caches, command traces, support bundles, or job outputs. Masking is not a substitute for avoiding unnecessary disclosure. Keep diagnostic evidence focused on identity, policy decisions, resource changes, and timestamps rather than bearer material.
Pilot an allowed job and deliberately rejected contexts
Start with a nonproduction resource and an explicit test matrix. One row should show the intended workflow assuming the intended role and completing the smallest useful deployment action. Another should show that the role cannot perform an unrelated operation that falls outside its authorization.
Add negative identity tests reflecting the threat boundary: an unapproved branch or environment, a different repository, or another workflow context where the integration distinguishes it. Use authorized test repositories and safe resources. Do not probe other organizations or attempt to evade their controls.
For each case, record the expected decision, observed result, policy version, repository context, cloud role, timestamp, and relevant audit-event identifier. A rejected deployment can fail for many reasons. Confirm that a negative identity test failed at the intended trust control, not merely because a later command referenced a nonexistent resource.
Repeat the accepted case after tightening permissions. This catches an easy migration error: the first broad policy works, the final policy is never exercised, and the team discovers missing access during production release. Use the saved policy and workflow revisions to make the evidence reproducible.
Retire the long-lived credential only after consumer reconciliation
Compare the original consumer inventory with the migrated workflows. Ask each owner to confirm that the new identity path is saved and used, not simply prepared in a branch. Remove the secret from the locations that no longer need it, and disable or revoke the underlying cloud credential through the provider’s supported process once remaining consumers are resolved.
Deleting a GitHub secret does not, by itself, invalidate the corresponding cloud key. Conversely, revoking the cloud key without accounting for another consumer can interrupt a critical job. Record both sides of retirement and the service checks performed afterward.
Check scheduled and infrequent jobs explicitly. A monthly maintenance task may not run during a short pilot. Either exercise it safely, migrate it independently, or retain a visible exception with an owner and a retirement decision date. Do not label the migration complete while an undocumented shared dependency still uses the old identity.
Keep secret-scanning alerts and incident procedures available for any credential believed to have been exposed. OIDC migration does not undo historical disclosure or replace investigation. Our software supply-chain guide provides related dependency context, but this record should prove the credential’s own disposition.
Failure modes that defeat the intended improvement
Any workflow can assume the role. The trust conditions are broader than the release policy. Repair the claim-to-requirement mapping and rerun both accepted and rejected cases.
OIDC is enabled everywhere. Unrelated jobs can request tokens, increasing the contexts you must reason about. Review job-level needs and reduce permissions where supported.
The cloud role still grants administrator access. The credential lifetime improved, but the authorized action set did not. Narrow the role against a documented task and verify both required and forbidden operations.
The old secret survives as a convenience. The project declares success while retaining the original reusable credential. Keep an explicit exception or complete retirement; do not hide it.
Configuration review substitutes for a running test. The saved files look correct but no deployed job has exercised them. Use the evidence process above and revisit relevant security misconfiguration checks after changes.
Revisit the test matrix when repository ownership, deployment environments, reusable workflows, or cloud roles change. Those changes can alter the accepted identity boundary even when the application deployment command remains exactly the same.
Frequently asked questions
Does OIDC remove every secret from a deployment?
No. It can replace a particular long-lived credential used for cloud authentication. Other services, package sources, signing operations, and application runtime credentials need their own supported identity decisions.
Can we copy one cloud policy into every repository?
Do not assume that is safe. Claims, environments, supported conditions, and required permissions vary. Reuse a reviewed pattern, but validate the actual identity and task for each deployment boundary.
Is successful deployment enough evidence?
No. Include a trusted-context test, meaningful rejected contexts, limited authorization, token-handling checks, and proof that the replaced credential is no longer active where retirement was intended.
Make the trust boundary the deliverable
Choose one deployment, document its old credential and required actions, and implement the narrowest supported trust path. Demonstrate what works and what is rejected, then retire the replaced credential with consumer evidence. The useful result is not an OIDC checkbox; it is a tested boundary and an accountable maintenance record.
