OIDC connections rulesets and subject claims

Rulesets and subject claims define what actions your GitHub workflows can take with your Docker resources. Use them to authorize GitHub workflow behaviors for an OIDC connection.

Rulesets

A ruleset is a set of conditions that Docker evaluates against an incoming GitHub ID token. When a workflow triggers an OIDC exchange, Docker checks the token against every ruleset defined in your connection. If a ruleset's conditions are satisfied, Docker grants access based on the parameters set by that ruleset.

Each ruleset contains the following fields:

• Label: A name for the ruleset.
• Rules: One or more conditions based on OIDC token claims, such as the repository name, branch, or workflow path.
  • These are expressed as subject claim strings.
  • See Subject claims.
• Resources: The Docker resources a workflow can access when the ruleset matches. See Resources.
• Scopes: The permissions granted on those resources, such as read or write access.

You can define between 1 and 5 rulesets per connection. Use multiple rulesets to apply different access levels across different workflows or branches. If more than one ruleset matches an incoming token, Docker merges the resources from all matching rulesets and grants access to the combined set.

Subject claims

A subject claim is the sub field in a GitHub-issued JWT ID token. It encodes details of a workflow into a single string, identifying the workflow by organization, repository, branch, environment, and so on.

Docker uses the subject claim as the primary condition when evaluating your ruleset rules. The default subject claim format is:

repo:<org>/<repo>:ref:refs/heads/<branch>

For example:

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

The exact format varies and depends on what triggered the workflow.

• A branch push, pull request, tag, or environment deployment each produces a different sub value.
• Refer to GitHub's OpenID Connect reference for the full list of formats.

Note

GitHub repositories created after July 15, 2026 have immutable identifiers in the default subject claim. For example: repo:octocat@123456/my-repo@456789:ref:refs/heads/main. See the GitHub changelog for more details.

You can use wildcards to match across repositories or branches:

Resources

Resources define the Docker resources a workflow can access when a ruleset matches. You specify resources per ruleset, alongside the scopes that determine the level of access granted.

Docker Hub repositories and Docker Build Cloud are supported resources.

What's next

• OIDC connections overview
• Create or manage OIDC connections