Add OIDC in Docker guide for GitHub Actions deployments by gmondello · Pull Request #45243 · github/docs

gmondello · 2026-07-21T21:29:34Z

Summary

Adds a new guide for configuring OpenID Connect between GitHub Actions and Docker Hub, following the same format as existing provider-specific guides (AWS, Azure, GCP, HashiCorp Vault, JFrog, Octopus Deploy, PyPI).

Docker Hub recently shipped OIDC connections that let GitHub Actions workflows authenticate using short-lived tokens instead of long-lived personal access tokens (PATs) or organization access tokens (OATs). This eliminates credential rotation overhead and reduces secret sprawl in CI/CD pipelines.

Changes

New file: content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md
- Overview of Docker Hub OIDC connections
- Prerequisites (Docker Business/Team subscription, org owner/editor role)
- Step-by-step setup: creating a connection in Docker Hub, configuring rulesets
- Complete workflow example using docker/oidc-action@v1 and docker/login-action@v4
- Subject claim matching reference (trigger types, wildcard patterns)
- Links to Docker documentation
Updated file: content/actions/how-tos/secure-your-work/security-harden-deployments/index.md
- Added /oidc-in-docker to the children list (alphabetical order, between Azure and GCP)

References

Adds a new guide for configuring OpenID Connect between GitHub Actions and Docker Hub, following the same format as existing provider guides (AWS, Azure, GCP, JFrog, etc.). Docker Hub OIDC connections let workflows authenticate using short-lived tokens instead of long-lived PATs or OATs. The guide covers creating a connection in Docker Hub, configuring rulesets for claim matching, and a complete workflow example using docker/oidc-action and docker/login-action.

welcome · 2026-07-21T21:29:37Z

Thanks for opening this pull request! A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

github-actions · 2026-07-21T21:30:07Z

How to review these changes 👓

Thank you for your contribution. To review these changes, choose one of the following options:

A Hubber will need to deploy your changes internally to review.

Table of review links

Note: Please update the URL for your staging server or codespace.

The table shows the files in the content directory that were changed in this pull request. This helps you review your changes on a staging server. Changes to the data directory are not included in this table.

Source	Review	Production	What Changed
`actions/how-tos/secure-your-work/security-harden-deployments/index.md`	fpt ghec ghes@ 3.21 3.20 3.19 3.18 3.17	fpt ghec ghes@ 3.21 3.20 3.19 3.18 3.17
New file: `actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md`	fpt ghec	fpt ghec

Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server

🤖 This comment is automatically generated.

Copilot

Pull request overview

Adds guidance for authenticating GitHub Actions workflows with Docker Hub using OIDC.

Changes:

Adds Docker Hub OIDC setup, ruleset, and workflow guidance.
Adds the guide to the security-hardening navigation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 9 comments.

File	Description
`oidc-in-docker.md`	Adds the Docker Hub OIDC guide and workflow example.
`index.md`	Registers the new guide in navigation.

- Use Liquid variables instead of hardcoded product names - Add third-party actions disclaimer reusable to workflow example - Use action-checkout reusable for actions/checkout - Add note about immutable subject claim format (post July 15 2026) - Remove duplicate external links per style guide - Pin version comments to major version only (v1, v4, v6)

OIDC connections scope access to Docker Hub and Docker Build Cloud, not just Docker Hub. Keep Docker Hub only where specifically referring to registry operations.

login-action v4.5.1 now handles OIDC token exchange natively when DOCKERHUB_OIDC_CONNECTIONID is set. This is simpler for the common case. The two-step flow using docker/oidc-action is preserved for workflows that need the token as a separate output.

…yments/oidc-in-docker.md Co-authored-by: Alexa Kristensen <81787716+akristen@users.noreply.github.com>

jc-clark

From a Docs Content perspective, this looks great. Awesome work putting this together, @gmondello!

I left a few small comments just for docs style.

We should still get a SME review to confirm the technical details. After this has been approved by a SME, we can go ahead and merge. Holding off on a docs approval until then.

jc-clark · 2026-08-05T23:33:03Z

+The following example uses the placeholder `YOUR_CONNECTION_ID` for the connection ID you copied from Docker, and `YOUR_DOCKER_ORG` for your Docker organization name.
+
+```yaml
+{% data reusables.actions.actions-not-certified-by-github-comment %}
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: {% data reusables.actions.action-checkout %}
+
+      - name: Sign in to Docker Hub with OIDC
+        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
+        with:
+          username: YOUR_DOCKER_ORG
+        env:
+          DOCKERHUB_OIDC_CONNECTIONID: YOUR_CONNECTION_ID
+
+      - name: Build and push
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
+        with:
+          push: true
+          tags: YOUR_DOCKER_ORG/my-image:latest
+```


I'm not sure about the underscores in DOCKERHUB_OIDC_CONNECTIONID. Docs style uses hyphens for placeholders. But I'm not sure if this one is actually a placeholder. If it's a placeholder, let's use hyphens.

