Docker OIDC for GitHub Actions: Eliminate Stored Credentials

Every GitHub Actions workflow that pushes or pulls images from Docker Hub authenticates with a personal access token (PAT) or organization access token (OAT) stored as a GitHub secret. These credentials are long-lived: someone must remember to rotate them, and each rotation requires updating every workflow that references the secret.

A leaked token grants access to the container registry. An attacker can pull private images—including proprietary base images and embedded source code—or push malicious images to legitimate repositories. Because the token does not expire on its own, that access persists until the leak is discovered and the token is manually revoked. The broader the token's scope, the larger the blast radius.

• Long-lived PATs and OATs remain valid for extended periods, regardless of how many workflows, forked repositories, or third-party actions have been exposed to them.
• Rotation is manual and human-dependent; as pipelines multiply, so do the credentials that need tracking.
• Stale tokens—credentials that are no longer actively used but still valid—are a common audit finding.

Consider a concrete failure: a token stored as DOCKERHUB_TOKEN in repository secrets is read by a workflow and passed to docker/login-action. If the token is accidentally printed in a debug log, exfiltrated through a compromised dependency, or exposed by a malicious pull request that alters workflow logic, the attacker can issue authenticated docker pull and docker push commands against the organization's Docker Hub resources until the token is revoked.

Manual rotation does not scale. Every new workflow and repository increases the number of stored secrets, verification that rotation actually occurred is weak, and the organization cannot distinguish which workflow or engineer used a given token at a given time—an audit and incident-response gap.

Address the root cause by eliminating stored credentials for registry authentication. The workflow can exchange a GitHub-issued OIDC identity token for a short-lived Docker access token that expires in minutes, is scoped to resources defined in an OIDC ruleset, and cannot be reused. No PAT or OAT is stored, there is nothing to rotate, and stale-token findings disappear.

OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol that allows for the exchange of identity tokens between a provider—in this case, GitHub—and a relying party, such as Docker Hub. By utilizing OIDC, enterprise organizations can eliminate the reliance on long-lived Personal Access Tokens (PATs) or Organization Access Tokens (OATs) within CI/CD pipelines. This approach mitigates risks associated with credential leakage, as the authentication process relies on short-lived, ephemeral tokens that expire automatically after a brief duration and cannot be reused.

Adopting OIDC connections is the recommended security best practice for GitHub Actions workflows. This mechanism requires the id-token: write permission within the workflow, allowing it to request a signed JSON Web Token (JWT) from GitHub. Docker verifies this token against its own rulesets configured in the Admin Console. If the token’s metadata matches the defined constraints—such as specific repositories or branches—Docker issues a temporary access token for the necessary container registry operations.

Access to Docker OIDC functionality is restricted to specific subscription tiers and programs. Organizations should evaluate their eligibility based on the following requirements:

• Docker Team subscription
• Docker Business subscription
• Docker Hardened Images (DHI) subscription
• Enrollment in the Docker Sponsored Open Source Program (DSOS)

When implementing OIDC, administrators can define up to five rulesets per connection to enforce granular access control. These rulesets validate the OIDC subject claim (sub) to ensure that only authorized workflows can interact with Docker Hub resources. For instance, a ruleset may be pinned to a specific branch pattern, such as repo:my-org/my-repo:ref:refs/heads/main, to adhere to the principle of least privilege. Organizations transitioning to this model should remove legacy PATs and OATs from their GitHub secrets once the OIDC-based workflow has been validated, thereby reducing the organization’s overall attack surface and simplifying secret management.

OpenID Connect (OIDC) token exchange replaces long-lived stored credentials with a per-run, short-lived identity. In a GitHub Actions workflow, GitHub acts as the identity provider and issues a signed JSON Web Token (JWT). The JWT's subject claims encode the repository, branch, environment, and workflow metadata for that specific run. The token is neither stored nor exposed as a GitHub secret; it is available only during workflow execution.

The exchange proceeds as follows:

