GitHub is changing the default subject claim used by Actions OpenID Connect (OIDC) tokens. GitHub’s changelog says repositories created after July 15, 2026, and repositories renamed or transferred after that date, use an immutable default subject claim that includes owner and repository identifiers. Existing repositories can opt in. The practical consequence is that cloud trust policies written only for an organization or repository name may need a deliberate review before a deployment succeeds.
This article separates what GitHub documents from operational guidance CodeRiskTools infers from that documentation. CodeRiskTools did not test a production AWS, Azure, or Google Cloud tenant and this checklist is not a guarantee that an OIDC deployment is safe. Treat the live GitHub and cloud-provider documentation as authoritative, preserve a rollback path, and never place long-lived cloud credentials in workflow secrets when short-lived OIDC is appropriate.
What the immutable claim changes
GitHub’s OIDC reference explains that the sub claim identifies the workflow subject. The older default format relied on readable owner and repository names. The documented immutable format adds numeric owner and repository IDs, so a rename or transfer cannot silently make a different repository match a name-based trust rule. GitHub says this format is not available on GitHub Enterprise Server. The exact token shape and rollout details belong to GitHub’s current reference, not a copied snippet in this article.
That is a trust-policy migration, not merely a YAML edit. A workflow may continue to issue a token while the cloud provider rejects it because the provider-side condition still expects the previous subject. Conversely, broadening a condition until the deployment works can create unintended trust. Plan the provider change first, then test a narrowly scoped workflow.
Build an identity inventory before changing policy
| Inventory item | Evidence to capture | Why it matters |
|---|---|---|
| Repository identity | Owner, repository, numeric owner ID, numeric repository ID, and rename/transfer history | Names are readable; IDs are the immutable binding used by the new default. |
| Workflow subject | Event, branch or environment, reusable-workflow context, and intended audience | The subject is assembled from workflow context; do not guess it from a repository name alone. |
| Cloud trust rule | Provider, audience condition, subject condition, and change owner | A successful token request does not prove the provider accepted the intended scope. |
| Migration state | Current format, opt-in setting, test run, and rollback instruction | Separates an observed state from a planned state and prevents emergency widening. |
Six-step migration workflow
- List every OIDC consumer. Find workflows requesting
id-token: write, then map each job to AWS, Azure, Google Cloud, or another provider. Include reusable workflows and deployment environments. - Read the current claim reference. Confirm the repository’s GitHub.com or GHES boundary, the current default format, supported customization, and the audience expected by the provider integration.
- Prepare a narrow provider condition. Add the immutable identity condition alongside the existing rule only if the provider supports a controlled transition. Never replace a precise rule with a wildcard just to make a test green.
- Use a disposable or low-risk environment. Run a workflow with read-only deployment scope and a non-production target. Record the run, commit, event, audience, provider decision, and timestamps without collecting token contents.
- Verify both success and rejection. Confirm the intended repository can authenticate, then test a different repository, branch, or environment is rejected. A positive test alone cannot show that trust is bounded.
- Remove the old path deliberately. After the new condition is observed and reviewed, retire the legacy condition according to the provider’s change process. Keep the prior policy in a private rollback record, not in public logs or source control.
Workflow permissions still define the boundary
OIDC replaces a long-lived credential with a short-lived token exchange; it does not make a workflow trustworthy by itself. Set permissions: explicitly and grant id-token: write only to the job that needs it. Keep checkout, dependency installation, deployment commands, third-party actions, and pull-request inputs in the threat model. A workflow that can mint an OIDC token and then executes attacker-controlled code is still a high-consequence design. Compare this with the GitHub Actions permissions checklist and the safe merge workflow before changing production access.
- Separate untrusted pull-request validation from privileged deployment jobs.
- Pin important actions to reviewed immutable references where your maintenance policy permits.
- Use environment protection and required reviewers for production credentials.
- Keep cloud audience, subject, and repository scope in reviewable configuration.
- Do not print JWTs, cloud responses containing claims, or secret-bearing environment values.
Provider-specific checks
GitHub publishes separate configuration guidance for Google Cloud and Azure. Use the provider-specific audience and subject requirements rather than copying an AWS-shaped example into another platform. For Google Cloud, verify the workload identity provider attribute mapping and the repository condition. For Azure, verify the federated credential’s issuer, subject, and audience. For any provider, record whether the test used the immutable default or a customized subject claim.
Failure modes to catch before production
| Symptom | Likely review question | Safe response |
|---|---|---|
| Token exchange fails after a rename | Does the provider still match the old name-based subject? | Compare the documented current claim and update one narrow condition. |
| Deployment works only with a wildcard | Which exact identity or audience is unknown? | Stop and resolve the missing claim evidence; do not widen trust. |
| Only production fails | Are environment or branch components different? | Compare the complete subject context and test a non-production equivalent. |
| OIDC job runs code from a fork | Can untrusted content execute with token minting permission? | Split the workflow and remove privileged permissions from the untrusted path. |
FAQ
Do all existing repositories need an immediate change?
Not necessarily. GitHub documents automatic behavior for new repositories and renames or transfers after July 15, 2026, while existing repositories can opt in. Inventory first and follow the current reference for your repository state.
Does an immutable subject claim replace environment protection?
No. It improves identity binding. Environment approvals, least-privilege permissions, action pinning, and review of executed code remain separate controls.
Can I log the decoded OIDC token to debug?
Do not publish or retain token contents casually. Capture non-secret metadata and provider error codes, and use access-controlled diagnostics if the provider requires claim inspection.
Is a successful cloud login proof of secure deployment?
No. It proves one configured exchange succeeded. Review the exact workflow diff, permissions, code execution path, and production approval boundary.
Official sources and next step
- GitHub Changelog: Immutable subject claims for GitHub Actions OIDC tokens — rollout and immutable identity announcement.
- GitHub Docs: OpenID Connect reference — current claim formats and customization rules.
- GitHub Docs: OIDC in Google Cloud — provider-specific configuration guidance.
- GitHub Docs: OIDC in Azure — federated credential guidance.
- GitHub REST API: Actions OIDC — documented repository customization controls.
Use the single CodeRiskTools comparison hub for scope context, then start with the free 5-point AI code review checklist. For a local exact-change review workflow paired with secret scanning, inspect the documented scope of the AI Change Firewall; it does not replace GitHub, cloud-provider, or human controls.
Review the trust-policy diff before rollout
Compare the old and proposed provider conditions, workflow permissions, audience, subject context, and rollback path against the final change. A bounded migration is easier to audit than a rushed wildcard fix.