Suggested change

The following example uses the placeholder `YOUR_CONNECTION_ID` for the connection ID you copied from Docker, and `YOUR_DOCKER_ORG` for your Docker organization name.

```yaml

{% data reusables.actions.actions-not-certified-by-github-comment %}

permissions:

id-token: write

contents: read

jobs:

build:

runs-on: ubuntu-latest

steps:

- name: Check out repository

uses: {% data reusables.actions.action-checkout %}

- name: Sign in to Docker Hub with OIDC

uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1

with:

username: YOUR_DOCKER_ORG

env:

DOCKERHUB_OIDC_CONNECTIONID: YOUR_CONNECTION_ID

- name: Build and push

uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6

with:

push: true

tags: YOUR_DOCKER_ORG/my-image:latest

```

The following example uses the placeholder `YOUR-CONNECTION-ID` for the connection ID you copied from Docker, and `YOUR-DOCKER-ORG` for your Docker organization name.

```yaml

{% data reusables.actions.actions-not-certified-by-github-comment %}

permissions:

id-token: write

contents: read

jobs:

build:

runs-on: ubuntu-latest

steps:

- name: Check out repository

uses: {% data reusables.actions.action-checkout %}

- name: Sign in to Docker Hub with OIDC

uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1

with:

username: YOUR-DOCKER-ORG

env:

DOCKERHUB_OIDC_CONNECTIONID: YOUR-CONNECTION-ID

- name: Build and push

uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6

with:

push: true

tags: YOUR-DOCKER-ORG/my-image:latest

jc-clark · 2026-08-05T23:34:57Z

+### Key workflow settings
+
+* **`permissions.id-token: write`** is required so that {% data variables.product.prodname_dotcom %} can issue an OIDC token for the workflow.
+* The `docker/login-action` handles the OIDC token exchange and Docker login in a single step when `DOCKERHUB_OIDC_CONNECTIONID` is set and `password` is omitted.


Same note here about DOCKERHUB_OIDC_CONNECTIONID using underscores vs hyphens.

jc-clark · 2026-08-05T23:35:50Z

+          connection_id: YOUR_CONNECTION_ID
+
+      - name: Sign in to Docker Hub
+        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
+        with:
+          username: YOUR_DOCKER_ORG


Suggested change

connection_id: YOUR_CONNECTION_ID

- name: Sign in to Docker Hub

uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1

with:

username: YOUR_DOCKER_ORG

connection_id: YOUR-CONNECTION-ID

- name: Sign in to Docker Hub

uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1

with:

username: YOUR-DOCKER-ORG

jc-clark · 2026-08-05T23:38:43Z

+## Further reading
+
+* [AUTOTITLE](/actions/concepts/security/openid-connect)


Since this is linked earlier, we can remove this section.

Suggested change

## Further reading

* [AUTOTITLE](/actions/concepts/security/openid-connect)

github-actions · 2026-08-05T23:44:50Z

Thanks for opening a pull request! We've triaged this issue for technical review by a subject matter expert 👀

Copilot AI review requested due to automatic review settings July 21, 2026 21:29

github-actions Bot added the triage Do not begin working on this issue until triaged by the team label Jul 21, 2026

Copilot started reviewing on behalf of gmondello July 21, 2026 21:30 View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

gmondello commented Jul 21, 2026

View reviewed changes

Comment thread content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md Outdated

Use immutable SHA refs for all GitHub Actions in workflow example

1791b9b

gmondello commented Jul 21, 2026

View reviewed changes

Comment thread content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md Outdated

gmondello commented Jul 21, 2026

View reviewed changes

Comment thread content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md Outdated

gmondello added 4 commits July 21, 2026 17:41

Replace literal 'personal access tokens' with Liquid variable

bc657ad

Replace Docker Hub with Docker where scope is broader than registry

18f1857

OIDC connections scope access to Docker Hub and Docker Build Cloud, not just Docker Hub. Keep Docker Hub only where specifically referring to registry operations.

akristen reviewed Jul 28, 2026

View reviewed changes

Comment thread content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md Outdated

Update content/actions/how-tos/secure-your-work/security-harden-deplo…

dcaf739

…yments/oidc-in-docker.md Co-authored-by: Alexa Kristensen <81787716+akristen@users.noreply.github.com>

jc-clark reviewed Aug 5, 2026

View reviewed changes

jc-clark added the needs SME This proposal needs review from a subject matter expert label Aug 5, 2026

		## Further reading

		* [AUTOTITLE](/actions/concepts/security/openid-connect)

Uh oh!

Conversation

gmondello commented Jul 21, 2026

Summary

Changes

References

Uh oh!

welcome Bot commented Jul 21, 2026

Uh oh!

github-actions Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to review these changes 👓

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jc-clark left a comment

Choose a reason for hiding this comment

Uh oh!

jc-clark Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

jc-clark Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

jc-clark Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

jc-clark Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Aug 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions Bot commented Jul 21, 2026 •

edited

Loading