From d418d162376a7a821844bda97e8ec3b7da64cb1b Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Tue, 25 Aug 2026 13:42:08 -0700 Subject: [PATCH] hub: refresh gated distribution Signed-off-by: Craig Osterhout --- .../manuals/docker-hub/repos/manage/access.md | 155 ++++++++++++++---- 1 file changed, 126 insertions(+), 29 deletions(-) diff --git a/content/manuals/docker-hub/repos/manage/access.md b/content/manuals/docker-hub/repos/manage/access.md index c88d3492cfb3..dd945292d6c5 100644 --- a/content/manuals/docker-hub/repos/manage/access.md +++ b/content/manuals/docker-hub/repos/manage/access.md @@ -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 Docker Sales Team 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 Docker Sales +Team 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.