GitHub Actions OIDC Immutable Subject Claims: A Migration Guide

GitHub Actions OIDC trust policies often start with a repository name, such as `repo:my-org/my-repo:ref:refs/heads/main`. That worked until repository or organization names could be recycled. A new owner could potentially create the same name and match a cloud policy that trusted only the old text.

GitHub now supports immutable subject claims. Repositories created after July 15, 2026 use a default `sub` format that includes the owner ID and repository ID. Existing repositories keep the older format until an administrator opts in, while repositories renamed or transferred after that date move to the immutable format. The OIDC reference and the rollout announcement describe the behavior.

What changed in the sub claim

The old default identifies a repository by mutable names:

repo:my-org/my-repo:ref:refs/heads/main

The immutable format adds the numeric owner and repository identifiers:

repo:my-org@123456/my-repo@456789:ref:refs/heads/main

The IDs are part of the repository segment. They remain present when you customize the subject claim with additional claim keys. GitHub Enterprise Server does not use this immutable format.

Who needs to act now

Teams creating new repositories after July 15, 2026 should build the new format into cloud trust policies from the start.
Teams with existing repositories can opt in at the repository or organization level after updating their cloud policy.
Teams that rename or transfer repositories should expect the subject claim to change.
Teams using GitHub Enterprise Server should follow its separate OIDC behavior.
Teams using custom subject templates must account for the immutable IDs in the repo segment.

If you already have a general OIDC setup, this is a migration detail rather than a reason to abandon federation. GitDash’s earlier OIDC identity federation guide covers the baseline workflow permissions and cloud login model.

A safe migration sequence

Do not switch the GitHub setting first and repair the cloud policy after production deployments start failing. Update the trust relationship in a controlled sequence.

Inventory every cloud role, service account, Vault policy, and deployment that trusts a GitHub Actions subject.
Record whether each repository is old-format or immutable-format, including repositories that were renamed or transferred.
Create the new exact subject condition in a non-production trust policy first.
Run a workflow that requests an OIDC token and inspect the actual `sub` value used by the cloud login action.
Enable immutable subjects for one repository or a small test group.
Confirm that the cloud exchange succeeds and that an unrelated repository is still rejected.
Roll the policy and repository setting through production with an owner and rollback path.

AWS trust policy example

For AWS, the subject condition must match the value that GitHub puts in the token. The provider-specific syntax differs across clouds, but the value is the same immutable subject string:

"Condition": {\n  "StringEquals": {\n    "token.actions.githubusercontent.com:sub":\n      "repo:my-org@123456/my-repo@456789:ref:refs/heads/main"\n  }\n}

The GitHub AWS OIDC guide shows the surrounding AWS configuration. Keep the repository, ref, owner ID, and repository ID exact. A broad wildcard can make the policy easier to migrate, but it also expands who can assume the role.

Azure, Google Cloud, and Vault

Azure, Google Cloud, and Vault use their own policy syntax, but the subject value still needs the immutable format when the repository uses it.

Azure: match `repo:my-org@123456/my-repo@456789:ref:refs/heads/main` in the federated credential subject.
Google Cloud: compare the assertion subject to the immutable string in the workload identity provider condition.
Vault: bind the role’s subject to the immutable string instead of the old name-only value.

Use one exact branch or environment condition per deployment role where possible. If one role serves many repositories, consider whether repository custom properties or a reusable workflow claim gives you a safer boundary than a broad repository-name pattern.

The workflow still needs the right permission

Immutable claims do not replace the workflow permission that allows GitHub to mint an OIDC token. A deployment job normally needs `id-token: write`, plus the minimum repository permission required by its other steps.

permissions:\n  contents: read\n  id-token: write\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - name: Authenticate with the cloud provider\n        uses: your-provider/login-action@v1

The example is illustrative. Use the provider’s current login action and pin it according to your repository policy. The important pieces are the narrow permissions and the exact cloud-side subject condition.

Common migration mistakes

Updating the trust policy for the new format but forgetting a renamed repository that already changed subjects.
Assuming every existing repository changed automatically on July 15, 2026.
Using a subject wildcard that accepts every repository in an organization.
Customizing the subject template and assuming the IDs disappear from the repo segment.
Testing only token issuance and not the final cloud role exchange.
Mixing GitHub.com and GitHub Enterprise Server assumptions in one policy.

A small OIDC audit checklist

List the cloud roles that trust GitHub Actions.
Map each role to exact repositories, branches, tags, environments, or reusable workflows.
Check the format of the subject claim for each repository.
Add and test immutable subjects before opting in broadly.
Remove obsolete name-only subjects after the migration window.
Keep the policy reviewable, documented, and owned by the deployment team.

The security improvement is simple: a repository name is useful for humans, but an immutable owner and repository ID gives the cloud provider a stable identity to trust. Migrate deliberately, keep the subject conditions exact, and test the cloud exchange before changing production settings.