Replace GitHub Actions cloud secrets with OpenID Connect federation

Source facts: federation replaces storage, not authorization design

GitHub’s OIDC guidance says Actions workflows can access a cloud provider without storing long-lived cloud credentials as GitHub secrets. The cloud is configured to trust GitHub’s OIDC provider; a workflow requests a signed JSON Web Token, presents it to the provider, and receives a short-lived access token for that job.

The job or workflow needs id-token: write to request the OIDC token. GitHub explicitly notes that this setting alone does not grant permission to modify GitHub or cloud resources. The cloud trust relationship and the permissions attached to the resulting cloud identity determine what the job can do.

GitHub requires at least one trust condition so an untrusted repository cannot request access to the organization’s cloud resources. Claims such as issuer, audience, subject, repository, ref, and environment can define that boundary. GitHub recommends environment protection rules when environments participate in the OIDC policy and recommends the cloud provider’s official action for the token exchange when available.

The current OIDC reference adds an operational detail for GitHub.com: repositories created after July 15, 2026 use an immutable default subject containing owner and repository IDs. Older repositories retain the prior name-based format unless they opt in, while later renames and transfers move to the immutable form. That rollout does not apply to GitHub Enterprise Server. Trust-policy migration must match the actual subject format.

DSE recommendation: write the trust statement before the workflow

For each deployment, state in plain language: “this repository, from this branch, tag, reusable workflow, or protected environment, may assume this cloud role for this purpose.” Translate that statement into exact GitHub claims and cloud conditions. Reject wildcard organization trust and broad repository patterns unless a documented design truly requires them.

1. Inventory reusable credentials. Find cloud keys in repository, organization, and environment secrets; workflow files; runner configuration; external secret stores; deployment scripts; and copied runbooks. Map each to the workflows and cloud actions that use it.
2. Inspect the real token shape. Determine issuer, audience, subject format, repository and owner IDs, ref, environment, and reusable-workflow context for a controlled run. Account for repository age, rename, transfer, and the GitHub.com versus Enterprise Server boundary.
3. Create a narrow cloud role. Limit trust to the approved claims and permissions to the required resource and action. Separate production from test, deployment from administration, and read from write. Keep token lifetime no longer than operationally necessary.
4. Protect the path to the token. Restrict workflow and environment changes through branch protection, CODEOWNERS or equivalent review, environment reviewers, and limited repository administration. Pin third-party actions to reviewed immutable commits where the risk warrants it.
5. Test positive and negative cases. Prove the approved branch or environment can deploy. Prove a pull request, fork, wrong branch, unprotected environment, different repository, and unauthorized resource cannot. Confirm cloud audit logs identify the federated principal and GitHub run.
6. Revoke the old secret. Remove it from GitHub and runners, revoke it at the provider, search for copies, observe scheduled and rarely used workflows, and preserve rollback through a controlled break-glass process rather than restoring the shared key.

Monitor failed token exchanges, unexpected subjects, role assumptions outside deployment windows, denied cloud actions, changes to trust policies, and workflows newly granted id-token: write. Review the design after repository transfer, rename, environment change, workflow reuse change, or cloud-role expansion. Federation reduces secret exposure and rotation burden, but a broad trust rule can turn any compromised workflow inside its scope into a credential mint. The security value comes from making that scope both narrow and observable.

Keep an emergency revocation procedure that disables the cloud trust relationship without requiring a repository change. Test that action and the recovery approval path so a compromised workflow can be contained even when GitHub administration is unavailable.

Official references

• GitHub Docs, Configuring OpenID Connect in cloud providers, living documentation reviewed August 11, 2026.
• GitHub Docs, OpenID Connect reference, including immutable subject-claim behavior effective July 15, 2026.