Skip to content

hub: refresh gated distribution #25933

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
craig-osterhout wants to merge 1 commit into
base: main
Choose a base branch
from
+126 −29
Draft

hub: refresh gated distribution #25933

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
155 changes: 126 additions & 29 deletions content/manuals/docker-hub/repos/manage/access.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,39 +137,136 @@ tokens](/manuals/enterprise/security/access-tokens.md).

{{< summary-bar feature_name="Gated distribution" >}}

Gated distribution allows publishers to securely share private container images with external customers or partners, without giving them full organization access or visibility into your teams, collaborators, or other repositories.

This feature is ideal for commercial software publishers who want to control who can pull specific images while preserving a clean separation between internal users and external consumers.

If you are interested in Gated Distribution contact the <a href="https://www.docker.com/pricing/contact-sales/" id="dkr_docs_cs_hub_gated_distribution" class="link" rel="noopener">Docker Sales Team</a> for more information.

### Key features

- **Private repository distribution**: Content is stored in private repositories and only accessible to explicitly invited users.

- **External access without organization membership**: External users don't need to be added to your internal organization to pull images.

- **Pull-only permissions**: External users receive pull-only access and cannot push or modify repository content.

- **Invite-only access**: Access is granted through authenticated email invites, managed via API.
Gated distribution allows publishers to securely share private container images
with external customers or partners, without giving them full organization
access or visibility into your teams, collaborators, or other repositories.
Content stays in private repositories, and external users can pull from them
without being added to your internal organization.

This feature is ideal for commercial software publishers who want to control who
can pull specific images while preserving a clean separation between internal
users and external consumers.

If you are interested in Gated Distribution contact the <a
href="https://www.docker.com/pricing/contact-sales/"
id="dkr_docs_cs_hub_gated_distribution" class="link" rel="noopener">Docker Sales
Team</a> for more information.

### Distributor members

When you invite users to an organization entitled with gated distribution, you
assign them a role that determines their level of access. For gated
distribution, external users are invited as **distributor members** within a
specific team that you create. This role grants pull-only access to the
repositories assigned to that team, and nothing else in your organization. See
[Roles and permissions](/manuals/enterprise/security/roles-and-permissions.md)
for details about the access permissions for other roles.

Distributor members can't see other members in their team or organization, and
they can't see any repositories other than the ones their team has been granted
access to. This isolation is what makes the role suitable for distributing gated
images to external users, partners, or customers without exposing internal
collaborators, teams, or repositories.

Because distributor members consume licenses allocated for that role, consider
provisioning a separate organization for gated distribution rather than adding
distributor members to your main organization. This keeps regular members from
inadvertently consuming the licenses set aside for external distribution.

### Invite distributor members via API

> [!NOTE]
> When you invite members, you assign them a role. See [Roles and permissions](/manuals/enterprise/security/roles-and-permissions.md) for details about the access permissions for each role.
> [!NOTE] You must be an organization owner to create teams and send invites.

Distributor members (used for gated distribution) can only be invited using the Docker Hub API. UI-based invitations are not currently supported for this role. To invite distributor members, use the Bulk create invites API endpoint.
Distributor members can only be invited using the Docker Hub API. UI-based
invitations are not currently supported for this role. To invite distributor
members, use the Bulk create invites API endpoint.

To invite distributor members:

1. Use the [Authentication API](https://docs.docker.com/reference/api/hub/latest/#tag/authentication-api/operation/AuthCreateAccessToken) to generate a bearer token for your Docker Hub account.

2. Create a team in the Hub UI or use the [Teams API](https://docs.docker.com/reference/api/hub/latest/#tag/groups/paths/~1v2~1orgs~1%7Borg_name%7D~1groups/post).

3. Grant repository access to the team:
- In the Hub UI: Navigate to your repository settings and add the team with "Read-only" permissions
- Using the [Repository Teams API](https://docs.docker.com/reference/api/hub/latest/#tag/repositories/paths/~1v2~1repositories~1%7Bnamespace%7D~1%7Brepository%7D~1groups/post): Assign the team to your repositories with "read-only" access level

4. Use the [Bulk create invites endpoint](https://docs.docker.com/reference/api/hub/latest/#tag/invites/paths/~1v2~1invites~1bulk/post) to send email invites with the distributor member role. In the request body, set the "role" field to "distributor_member".

5. The invited user will receive an email with a link to accept the invite. After signing in with their Docker ID, they'll be granted pull-only access to the specified private repository as a distributor member.
1. Use the [Authentication
API](https://docs.docker.com/reference/api/hub/latest/#tag/authentication-api/operation/AuthCreateAccessToken)
to generate a bearer token for your Docker Hub account. This token authorizes
the API requests you use to send invites. Replace `myusername` and
`dckr_pat_...` with your Docker ID and a [personal access
token](/manuals/security/access-tokens.md):

```console
$ TOKEN=$(curl -s -X POST "https://hub.docker.com/v2/auth/token" \
-H "Content-Type: application/json" \
-d '{"identifier": "myusername", "secret": "dckr_pat_..."}' \
| jq -r .access_token)
```

2. Create a team to group the distributor members and assign them a shared set
of repository permissions.

{{< tabs >}} {{< tab name="Hub UI" >}}

Navigate to your organization and create a new team.

{{< /tab >}} {{< tab name="Teams API" >}}

Use the [Teams
API](https://docs.docker.com/reference/api/hub/latest/#tag/groups/paths/~1v2~1orgs~1%7Borg_name%7D~1groups/post):

```console
$ curl -s -X POST "https://hub.docker.com/v2/orgs/example-org/groups" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "customer-team", "description": "External distributor members"}'
```

The response includes the new team's `id`. Save it for the next step, for
example `GROUP_ID=12345`.

{{< /tab >}} {{< /tabs >}}

3. Grant the team read-only access to the repositories you want distributor
members to access.

{{< tabs >}} {{< tab name="Hub UI" >}}

Navigate to the repository, open **Repository settings**, add the team under
**Team access**, and then assign the **Read-only** permission level.

{{< /tab >}} {{< tab name="Repository Teams API" >}}

Use the [Repository Teams
API](https://docs.docker.com/reference/api/hub/latest/#tag/repositories/paths/~1v2~1repositories~1%7Bnamespace%7D~1%7Brepository%7D~1groups/post),
passing the team's `id` from the previous step as `group_id`:

```console
$ curl -s -X POST "https://hub.docker.com/v2/repositories/example-org/example-repo/groups" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "{\"group_id\": $GROUP_ID, \"permission\": \"read\"}"
```

{{< /tab >}} {{< /tabs >}}

4. Use the [Bulk create invites
endpoint](https://docs.docker.com/reference/api/hub/latest/#tag/invites/paths/~1v2~1invites~1bulk/post)
to send email invites. In the request body, set `role` to
`distributor_member`, specify the `team`, and list the invitees' email
addresses:

```console
$ curl -s -X POST "https://hub.docker.com/v2/invites/bulk" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"org": "example-org",
"team": "customer-team",
"role": "distributor_member",
"invitees": ["user@example.com"]
}'
```

This sends email invitations to the specified users and automatically assigns
them to the team.

5. The invited user receives an email invitation from Docker Hub. When they
select the link in the email, they sign in with their Docker ID (or create
one if needed) to accept the invite. Once accepted, they're added to the
organization as a distributor member with pull-only access to the
repositories assigned to their team.