Skip to content

Single step action #25834

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
akristen wants to merge 1 commit into
base: main
Choose a base branch
from
+39 −81
Draft

Single step action #25834

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 39 additions & 81 deletions content/manuals/enterprise/security/oidc-connections/create-manage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,131 +1,89 @@
---
title: Create and manage OIDC connections
linkTitle: Create and manage connections
description: Create, update, and delete OIDC connections for your organization
keywords: oidc connections, create oidc connection, github actions, docker/oidc-action, openid connect, enterprise security, admin
description: Create and manage OIDC connections in Docker Home, then authenticate GitHub Actions to Docker Hub with docker/login-action and short-lived tokens
keywords: oidc connections, create oidc connection, github actions, docker/login-action, DOCKERHUB_OIDC_CONNECTIONID, openid connect, docker hub, enterprise security, admin
tags: [admin]
weight: 10
---

{{< summary-bar feature_name="OIDC connections" >}}

Organization owners and editors can create OIDC connections or manage
existing ones from **OIDC connections** in Docker Home. Establishing an
OIDC connection occurs in two phases. First, you create the OIDC
connection in Docker Home, then you configure your GitHub Actions workflow
YAML file.
Organization owners and editors create and manage OIDC connections from
**OIDC connections** in Docker Home. After you create a connection,
configure your GitHub Actions workflow so it can sign in to Docker Hub
with a short-lived token.

> [!NOTE]
> OIDC connections support only GitHub as a trusted third party.

## Set up GitHub Actions authentication

### Step 1: Create the OIDC connection
## Create an OIDC connection

