Eliminate Stored Credentials in Your CI/CD Pipelines
TL;DR: Docker now supports OpenID Connect (OIDC) for GitHub Actions. Your workflows can authenticate with short-lived, per-run tokens instead of stored PATs or OATs. No secrets to rotate, no credentials to leak.
GitHub OIDC connections are available to organizations with Docker Team, Docker Business, or Docker Hardened Images (DHI) subscriptions, as well as organizations enrolled in the Docker Sponsored Open Source Program (DSOS).
Table of contents
- The problem with stored credentials
- Who should use this
- How OIDC connections work
- Getting started
- What doesn’t change
- Learn more
OIDC token exchange flow between GitHub Actions and Docker
The problem with 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 has to remember to rotate them. A leaked token grants access to your registry — pulling private images, pushing malicious ones — and that access persists until someone discovers and revokes it. Rotation is manual and does not scale. As pipelines multiply, so do the credentials that need tracking, and stale tokens are a common audit finding.
Who should use this
- GitHub issues a signed identity token (a JWT) that encodes the repository, branch, environment, and other metadata about the workflow run.
- The workflow calls docker/login-action, which presents this token to Docker.
- Docker verifies the token’s signature against GitHub’s public key registry and checks it against rulesets configured in the Admin Console.
- If the token matches a ruleset, Docker returns a short-lived access token scoped to the resources defined in that ruleset.
- docker/login-action uses this token to authenticate to Docker Hub. From there, docker pull, docker push, and docker build commands work as usual.
The entire exchange happens without any stored secrets, API keys, or access tokens. The short-lived Docker access token expires in minutes and cannot be reused.
This is the same pattern that AWS and GCP already use for cloud resource access (AWS OIDC for GitHub Actions, GCP Workload Identity Federation). Docker is applying it to container registry access.
Getting started
Setup is a one-time connection in Docker Home plus a small update to your workflow YAML.
Step 1: Create a connection
Sign in to Docker Home, select your organization, and navigate to OIDC connections. Select Create OIDC connection and configure the rulesets that control which repositories, branches, and workflows can access which Docker Hub resources. You can create up to five rulesets per connection. 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.
Rulesets use OIDC subject claims to match incoming tokens. You can pin to specific repos and branches as a recommended security best practice:
- repo:my-org/my-repo:ref:refs/heads/main — only the main branch of a specific repo
- repo:my-org/my-repo:ref:refs/heads/release-* — all release branches
- repo:my-org/my-repo:* – all branches of this repo
- repo:my-org/* — any repo in the organization (not recommended)
Copy the connection ID when you are done.
Note: GitHub repositories created after July 15, 2026 use immutable identifiers for default subject claims. For example: repo:octocat@123456/my-repo@456789:ref:refs/heads/main. See the GitHub changelog for more details.
Step 2: Update your workflow
Update your GitHub Actions workflow. Replace
with the ID from the previous step and
with your Docker organization name:
permissions:
contents: read
id-token: write
steps:
- name: Docker login
uses: docker/login-action@v4 # v4.5.0+
with:
username:
env:
DOCKERHUB_OIDC_CONNECTIONID:
The id-token
: write permission lets the workflow request a GitHub OIDC token. The docker/login-action
handles the token exchange and Docker login in a single step when DOCKERHUB_OIDC_CONNECTIONID
is set. From there, docker pull, docker push, and docker build commands work as usual.details of the incoming claim sub value, which you can use to diagnose why the connection failed.
Step 3: Verify the OIDC connection works
Run your workflow and confirm it completes successfully. If you encounter an error, the Failures tab of the OIDC connection page will show the details of the incoming claim sub value, which you can use to diagnose why the connection failed.
Step 4: Remove the stored credential
After verifying your workflow runs successfully with OIDC, remove the old PAT or OAT from your GitHub repository secrets. You no longer need it.
Migration Checklist
- Create a connection
- Update your workflow
- Verify the OIDC connection works
- Remove stored credentials
What doesn’t change
- Existing PATs and OATs keep working. Organizations can migrate workflows to OIDC connections at their own pace.
- Images, registries, and build workflows are unchanged. OIDC connections only replace the authentication step; everything downstream is the same.
- Local development and non-GitHub CI still use PATs and OATs. OIDC connections are the recommended replacement for GitHub Actions specifically. Other CI providers will follow based on demand.
Learn more
- Learn more about OpenID Connect
- Visit Docker Home to get started
- Read the documentation
Facts Only
Docker supports OpenID Connect (OIDC) for GitHub Actions.
Organizations with Docker Team, Docker Business, Docker Hardened Images (DHI), or Docker Sponsored Open Source Program (DSOS) subscriptions have access.
Workflows use short-lived tokens instead of stored Personal Access Tokens (PATs) or Organization Access Tokens (OATs).
GitHub issues a signed JWT identity token containing repository and branch metadata.
The docker/login-action@v4 (v4.5.0+) handles the token exchange with Docker Hub.
Docker verifies tokens against rulesets configured in the Docker Admin Console.
Rulesets support pinning to specific repositories, branches, or release patterns.
GitHub repositories created after July 15, 2026, use immutable identifiers for subject claims.
Workflow configuration requires 'id-token: write' and 'contents: read' permissions.
Existing PATs and OATs remain functional during migration.
Local development and non-GitHub CI providers continue to use PATs and OATs.
Executive Summary
Docker Hub now integrates OpenID Connect (OIDC) with GitHub Actions, moving authentication from long-lived, stored secrets to short-lived, per-run tokens. Previously, pipelines relied on Personal Access Tokens (PATs) or Organization Access Tokens (OATs) stored as GitHub secrets, which necessitated manual rotation and posed a security risk if leaked. The new system uses a JWT exchange where GitHub provides an identity token and Docker Hub issues a temporary access token based on pre-configured rulesets.
This transition is available to specific paid tiers and sponsored open-source organizations. While the authentication mechanism changes, the downstream container commands—such as pull, push, and build—remain identical. Users can migrate incrementally, as legacy tokens continue to work. However, this OIDC solution is specific to GitHub Actions; developers operating locally or using other CI providers must still utilize traditional static credentials.
Full Take
The strongest version of this narrative is a straightforward security upgrade: removing static secrets reduces the attack surface and eliminates the operational burden of credential rotation. By aligning with the existing identity patterns used by AWS and GCP, Docker is standardizing how workloads prove their identity without possessing a password.
This is a classic vendor-led transition toward "Identity-as-Infrastructure." The central persuasion vector leverages the well-known pain point of "secret sprawl" and the fear of leaked credentials to drive adoption of a specific ecosystem integration. By framing the problem as a binary choice between "manual rotation/leaks" and "OIDC," the narrative pushes the user toward the vendor's managed control plane.
Patterns detected: ARC-0024 Ambiguity (The text mentions "rulesets" and "conditions" but provides only basic examples, leaving the precise granularity of these permissions ambiguous), ARC-0048 Fear Appeal (The narrative centers on the danger of "malicious" pushes and "stale tokens" as a catalyst for adoption).
The root cause is the industry-wide shift from static secrets to dynamic identity. The implication is a further centralization of trust; while the "secret" is gone, the dependency on the identity provider (GitHub) and the trust-broker (Docker) increases. Human agency shifts from managing a key to managing a policy.
Bridge Questions:
1. If the identity provider (GitHub) is compromised, does this shift in authentication mitigate or exacerbate the resulting breach?
2. How does the reliance on specific paid subscription tiers for this security feature affect the posture of smaller open-source projects?
Counterstrike Scan: A coordinated campaign would use a "security crisis" narrative (e.g., highlighting a massive leak of PATs) to force a migration to a proprietary identity standard. This content does not match that pattern; it is a standard product feature announcement.
Sentinel — Human
This text appears to be a factual, high-quality technical guide detailing an infrastructure update. It exhibits clear expertise in the domain and follows a logical, step-by-step exposition typical of well-documented engineering content.