1. GitHub issues a JWT signed with a private key whose public counterpart is published in GitHub's public key registry.
2. The docker/login-action presents the JWT to Docker.
3. Docker verifies the signature against GitHub's public key registry and checks the token's claims against the rulesets configured in the Admin Console.
4. If the claims match a ruleset, Docker returns an access token scoped to the resources defined by that ruleset.
5. docker/login-action uses this token to authenticate to Docker Hub; docker pull, docker build, and docker push operate normally.

Rulesets match incoming tokens using OIDC subject claims. For example, repo:my-org/my-repo:ref:refs/heads/main grants access only to the main branch of a specific repository, while repo:my-org/my-repo:ref:refs/heads/release-* matches every release branch. Pinning to specific repositories and branches is a recommended security best practice; broad patterns such as repo:my-org/* cover any repository in the organization and are not recommended.

The Docker access token that is returned is:

• Short-lived: it expires in minutes.
• Scoped to the resources defined by the matched ruleset.
• Non-reusable: it cannot be replayed after expiry.

This exchange pattern is the same one AWS and GCP use for cloud resource access—AWS OIDC for GitHub Actions and GCP Workload Identity Federation both exchange a GitHub-issued JWT for a temporary, scoped token. Docker applies the model to container registry access, allowing pipelines to authenticate without storing personal access tokens (PATs) or organization access tokens (OATs) in GitHub secrets.

Docker Hub authentication for GitHub Actions traditionally relies on personal access tokens (PATs) or organization access tokens (OATs) stored as GitHub repository secrets. Those credentials are long-lived, require manual rotation, and remain valid until explicitly revoked. Docker's OpenID Connect (OIDC) connection mechanism eliminates this stored-credential pattern: GitHub issues a signed JSON Web Token (JWT) encoding the repository, branch, and other workflow metadata; docker/login-action presents that token to Docker; Docker verifies the token signature against GitHub's public key registry and evaluates it against rulesets configured in Docker Home. A successful match yields a short-lived access token, scoped to the resources defined by the matching ruleset, that expires in minutes and cannot be reused.

1. Create an OIDC connection. Sign in to Docker Home, select your organization, and navigate to OIDC connections. Choose Create OIDC connection and configure rulesets that control which repositories, branches, and workflows may access which Docker Hub resources. You can create up to five rulesets per connection. Rulesets match incoming tokens using OIDC subject claims. Pin to specific repositories and branches as a security best practice:

   • repo:my-org/my-repo:ref:refs/heads/main — only the main branch of one repository
   • repo:my-org/my-repo:ref:refs/heads/release-* — all release branches of one repository
   • repo:my-org/my-repo:* — all branches of one repository
   • repo:my-org/* — any repository in the organization (not recommended)

2. Copy the connection ID and update your workflow. After creating the connection, copy its ID. Then update your GitHub Actions workflow:

   permissions:
     contents: read
     id-token: write
   steps:
     - name: Docker login
       uses: docker/login-action@v4
       with:
         username: <YOUR_ORG_NAME>
       env:
         DOCKERHUB_OIDC_CONNECTIONID: <YOUR_CONNECTION_ID>

   The id-token: write permission allows the workflow to request a GitHub OIDC token. When DOCKERHUB_OIDC_CONNECTIONID is set, docker/login-action performs the token exchange and login in a single step; subsequent docker pull, docker build, and docker push commands work unchanged.

3. Run the workflow to verify. Execute the workflow and confirm it completes successfully. If the exchange fails, the Failures tab on the OIDC connection page shows the incoming claim sub value, which you can use to diagnose why the ruleset did not match.

4. Remove the stored credential. Once the workflow succeeds via OIDC, delete the old PAT or OAT from your GitHub repository secrets. Existing PATs and OATs continue to work, so you can migrate workflows incrementally; OIDC only replaces the authentication step.

Note that GitHub repositories created after July 15, 2026 use immutable identifiers for default subject claims. For example, a claim may appear as repo:octocat@123456/my-repo@456789:ref:refs/heads/main rather than repo:octocat/my-repo:ref:refs/heads/main; consult GitHub's changelog for exact formats when writing rulesets for new repositories.

OpenID Connect (OIDC) for Docker Hub replaces only the authentication step in a GitHub Actions workflow. The docker/login-action presents a GitHub-issued OIDC token to Docker, Docker validates it against rulesets configured in the organization, and returns a short-lived access token. After that exchange completes, everything downstream executes exactly as it did before: docker pull, docker push, and docker build commands behave identically, and the registry, image format, tag structure, and build pipeline remain untouched.

Existing credentials continue to work. Personal access tokens (PATs) and organization access tokens (OATs) stored as GitHub secrets still authenticate workflows that have not been migrated. This enables an incremental, workflow-by-workflow migration. A team can move one pipeline to OIDC, verify that it runs successfully, and then remove only that workflow's stored credential. Other workflows can remain on PATs and OATs until their owners are ready.

Adopting OIDC does not change:

• Images and registries. Image names, tags, digests, and registry endpoints remain identical; OIDC only affects how the client authenticates.
• Build workflows. Dockerfiles, build arguments, base images, and multi-stage builds are unaffected. Only the login step in the workflow YAML changes.
• Local development. Developers running docker login on their own machines continue to use PATs; organization-level OIDC adoption does not alter local credential handling.
• Non-GitHub CI systems. Jenkins, GitLab CI, CircleCI, and similar platforms do not have a Docker OIDC connection. Their pipelines continue to use PATs and OATs.

OIDC connections are the recommended replacement for GitHub Actions specifically, not a universal replacement for all stored credentials. Other CI providers will add OIDC support based on demand; until they do, long-lived credentials remain necessary in those environments. Because the change is scoped to the authentication step, the migration is reversible: create an OIDC connection with rulesets, update the workflow YAML, verify the run, and only then remove the old stored credential. If a workflow fails, the stored credential is still in place and the workflow can be reverted without disrupting image builds or pushes.

Transitioning to OpenID Connect (OIDC) for GitHub Actions eliminates the reliance on long-lived Personal Access Tokens (PATs) or Organization Access Tokens (OATs). By leveraging short-lived, per-run tokens, organizations significantly reduce the risk of credential leakage and remove the operational overhead of manual secret rotation. This migration is available to organizations with Docker Team, Docker Business, or Docker Hardened Images subscriptions, as well as those in the Docker Sponsored Open Source Program.

Migration Checklist

• Create a connection: Access the OIDC connections section within Docker Home. Configure rulesets based on OIDC subject claims—such as specific repositories or branches—to define which workflows can access your resources. Secure your configuration by pinning to specific repository and branch patterns.
• Update your workflow: Modify your GitHub Actions YAML to grant the necessary permissions (contents: read and id-token: write). Utilize docker/login-action (v4.5.0 or later) by injecting your connection ID via the DOCKERHUB_OIDC_CONNECTIONID environment variable.
• Verify the connection: Trigger the workflow and monitor the execution. A successful exchange results in a short-lived access token, allowing downstream docker pull, push, and build commands to proceed as usual.
• Remove stored credentials: Once verification is complete, delete the legacy PATs or OATs from your GitHub repository secrets to finalize the security posture.

Troubleshooting

If a workflow fails during authentication, navigate to the Failures tab on the specific OIDC connection page within Docker Home. This interface provides visibility into the incoming sub (subject) claim value generated by the GitHub workflow run. Comparing this value against your configured rulesets is the most efficient method for diagnosing why an authentication request was rejected.

For further technical details regarding implementation and security, refer to the following resources:

• Official Docker Documentation: Comprehensive guidance on registry authentication and OIDC configuration.
• Docker Home: The central console for managing your organization's OIDC connections and rulesets.
• OpenID Connect Standards: Review standard OIDC documentation for a deeper understanding of the JWT-based token exchange flow between identity providers and service registries.