1. Sign in to [Docker Home](https://app.docker.com/), select your
organization, then go to **Identity & auth**.
1. Select **OIDC connections**.
1. Select **Create OIDC connection** and fill in the OIDC connection form.
- You must provide rulesets and subject claims. Other values are
optional.
- Provide rulesets and subject claims. Other values are optional.
- For rulesets, subject claims, and resources, see
[OIDC connections rulesets and subject claims](/manuals/enterprise/security/oidc-connections/rulesets-claims.md).
1. Select **Create connection**.
1. Copy your OIDC connection ID.

### Step 2: Define the GitHub Actions workflow
## Configure a GitHub Actions workflow

1. Add a top-level `permissions` key that requests a GitHub OIDC ID token:
Use `docker/login-action` version 4.5.0 or later. The action exchanges
the GitHub OIDC token and signs in to Docker Hub in a single step.

```yaml
permissions:
id-token: write
```

1. Define a job that triggers the OIDC exchange. Update `connection_id`
with the connection ID you copied from Docker:

```yaml
jobs:
login:
runs-on: ubuntu-latest
steps:
- name: OIDC connections
id: docker_oidc
uses: docker/oidc-action@v1
with:
connection_id: <YOUR_CONNECTION_ID>
```

1. Add a step that signs in to Docker with an access token once the ID
token passes authentication:

```yaml
- name: Sign in to Docker Hub
uses: docker/login-action@{{% param "login_action_version" %}}
with:
username: <DOCKER_ORGANIZATION_NAME>
password: ${{ steps.docker_oidc.outputs.token }}
```

The `username` value must be an organization name. Personal accounts
aren't supported.

Your updated workflow YAML should look like this:
1. Add the following `permissions` and `steps` to your workflow YAML.
Replace `<YOUR_ORG_NAME>` with your Docker organization name and
`<YOUR_CONNECTION_ID>` with the ID you copied from Docker Home:

```yaml
permissions:
contents: read
id-token: write

jobs:
login:
runs-on: ubuntu-latest
steps:
- name: OIDC connections
id: docker_oidc
uses: docker/oidc-action@v1
with:
connection_id: <YOUR_CONNECTION_ID>

- name: Sign in to Docker Hub
uses: docker/login-action@{{% param "login_action_version" %}}
with:
username: <YOUR_ORGANIZATION_NAME>
password: ${{ steps.docker_oidc.outputs.token }}
steps:

@docker-agent docker-agent Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] YAML snippet shows permissions and steps as peer keys — missing jobs: context

The example places permissions: and steps: at the same indentation level with no enclosing job block. In a real GitHub Actions workflow, steps: must live inside a named job under jobs:, not as a top-level or sibling key. A user copying this snippet verbatim and adding it as top-level YAML would produce an invalid workflow file.

Consider showing the full minimal job context:

permissions:
  contents: read
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Docker login
        uses: docker/login-action@v4 # v4.5.0+
        with:
          username: <YOUR_ORG_NAME>
        env:
          DOCKERHUB_OIDC_CONNECTIONID: <YOUR_CONNECTION_ID>

Or, if a partial snippet is intentional, add a note such as "Add permissions at the workflow level and the step inside your existing job's steps: list."

- name: Docker login
uses: docker/login-action@v4 # v4.5.0+
with:
username: <YOUR_ORG_NAME>
env:

@docker-agent docker-agent Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Verify that DOCKERHUB_OIDC_CONNECTIONID is consumed as an environment variable, not a with: input

The example places DOCKERHUB_OIDC_CONNECTIONID in a step-level env: block (sibling of with:), not as a named input inside with:. If docker/login-action v4.5.0+ reads the connection ID via environment variable, the YAML is correct. But if the action expects it as a with: input (e.g., oidc_connection_id:), users following this example will get silent authentication failures.

The PR description and front-matter keywords both reference DOCKERHUB_OIDC_CONNECTIONID, suggesting the env: placement is intentional — but it's worth confirming against the action's v4.5.0 release notes or README before this ships, since users in a security-sensitive OIDC flow will copy-paste this YAML exactly.

DOCKERHUB_OIDC_CONNECTIONID: <YOUR_CONNECTION_ID>
```

1. Run your GitHub Action and verify the workflow can sign in to Docker.
The `username` value must be a Docker organization name. Personal
accounts are not supported.

@docker-agent docker-agent Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[LOW] Negative framing — style guide prefers positive language

"Personal accounts are not supported." states what users cannot do. The Docker style guide recommends emphasizing what users can do. Consider:

The username value must be a Docker organization name. Only organization accounts can sign in using OIDC.


1. Run the workflow and confirm it can sign in to Docker.

## Manage OIDC connections

You can view, edit, deactivate, or delete connections from the **OIDC
connections** page.

1. From **Identity & auth**, go to **OIDC connections**.
1. From the **OIDC connections** page, find the row with your target
connection ID.
1. Select **Identity & auth**, then **OIDC connections**.
1. Find the row with your target connection ID.
1. Select the action menu icon for your options.
- **Edit** opens the **Edit OIDC connection** page where you can copy
your connection ID, update rulesets, or view the **Failures** table.
- **Deactivate** temporarily disables access to your GitHub workflow.
- **Activate** restores access to your GitHub workflow.
- **Delete** permanently deletes a connection.

## Deactivation and deletion

You can deactivate an OIDC connection to pause GitHub workflow access to
your Docker resources without deleting the connection. While a connection
is deactivated:
## Deactivate or delete a connection

- It can't issue Docker access tokens.
- Without Docker access tokens, `docker/oidc-action` fails at the
token-exchange step until you activate the connection.
Deactivate an OIDC connection to pause GitHub workflow access to your
Docker resources without deleting the connection. A deactivated
connection does not issue Docker access tokens, so `docker/login-action`
fails at the token-exchange step until you activate the connection.

Unlike deactivation, deleting an OIDC connection is permanent. Any workflow
whose `docker/oidc-action` step still references the deleted
`connection_id` fails at the token-exchange step. Update that input with a
replacement connection's ID in every affected workflow before it runs
again.
> [!WARNING]
> Deleting an OIDC connection is permanent. Any workflow that still sets
> `DOCKERHUB_OIDC_CONNECTIONID` to the deleted ID fails at the
> token-exchange step. Update that environment variable with a
> replacement connection ID in every affected workflow before it runs
> again.

## Next steps

Expand Down