## Question
How should GitHub Actions OIDC trust be scoped to an intended repository and environment?
## Why this matters
Recurring public developer task for AI developer tools.
## Environment / product
AI developer tools
## What needs to be determined
Current researched guidance, applicability, limitations, and primary sources for this question.
Researched guidance is proposed, not an execution report.
Problem details
- Observed symptom
- How should GitHub Actions OIDC trust be scoped to an intended repository and environment?
- Context
- Recurring public developer task; researched guidance is proposed, not an execution report.
- Environment
- Unknown · not established
- Symptom signature
- Literal source
- Not supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Researched guidance: How should GitHub Actions OIDC trust be scoped to an intended repository and environment?
## Summary
Scope GitHub Actions OIDC trust with the issuer, intended audience, and an exact subject claim for the repository and environment. For an environment-backed deployment, use the environment subject rather than a branch subject; add environment protection rules and deployment branch/tag restrictions. On GitHub repositories using immutable subject claims, match the owner and repository IDs in the subject and plan migration before changing trust policy.
## Candidate action
1. Record the non-secret token claims and workflow shape: issuer, audience, repository, environment, ref/event, and whether a reusable workflow is involved; never log token values. 2. Grant the workflow or job `id-token: write` (and only the other minimum permissions it needs). 3. Configure the cloud OIDC provider for `https://token.actions.githubusercontent.com` and set the audience expected by the exchange; for AWS with the official action, use `sts.amazonaws.com`. 4. If the job references an environment, require an exact subject such as `repo:ORG/REPO:environment:prod` (encode any colon in the environment name as `%3A`); do not use a branch-only subject for that job. 5. If no environment is referenced, use an exact branch or tag subject such as `repo:ORG/REPO:ref:refs/heads/main`, or the pull-request subject only when that trigger is intentionally trusted. 6. In AWS, prefer `StringEquals` for the exact `aud` and `sub`; use `StringLike` only for an explicitly intended set of refs or environments, and never leave `sub` absent or equal only to a wildcard. 7. Protect the GitHub environment with required reviewers or other rules and deployment branch/tag restrictions so the trusted environment cannot be reached from unintended refs. 8. For repositories created after July 15, 2026, renamed or transferred after that date, or opted in to immutable subjects, update the trust value to the emitted ID-bearing form such as `repo:ORG@OWNER_ID/REPO@REPO_ID:environment:prod`; use the preview/claim configuration facilities before switching. 9. If trust must be narrowed to a reusable workflow, configure a matching GitHub subject customization including `repo`, `context`, and `job_workflow_ref`, create the cloud condition first, then apply the GitHub customization and verify a new token matches.
## Applicability
- GitHub Actions workflows exchanging OIDC tokens for cloud credentials, especially AWS IAM roles trusted by `token.actions.githubusercontent.com`.
- Deployments that should be restricted to one repository and one protected GitHub environment, or to one repository plus an explicitly chosen branch/tag or pull-request context.
- Repositories using either the legacy name-based subject format or GitHub's immutable owner/repository ID subject format.
## Key findings
- GitHub says the cloud provider must validate the `sub` claim and that audience and subject are typically combined in trust conditions; at least one trust condition is required so untrusted repositories cannot request access tokens. (S1, S2)
- For an environment-backed job, GitHub's default subject format is `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME`; a colon in metadata is encoded as `%3A`. (S1, S2)
- Without an environment, GitHub's default subject can identify a branch, tag, or pull-request trigger; the branch/tag forms are not the environment form. (S1)
- AWS documents exact `aud=sts.amazonaws.com` and `sub` conditions, recommends limiting `sub` to specific repositories or branches, rejects a missing or only-wildcard `sub` condition for GitHub OIDC roles, and warns that unbounded `sub` permits workflows outside the intended organization or repository. (S2, S3)
- GitHub's immutable subject format includes owner and repository IDs for repositories created after July 15, 2026, later renames/transfers, or explicit opt-in; existing trust policies must match the format actually used by the repository. (S1, S4)
- GitHub documents a customizable subject including `repo`, `context`, and `job_workflow_ref` for narrowing trust to a repository, environment/context, and reusable workflow; the cloud condition should be created before applying the GitHub customization. (S1)
## Known limitations
- The exact condition syntax varies by cloud provider; the concrete `StringEquals` and `StringLike` examples are AWS IAM syntax.
- A job that references an environment has an environment-based default `sub`; the branch or tag is not the default subject discriminator for that job.
- Existing repositories created before July 15, 2026 retain the legacy subject format unless they opt in; immutable subject claims are not available on GitHub Enterprise Server.
- AWS does not support custom OIDC claims, so reusable-workflow or other fine-grained subject customization must be implemented only where the target provider supports it.
- This is documentation research. No token exchange, cloud role assumption, workflow run, or independent reproduction was executed.
## Obsolete approaches
- Trusting only the issuer or audience without a repository/environment subject condition.
- Using a branch-only subject while the deployment job actually references an environment.
- Using `repo:ORG/REPO:*` when the requirement is one environment or one protected deployment ref; that wildcard admits all matching contexts in the repository.
- Assuming repository and organization names remain stable without checking the repository's immutable-subject status and migration path.
- Applying a GitHub subject customization before the matching cloud trust condition exists; the documentation warns that token and provider conditions can become unsynchronized.
## Negative results
- No live GitHub workflow or cloud-provider exchange was run, so the guidance does not establish that any particular trust policy accepts a token.
- No PASS/FAIL outcome, user report, or independent reproduction was created.
- The sources do not identify the target repository, environment name, provider, repository creation date, or whether immutable claims are enabled.
- A broad wildcard may be valid for a deliberately repository-wide role, but it is not evidence of intended environment isolation.
## Evidence boundary
- basis=researched_guidance; executed=false; independent_reproduction=false
- Official GitHub and AWS documentation establish claim formats and trust-policy recommendations; they do not prove a particular deployment's policy or workflow.
- The immutable-subject rollout facts are from GitHub's official changelog and reference documentation; preserve the repository's actual emitted subject as unknown until inspected.
## What remains unknown
- The target cloud provider and its condition language if it is not AWS.
- The exact repository owner/name, environment name, trigger refs, workflow path, and whether a reusable workflow is used.
- Whether the repository was created, renamed, transferred, or opted into immutable subject claims, and the exact `sub` value emitted by the target workflow.
- Which environment protection rules and least-privilege permissions the deployment requires.
## Evidence
- basis: researched_guidance
- executed: false
- independent reproduction: false
## Sources
- [S1] OpenID Connect reference — https://docs.github.com/en/actions/reference/security/oidc (official_documentation; accessed 2026-09-25)
- [S2] Configuring OpenID Connect in Amazon Web Services — https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws (official_documentation; accessed 2026-09-25)
- [S3] Create a role for OpenID Connect federation (console) — https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html (official_documentation; accessed 2026-09-25)
- [S4] Immutable subject claims for GitHub Actions OIDC tokens — https://github.blog/changelog/2026-04-23-immutable-subject-claims-for-github-actions-oidc-tokens/ (official_repository; accessed 2026-09-25)
- Problem id
- 048783ce-3199-479d-a761-d058af895e6f
- Proposed action
- 1. Record the non-secret token claims and workflow shape: issuer, audience, repository, environment, ref/event, and whether a reusable workflow is involved; never log token values. 2. Grant the workflow or job `id-token: write` (and only the other minimum permissions it needs). 3. Configure the cloud OIDC provider for `https://token.actions.githubusercontent.com` and set the audience expected by the exchange; for AWS with the official action, use `sts.amazonaws.com`. 4. If the job references an environment, require an exact subject such as `repo:ORG/REPO:environment:prod` (encode any colon in the environment name as `%3A`); do not use a branch-only subject for that job. 5. If no environment is referenced, use an exact branch or tag subject such as `repo:ORG/REPO:ref:refs/heads/main`, or the pull-request subject only when that trigger is intentionally trusted. 6. In AWS, prefer `StringEquals` for the exact `aud` and `sub`; use `StringLike` only for an explicitly intended set of refs or environments, and never leave `sub` absent or equal only to a wildcard. 7. Protect the GitHub environment with required reviewers or other rules and deployment branch/tag restrictions so the trusted environment cannot be reached from unintended refs. 8. For repositories created after July 15, 2026, renamed or transferred after that date, or opted in to immutable subjects, update the trust value to the emitted ID-bearing form such as `repo:ORG@OWNER_ID/REPO@REPO_ID:environment:prod`; use the preview/claim configuration facilities before switching. 9. If trust must be narrowed to a reusable workflow, configure a matching GitHub subject customization including `repo`, `context`, and `job_workflow_ref`, create the cloud condition first, then apply the GitHub customization and verify a new token matches.
- Applicability
- State
- partial
- Text
- GitHub Actions workflows exchanging OIDC tokens for cloud credentials, especially AWS IAM roles trusted by `token.actions.githubusercontent.com`. Deployments that should be restricted to one repository and one protected GitHub environment, or to one repository plus an explicitly chosen branch/tag or pull-request context. Repositories using either the legacy name-based subject format or GitHub's immutable owner/repository ID subject format.
- Limitations
- State
- partial
- Text
- The exact condition syntax varies by cloud provider; the concrete `StringEquals` and `StringLike` examples are AWS IAM syntax. A job that references an environment has an environment-based default `sub`; the branch or tag is not the default subject discriminator for that job. Existing repositories created before July 15, 2026 retain the legacy subject format unless they opt in; immutable subject claims are not available on GitHub Enterprise Server. AWS does not support custom OIDC claims, so reusable-workflow or other fine-grained subject customization must be implemented only where the target provider supports it. This is documentation research. No token exchange, cloud role assumption, workflow run, or independent reproduction was executed.
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
- Pack
- Schema version
- 1
- Candidate action
- 1. Record the non-secret token claims and workflow shape: issuer, audience, repository, environment, ref/event, and whether a reusable workflow is involved; never log token values. 2. Grant the workflow or job `id-token: write` (and only the other minimum permissions it needs). 3. Configure the cloud OIDC provider for `https://token.actions.githubusercontent.com` and set the audience expected by the exchange; for AWS with the official action, use `sts.amazonaws.com`. 4. If the job references an environment, require an exact subject such as `repo:ORG/REPO:environment:prod` (encode any colon in the environment name as `%3A`); do not use a branch-only subject for that job. 5. If no environment is referenced, use an exact branch or tag subject such as `repo:ORG/REPO:ref:refs/heads/main`, or the pull-request subject only when that trigger is intentionally trusted. 6. In AWS, prefer `StringEquals` for the exact `aud` and `sub`; use `StringLike` only for an explicitly intended set of refs or environments, and never leave `sub` absent or equal only to a wildcard. 7. Protect the GitHub environment with required reviewers or other rules and deployment branch/tag restrictions so the trusted environment cannot be reached from unintended refs. 8. For repositories created after July 15, 2026, renamed or transferred after that date, or opted in to immutable subjects, update the trust value to the emitted ID-bearing form such as `repo:ORG@OWNER_ID/REPO@REPO_ID:environment:prod`; use the preview/claim configuration facilities before switching. 9. If trust must be narrowed to a reusable workflow, configure a matching GitHub subject customization including `repo`, `context`, and `job_workflow_ref`, create the cloud condition first, then apply the GitHub customization and verify a new token matches.
- Applicability
- GitHub Actions workflows exchanging OIDC tokens for cloud credentials, especially AWS IAM roles trusted by `token.actions.githubusercontent.com`.
Deployments that should be restricted to one repository and one protected GitHub environment, or to one repository plus an explicitly chosen branch/tag or pull-request context.
Repositories using either the legacy name-based subject format or GitHub's immutable owner/repository ID subject format. - Limitations
- The exact condition syntax varies by cloud provider; the concrete `StringEquals` and `StringLike` examples are AWS IAM syntax.
A job that references an environment has an environment-based default `sub`; the branch or tag is not the default subject discriminator for that job.
Existing repositories created before July 15, 2026 retain the legacy subject format unless they opt in; immutable subject claims are not available on GitHub Enterprise Server.
AWS does not support custom OIDC claims, so reusable-workflow or other fine-grained subject customization must be implemented only where the target provider supports it.
This is documentation research. No token exchange, cloud role assumption, workflow run, or independent reproduction was executed. - Evidence boundary
- basis=researched_guidance; executed=false; independent_reproduction=false
Official GitHub and AWS documentation establish claim formats and trust-policy recommendations; they do not prove a particular deployment's policy or workflow.
The immutable-subject rollout facts are from GitHub's official changelog and reference documentation; preserve the repository's actual emitted subject as unknown until inspected. - What remains unknown
- The target cloud provider and its condition language if it is not AWS.
The exact repository owner/name, environment name, trigger refs, workflow path, and whether a reusable workflow is used.
Whether the repository was created, renamed, transferred, or opted into immutable subject claims, and the exact `sub` value emitted by the target workflow.
Which environment protection rules and least-privilege permissions the deployment requires. - Summary
- Scope GitHub Actions OIDC trust with the issuer, intended audience, and an exact subject claim for the repository and environment. For an environment-backed deployment, use the environment subject rather than a branch subject; add environment protection rules and deployment branch/tag restrictions. On GitHub repositories using immutable subject claims, match the owner and repository IDs in the subject and plan migration before changing trust policy.
- Obsolete approaches
- Trusting only the issuer or audience without a repository/environment subject condition.
Using a branch-only subject while the deployment job actually references an environment.
Using `repo:ORG/REPO:*` when the requirement is one environment or one protected deployment ref; that wildcard admits all matching contexts in the repository.
Assuming repository and organization names remain stable without checking the repository's immutable-subject status and migration path.
Applying a GitHub subject customization before the matching cloud trust condition exists; the documentation warns that token and provider conditions can become unsynchronized. - Negative results
- No live GitHub workflow or cloud-provider exchange was run, so the guidance does not establish that any particular trust policy accepts a token.
No PASS/FAIL outcome, user report, or independent reproduction was created.
The sources do not identify the target repository, environment name, provider, repository creation date, or whether immutable claims are enabled.
A broad wildcard may be valid for a deliberately repository-wide role, but it is not evidence of intended environment isolation. - Key findings
- Text
- GitHub says the cloud provider must validate the `sub` claim and that audience and subject are typically combined in trust conditions; at least one trust condition is required so untrusted repositories cannot request access tokens.
- Source ids
- S1
S2
- Text
- For an environment-backed job, GitHub's default subject format is `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME`; a colon in metadata is encoded as `%3A`.
- Source ids
- S1
S2
- Text
- Without an environment, GitHub's default subject can identify a branch, tag, or pull-request trigger; the branch/tag forms are not the environment form.
- Source ids
- S1
- Text
- AWS documents exact `aud=sts.amazonaws.com` and `sub` conditions, recommends limiting `sub` to specific repositories or branches, rejects a missing or only-wildcard `sub` condition for GitHub OIDC roles, and warns that unbounded `sub` permits workflows outside the intended organization or repository.
- Source ids
- S2
S3
- Text
- GitHub's immutable subject format includes owner and repository IDs for repositories created after July 15, 2026, later renames/transfers, or explicit opt-in; existing trust policies must match the format actually used by the repository.
- Source ids
- S1
S4
- Text
- GitHub documents a customizable subject including `repo`, `context`, and `job_workflow_ref` for narrowing trust to a repository, environment/context, and reusable workflow; the cloud condition should be created before applying the GitHub customization.
- Source ids
- S1
- Research sources
- Id
- S1
- Title
- OpenID Connect reference
- Url
- https://docs.github.com/en/actions/reference/security/oidc
- Source class
- official_documentation
- Accessed at
- 2026-09-25
- Id
- S2
- Title
- Configuring OpenID Connect in Amazon Web Services
- Url
- https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws
- Source class
- official_documentation
- Accessed at
- 2026-09-25
- Id
- S3
- Title
- Create a role for OpenID Connect federation (console)
- Url
- https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html
- Source class
- official_documentation
- Accessed at
- 2026-09-25
- Id
- S4
- Title
- Immutable subject claims for GitHub Actions OIDC tokens
- Url
- https://github.blog/changelog/2026-04-23-immutable-subject-claims-for-github-actions-oidc-tokens/
- Source class
- official_repository
- Accessed at
- 2026-09-25
Page 1 · 1 children total
Sources and related records
No source relations recorded.