# What is the OIDC subject (sub) claim?

> The sub claim names who an OIDC token is about; in CI, the repository and branch or environment of the job. How its formats work and why exact matching matters.

URL: https://crunu.com/learn/oidc-subject-claim
Language: en
Updated: 2026-10-30

The OIDC subject claim, `sub`, is the field in an OpenID Connect token that names the principal the token is about; in a CI job's token it is a string built from the repository and the branch, tag or deployment environment the job runs for, and it is the claim most trust rules match on.

## What it looks like

RFC 7519 defines `sub` as the claim that "identifies the principal that is the subject of the JWT" ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519)). Each CI provider decides how to fill it. GitHub's formats, from its [OIDC reference](https://docs.github.com/en/actions/reference/security/oidc):

| Job                                     | Subject                                              |
| --------------------------------------- | ---------------------------------------------------- |
| runs on a branch                        | `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` |
| references an environment               | `repo:octo-org/octo-repo:environment:Production`     |
| runs for a pull request, no environment | `repo:octo-org/octo-repo:pull_request`               |
| runs on a tag                           | `repo:octo-org/octo-repo:ref:refs/tags/demo-tag`     |

Two consequences surprise people. The environment wins: a job that deploys to `Production` from `main` gets the environment subject, not the branch one. And a pull request job without an environment gets a subject that names no branch at all.

## The 2026 format change on GitHub

The old format names an owner and repository by name. GitHub explains the problem: "If a namespace was recycled, a different owner could create the same subject value." So "repositories created after July 15, 2026 now use an immutable default subject format" that "includes both the owner ID and repository ID", for example `repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main`. Older repositories keep the previous format unless the organization or repository opts in; renames and transfers after that date also switch. GitHub Enterprise Server isn't part of the rollout.

A trust rule written for the old format silently stops matching a new repository. Check which format yours uses before writing rules. The details and migration path are in [GitHub's OIDC subject claim format](https://crunu.com/blog/github-oidc-subject-claim-format).

## Common mistakes

- **Wildcards.** `repo:kiteline/*` trusts every repository in the organization, including ones created later. AWS refuses to save a trust policy for GitHub whose `sub` condition is missing or only a wildcard ([AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)).
- **Prefix matches.** A pattern like `repo:kiteline/web-app*` also matches `kiteline/web-app-fork`.
- **Matching `sub` alone where the provider offers more.** Separate claims such as `repository_id` or `ref` can be pinned individually.
- **Customizing the template in the wrong order.** GitHub advises creating the matching condition at your cloud provider first, because "customizing the claims results in a new format for the entire `sub` claim."

## How Crunu matches it

Crunu's **CI binding (OIDC)** on a service token doesn't ask you to write a subject string. Rules name the claims directly: for GitHub Actions the repository and audience are required, and ref, environment, workflow ref, repository ID and owner ID are optional; GitLab CI rules use project path, ref, ref type, protected ref and environment; Bitbucket rules use workspace and repository UUIDs and optionally the branch and deployment environment UUID. A rule for any other OIDC issuer must pin at least one claim for a repository, project or owner without a `*` pattern.

Pinning IDs where you can protects against the recycled-name problem regardless of the subject format. For the claims every provider issues, see [CI/CD secrets with OIDC](https://crunu.com/guides/ci-cd-secrets-with-oidc); to generate cloud policies in both GitHub formats, use the [OIDC trust policy builder](https://crunu.com/tools/oidc-policy-builder).

## Sources

- [RFC 7519: JSON Web Token (JWT)](https://www.rfc-editor.org/rfc/rfc7519), checked October 30, 2026.
- [GitHub Docs: OpenID Connect reference](https://docs.github.com/en/actions/reference/security/oidc), checked October 30, 2026.
- [AWS IAM: Create a role for OpenID Connect federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html), checked October 30, 2026.