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.

+1. Sign in to [Docker Home](https://app.docker.com/) and navigate to your organization.
+1. Go to **Identity & auth** > **OIDC connections**.
+1. Select **Create OIDC connection**.
+1. Configure at least one ruleset to define which GitHub repositories, branches, or workflows can authenticate. Each ruleset specifies:


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


+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4


+
+      - name: Get Docker OIDC token
+        id: docker-oidc
+        uses: docker/oidc-action@v1


+          connection_id: YOUR_CONNECTION_ID
+
+      - name: Sign in to Docker Hub
+        uses: docker/login-action@v4


+          password: {% raw %}${{ steps.docker-oidc.outputs.token }}{% endraw %}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6


+Docker evaluates the `sub` claim from the {% data variables.product.prodname_dotcom %} OIDC token against the rulesets you configured. The default subject claim format is:
+
+```text
+repo:<owner>/<repo>:ref:refs/heads/<branch>
+```
+
+Different workflow triggers produce different subject claims. For example:
+
+| Trigger | Subject claim format |
+|---------|---------------------|
+| Branch push | `repo:my-org/my-repo:ref:refs/heads/main` |
+| Pull request | `repo:my-org/my-repo:pull_request` |
+| Tag | `repo:my-org/my-repo:ref:refs/tags/v1.0` |
+| Environment | `repo:my-org/my-repo:environment:production` |
+
+You can use wildcard patterns in your rulesets to match multiple repositories or branches. For example, `repo:my-org/*` matches all repositories in your organization.


+
+* You must have a Docker Business or Docker Team subscription.
+* You must be an organization owner or editor in your Docker organization.
+* You should plan which repositories, branches, and workflows need access to Docker Hub, and configure rulesets accordingly. For more information, see [Rulesets and subject claims](https://docs.docker.com/enterprise/security/oidc-connections/rulesets-claims/) in the Docker documentation.


+* [OIDC connections overview](https://docs.docker.com/enterprise/security/oidc-connections/) in the Docker documentation
+* [Create and manage OIDC connections](https://docs.docker.com/enterprise/security/oidc-connections/create-manage/) in the Docker documentation
+* [Rulesets and subject claims](https://docs.docker.com/enterprise/security/oidc-connections/rulesets-claims/) in the Docker documentation
+* [AUTOTITLE](/actions/concepts/security/openid-connect)


gmondello · 2026-07-21T22:31:26Z

+
+      - name: Get Docker OIDC token
+        id: docker-oidc
+        uses: docker/oidc-action@v1


Suggested change

uses: docker/oidc-action@v1

uses: docker/oidc-action@3f002d200df5620744c973221788e401898c6f86 # v1

gmondello · 2026-07-21T22:34:33Z

+          connection_id: YOUR_CONNECTION_ID
+
+      - name: Sign in to Docker Hub
+        uses: docker/login-action@v4


Suggested change

uses: docker/login-action@v4

uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0

gmondello · 2026-07-21T22:35:06Z

+          password: {% raw %}${{ steps.docker-oidc.outputs.token }}{% endraw %}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6


Suggested change

uses: docker/build-push-action@v6

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

- 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)

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

Use immutable SHA refs for all GitHub Actions in workflow example

1791b9b

gmondello commented Jul 21, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add OIDC in Docker guide for GitHub Actions deployments#45243

Add OIDC in Docker guide for GitHub Actions deployments#45243
gmondello wants to merge 3 commits into
github:mainfrom
gmondello:add-oidc-in-docker

gmondello commented Jul 21, 2026

Uh oh!

welcome Bot commented Jul 21, 2026

Uh oh!

github-actions Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

gmondello Jul 21, 2026

Uh oh!

gmondello Jul 21, 2026

Uh oh!

gmondello Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


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

		```yaml

	uses: docker/oidc-action@v1
	uses: docker/oidc-action@3f002d200df5620744c973221788e401898c6f86 # v1

	uses: docker/login-action@v4
	uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0

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

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!

gmondello Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gmondello Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gmondello Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Jul 21, 2026 •

edited

Loading