Merge branch 'main' into settings-reference

sarahsanders-docker · web-flow · commit 6358697b6cc9 · 2025-05-14T17:32:47.000-04:00
diff --git a/Dockerfile b/Dockerfile
@@ -2,7 +2,7 @@
 # check=skip=InvalidBaseImagePlatform
 
 ARG ALPINE_VERSION=3.21
-ARG GO_VERSION=1.23.8
+ARG GO_VERSION=1.24
 ARG HTMLTEST_VERSION=0.17.0
 ARG HUGO_VERSION=0.141.0
 ARG NODE_VERSION=22
diff --git a/content/manuals/admin/faqs/general-faqs.md b/content/manuals/admin/faqs/general-faqs.md
@@ -27,7 +27,7 @@ Additionally, you can't reuse a Docker ID in the future if you deactivate your a
 
 ### What if my Docker ID is taken?
 
-All Docker IDs are first-come, first-served except for companies that have a US Trademark on a username. If you have a trademark for your namespace, [Docker Support](https://hub.docker.com/support/contact/) can retrieve the Docker ID for you.
+All Docker IDs are first-come, first-served except for companies that have a U.S. Trademark on a username. If you have a trademark for your namespace, [Docker Support](https://hub.docker.com/support/contact/) can retrieve the Docker ID for you.
 
 ### What’s an organization?
 
@@ -66,7 +66,7 @@ The organization owner can also add additional owners to help them manage users,
 
 ### Can I configure multiple SSO identity providers (IdPs) to authenticate users to a single org?
 
-Docker SSO allows only one IdP configuration per organization. For more
+Yes. Docker SSO supports multiple IdP configurations. For more
 information, see [Configure SSO](../../security/for-admins/single-sign-on/configure/_index.md) and [SSO FAQs](../../security/faqs/single-sign-on/faqs.md).
 
 ### What is a service account?
diff --git a/content/manuals/build/cache/backends/_index.md b/content/manuals/build/cache/backends/_index.md
@@ -179,3 +179,6 @@ $ docker buildx build --push -t <registry>/<image> \
   --cache-to type=registry,ref=<registry>/<cache-image>,oci-mediatypes=true,image-manifest=true \
   --cache-from type=registry,ref=<registry>/<cache-image> .
 ```
+
+> [!NOTE]
+> Since BuildKit v0.21, `image-manifest` is enabled by default.
diff --git a/content/manuals/build/cache/backends/local.md b/content/manuals/build/cache/backends/local.md
@@ -25,13 +25,13 @@ The following table describes the available CSV parameters that you can pass to
 `--cache-to` and `--cache-from`.
 
 | Name                | Option       | Type                    | Default | Description                                                                                                                     |
-| ------------------- | ------------ | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
+|---------------------|--------------|-------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------|
 | `src`               | `cache-from` | String                  |         | Path of the local directory where cache gets imported from.                                                                     |
 | `digest`            | `cache-from` | String                  |         | Digest of manifest to import, see [cache versioning][4].                                                                        |
 | `dest`              | `cache-to`   | String                  |         | Path of the local directory where cache gets exported to.                                                                       |
 | `mode`              | `cache-to`   | `min`,`max`             | `min`   | Cache layers to export, see [cache mode][1].                                                                                    |
 | `oci-mediatypes`    | `cache-to`   | `true`,`false`          | `true`  | Use OCI media types in exported manifests, see [OCI media types][2].                                                            |
-| `image-manifest`    | `cache-to`   | `true`,`false`          | `false` | When using OCI media types, generate an image manifest instead of an image index for the cache image, see [OCI media types][2]. |
+| `image-manifest`    | `cache-to`   | `true`,`false`          | `true`  | When using OCI media types, generate an image manifest instead of an image index for the cache image, see [OCI media types][2]. |
 | `compression`       | `cache-to`   | `gzip`,`estargz`,`zstd` | `gzip`  | Compression type, see [cache compression][3].                                                                                   |
 | `compression-level` | `cache-to`   | `0..22`                 |         | Compression level, see [cache compression][3].                                                                                  |
 | `force-compression` | `cache-to`   | `true`,`false`          | `false` | Forcibly apply compression, see [cache compression][3].                                                                         |
diff --git a/content/manuals/build/cache/backends/registry.md b/content/manuals/build/cache/backends/registry.md
@@ -37,11 +37,11 @@ The following table describes the available CSV parameters that you can pass to
 `--cache-to` and `--cache-from`.
 
 | Name                | Option                  | Type                    | Default | Description                                                                                                                     |
-| ------------------- | ----------------------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
+|---------------------|-------------------------|-------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------|
 | `ref`               | `cache-to`,`cache-from` | String                  |         | Full name of the cache image to import.                                                                                         |
 | `mode`              | `cache-to`              | `min`,`max`             | `min`   | Cache layers to export, see [cache mode][1].                                                                                    |
 | `oci-mediatypes`    | `cache-to`              | `true`,`false`          | `true`  | Use OCI media types in exported manifests, see [OCI media types][2].                                                            |
-| `image-manifest`    | `cache-to`              | `true`,`false`          | `false` | When using OCI media types, generate an image manifest instead of an image index for the cache image, see [OCI media types][2]. |
+| `image-manifest`    | `cache-to`              | `true`,`false`          | `true`  | When using OCI media types, generate an image manifest instead of an image index for the cache image, see [OCI media types][2]. |
 | `compression`       | `cache-to`              | `gzip`,`estargz`,`zstd` | `gzip`  | Compression type, see [cache compression][3].                                                                                   |
 | `compression-level` | `cache-to`              | `0..22`                 |         | Compression level, see [cache compression][3].                                                                                  |
 | `force-compression` | `cache-to`              | `true`,`false`          | `false` | Forcibly apply compression, see [cache compression][3].                                                                         |
diff --git a/content/manuals/build/metadata/annotations.md b/content/manuals/build/metadata/annotations.md
@@ -11,7 +11,7 @@ arbitrary information and attach it to your image, which helps consumers and
 tools understand the origin, contents, and how to use the image.
 
 Annotations are similar to, and in some sense overlap with, [labels]. Both
-serve the same purpose: attach metadata to a resource. As a general principle,
+serve the same purpose: to attach metadata to a resource. As a general principle,
 you can think of the difference between annotations and labels as follows:
 
 - Annotations describe OCI image components, such as [manifests], [indexes],
@@ -68,7 +68,7 @@ For examples on how to add annotations to images built with GitHub Actions, see
 You can also add annotations to an image created using `docker buildx
 imagetools create`. This command only supports adding annotations to an index
 or manifest descriptors, see
-[CLI reference](/reference/cli/docker/buildx/imagetools/create.md#annotations).
+[CLI reference](/reference/cli/docker/buildx/imagetools/create.md#annotation).
 
 ## Inspect annotations
 
diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/faq.md b/content/manuals/desktop/setup/install/enterprise-deployment/faq.md
@@ -83,4 +83,18 @@ Add-LocalGroupMember -Group $Group -Member $CurrentUser
 
 > [!NOTE]
 >
-> After adding a new user to the `docker-users` group, the user must sign out and then sign back in for the changes to take effect.
+> After adding a new user to the `docker-users` group, the user must sign out and then sign back in for the changes to take effect.
+
+## MDM
+
+Common questions about deploying Docker Desktop using mobile device management
+(MDM) tools such as Jamf, Intune, or Workspace ONE.
+
+### Why doesn't my MDM tool apply all Docker Desktop configuration settings at once?
+
+Some MDM tools, such as Workspace ONE, may not support applying multiple
+configuration settings in a single XML file. In these cases, you may need to
+deploy each setting in a separate XML file.
+
+Refer to your MDM provider's documentation for specific deployment
+requirements or limitations.
diff --git a/content/manuals/docker-hub/repos/manage/access.md b/content/manuals/docker-hub/repos/manage/access.md
@@ -132,3 +132,42 @@ To configure team repository permissions:
 Organizations can use OATs. OATs let you assign fine-grained repository access
 permissions to tokens. For more details, see [Organization access
 tokens](/manuals/security/for-admins/access-tokens.md).
+
+## Gated distribution
+
+{{< 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.
+
+### 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.
+
+### Invite distributor members via API
+
+> [!NOTE]
+> When you invite members, you assign them a role. See [Roles and permissions](/manuals/security/for-admins/roles-and-permissions.md) for details about the access permissions for each role.
+
+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.
+
+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.
diff --git a/content/manuals/docker-hub/repos/manage/hub-images/immutable-tags.md b/content/manuals/docker-hub/repos/manage/hub-images/immutable-tags.md
@@ -0,0 +1,50 @@
+---
+description: Learn about immutable tags and how they help maintain image version consistency on Docker Hub.
+keywords: Docker Hub, Hub, repository content, tags, immutable tags, version control
+title: Immutable tags on Docker Hub
+linkTitle: Immutable tags
+weight: 11
+---
+{{< summary-bar feature_name="Immutable tags" >}}
+
+Immutable tags provide a way to ensure that specific image versions remain unchanged once they are published to Docker Hub. This feature helps maintain consistency and reliability in your container deployments by preventing accidental overwrites of important image versions.
+
+## What are immutable tags?
+
+Immutable tags are image tags that, once pushed to Docker Hub, cannot be overwritten or deleted. This ensures that a specific version of an image remains exactly the same throughout its lifecycle, providing:
+
+- Version consistency
+- Reproducible builds
+- Protection against accidental overwrites
+- Better security and compliance
+
+## Enable immutable tags
+
+To enable immutable tags for your repository:
+
+1. Sign in to [Docker Hub](https://hub.docker.com).
+2. Select **My Hub** > **Repositories**.
+3. Select the repository where you want to enable immutable tags.
+4. Select the **Settings** tab
+5. Under **Tag mutability settings**, select **Immutable**.
+6. Select **Save**.
+
+Once enabled, all tags are locked to their specific images, ensuring that each tag always points to the same image version and cannot be modified.
+
+ > [!NOTE]
+>
+> All tags in the repository become immutable, including the `latest` tag.
+
+## Working with immutable tags
+
+When immutable tags are enabled:
+
+- You cannot push a new image with the same tag name
+- You must use a new tag name for each new image version
+
+To push an image, create a new tag for your updated image and push it to the repository.
+
+
+
+
+
diff --git a/content/manuals/engine/install/debian.md b/content/manuals/engine/install/debian.md
@@ -42,6 +42,7 @@ To get started with Docker Engine on Debian, make sure you
 To install Docker Engine, you need the 64-bit version of one of these Debian
 versions:
 
+- Debian Trixie 13 (testing)
 - Debian Bookworm 12 (stable)
 - Debian Bullseye 11 (oldstable)
 
@@ -144,7 +145,7 @@ Docker from the repository.
    ```console
    $ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
    ```
-  
+
    {{< /tab >}}
    {{< tab name="Specific version" >}}
 
diff --git a/content/manuals/engine/install/fedora.md b/content/manuals/engine/install/fedora.md
@@ -26,8 +26,9 @@ To get started with Docker Engine on Fedora, make sure you
 To install Docker Engine, you need a maintained version of one of the following
 Fedora versions:
 
-- Fedora 40
+- Fedora 42
 - Fedora 41
+- Fedora 40
 
 ### Uninstall old versions
 
diff --git a/content/manuals/security/faqs/single-sign-on/idp-faqs.md b/content/manuals/security/faqs/single-sign-on/idp-faqs.md
@@ -11,7 +11,7 @@ aliases:
 
 ### Is it possible to use more than one IdP with Docker SSO?
 
-No. You can only configure Docker SSO to work with a single IdP. A domain can only be associated with a single IdP. Docker supports Entra ID (formerly Azure AD) and identity providers that support SAML 2.0.
+Yes. Docker supports multiple IdP configurations. A domain can be associated with multiple IdPs. Docker supports Entra ID (formerly Azure AD) and identity providers that support SAML 2.0.
 
 ### Is it possible to change my identity provider after configuring SSO?
 
@@ -57,4 +57,4 @@ Yes, Entra ID (formerly Azure AD) is supported with SSO for Docker Business, bot
 
 ### My SSO connection with Entra ID isn't working and I receive an error that the application is misconfigured. How can I troubleshoot this?
 
-Confirm that you've configured the necessary API permissions in Entra ID (formerly Azure AD) for your SSO connection. You need to grant admin consent within your Entra ID (formerly Azure AD) tenant. See [Entra ID (formerly Azure AD) documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent?pivots=portal#grant-admin-consent-in-app-registrations).
+Confirm that you've configured the necessary API permissions in Entra ID (formerly Azure AD) for your SSO connection. You need to grant administrator consent within your Entra ID (formerly Azure AD) tenant. See [Entra ID (formerly Azure AD) documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent?pivots=portal#grant-admin-consent-in-app-registrations).
diff --git a/content/manuals/security/for-admins/roles-and-permissions.md b/content/manuals/security/for-admins/roles-and-permissions.md
@@ -20,6 +20,7 @@ When you invite users to your organization, you assign them a role. A role is a
 The following roles are available to assign:
 
 - Member: Non-administrative role. Members can view other members that are in the same organization.
+- Distributor Member: Restricted-access role. Distributor Members can only view and pull from repositories they’ve been explicitly granted access to. They cannot view other members or teams.
 - Editor: Partial administrative access to the organization. Editors can create, edit, and delete repositories. They can also edit an existing team's access permissions.
 - Organization owner: Full organization administrative access. Organization owners can manage organization repositories, teams, members, settings, and billing.
 - Company owner: In addition to the permissions of an organization owner, company owners can configure settings for their associated organizations.
diff --git a/content/manuals/security/for-admins/single-sign-on/configure.md b/content/manuals/security/for-admins/single-sign-on/configure.md
@@ -18,6 +18,10 @@ Get started creating a single sign-on (SSO) connection for your organization or
 
 ## Step one: Add your domain
 
+> [!NOTE]
+>
+> Docker supports multiple identity provider (IdP) configurations. With a multiple IdP configuration, one domain can be associated with more than one SSO identity provider.
+
 {{< tabs >}}
 {{< tab name="Admin Console" >}}
 
diff --git a/content/manuals/security/for-admins/single-sign-on/connect.md b/content/manuals/security/for-admins/single-sign-on/connect.md
@@ -202,15 +202,20 @@ After you've completed the SSO connection process in Docker, we recommend testin
 
 1. Open an incognito browser.
 2. Sign in to the Admin Console using your **domain email address**.
-3. The browser will redirect to your IdP's login page to authenticate.
+3. The browser will redirect to your identity provider's sign in page to authenticate. If you have [multiple IdPs](#optional-configure-multiple-idps), choose the sign sign-in option **Continue with SSO**.
 4. Authenticate through your domain email instead of using your Docker ID.
 
 You can also test your SSO connection through the command-line interface (CLI). If you want to test through the CLI, your users must have a personal access token (PAT).
 
+## Optional: Configure multiple IdPs
+
+Docker supports multiple IdP configurations. With multiple IdPs configured, one domain can be associated with multiple SSO identity providers. To configure multiple IdPs, repeat steps 1-4 in this guide for each IdP. Ensure each IdP configuration uses the same domain.
+
+When a user signs in to a Docker organization that has multiple IdPs, on the sign-in page, they must choose the option **Continue with SSO**. This prompts them to choose their identity provider and authenticate through their domain email.
 
 ## Optional: Enforce SSO
 
->[!IMPORTANT]
+> [!IMPORTANT]
 >
 > If SSO isn't enforced, users can choose to sign in with either their Docker username and password or SSO.
 
diff --git a/content/manuals/subscription/change.md b/content/manuals/subscription/change.md
@@ -12,6 +12,7 @@ aliases:
 - /docker-hub/cancel-downgrade/
 - /docker-hub/billing/downgrade/
 - /billing/scout-billing/
+- /billing/subscription-management/
 weight: 30
 ---
 
diff --git a/data/summary.yaml b/data/summary.yaml
@@ -173,6 +173,8 @@ Domain management:
 Enforce sign-in:
   subscription: [Business]
   for: Administrators
+Gated distribution:
+  availability: Early Access
 General admin:
   for: Administrators
 GitHub Actions cache:
@@ -182,6 +184,8 @@ Hardened Docker Desktop:
   for: Administrators
 Image management:
   availability: Beta
+Immutable tags:
+  availability: Beta
 Import builds:
   availability: Beta
   requires: Docker Desktop [4.31](/manuals/desktop/release-notes.md#4310) and later
diff --git a/go.mod b/go.mod
@@ -1,8 +1,6 @@
 module github.com/docker/docs
 
-go 1.23.8
-
-toolchain go1.24.1
+go 1.24.0
 
 require (
 	github.com/docker/buildx v0.23.0 // indirect
diff --git a/hack/releaser/Dockerfile b/hack/releaser/Dockerfile
@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1
 
-ARG GO_VERSION=1.23
+ARG GO_VERSION=1.24
 
 FROM scratch AS sitedir
 
diff --git a/hack/releaser/go.mod b/hack/releaser/go.mod
@@ -1,6 +1,6 @@
 module github.com/docker/docs/hack/releaser
 
-go 1.22
+go 1.24.0
 
 require (
 	github.com/alecthomas/kong v1.4.0
diff --git a/hugo.yaml b/hugo.yaml
@@ -145,7 +145,7 @@ params:
   buildkit_version: "0.21.0"
 
   # Example runtime/library/os versions
-  example_go_version: "1.23"
+  example_go_version: "1.24"
   example_alpine_version: "3.21"
   example_node_version: "20"
 
diff --git a/hugo_stats.json b/hugo_stats.json
diff --git a/layouts/_default/baseof.html b/layouts/_default/baseof.html
diff --git a/layouts/partials/footer.html b/layouts/partials/footer.html
diff --git a/layouts/shortcodes/admin-domain-audit.md b/layouts/shortcodes/admin-domain-audit.md
diff --git a/layouts/shortcodes/admin-sso-management.md b/layouts/shortcodes/admin-sso-management.md
