From 6f2f8cf69ab522baedcb0286ad811d0413344c1e Mon Sep 17 00:00:00 2001
From: sarahsanders-docker <sarah.sanders@docker.com>
Date: Tue, 16 Sep 2025 10:11:51 -0400
Subject: [PATCH 1/3] add custom roles docs

---
 content/manuals/docker-hub/release-notes.md   |   2 +-
 .../security/roles-and-permissions/_index.md  |  73 ++++++++
 .../roles-and-permissions/custom-roles.md     | 176 ++++++++++++++++++
 .../roles-and-permissions.md                  |   4 +-
 hugo_stats.json                               |   8 +-
 5 files changed, 257 insertions(+), 6 deletions(-)
 create mode 100644 content/manuals/enterprise/security/roles-and-permissions/_index.md
 create mode 100644 content/manuals/enterprise/security/roles-and-permissions/custom-roles.md
 rename content/manuals/enterprise/security/{ => roles-and-permissions}/roles-and-permissions.md (99%)

diff --git a/content/manuals/docker-hub/release-notes.md b/content/manuals/docker-hub/release-notes.md
index d93b4ad0e06f..898c43ddb4fa 100644
--- a/content/manuals/docker-hub/release-notes.md
+++ b/content/manuals/docker-hub/release-notes.md
@@ -53,7 +53,7 @@ known issues for each Docker Hub release.
 
 ### New
 
-- Organizations can assign the [editor role](roles-and-permissions.md) to members to grant additional permissions without full administrative access.
+- Organizations can assign the [editor role](/manuals/enterprise/security/roles-and-permissions/roles-and-permissions.md) to members to grant additional permissions without full administrative access.
 
 ## 2023-05-09
 
diff --git a/content/manuals/enterprise/security/roles-and-permissions/_index.md b/content/manuals/enterprise/security/roles-and-permissions/_index.md
new file mode 100644
index 000000000000..04e168f6ca63
--- /dev/null
+++ b/content/manuals/enterprise/security/roles-and-permissions/_index.md
@@ -0,0 +1,73 @@
+---
+title: Roles and permissions
+linkTitle: Roles and permissions
+description: Control access to content, registry, and organization management with Docker's role system
+keywords: roles, permissions, custom roles, core roles, access control, organization management, docker hub, admin console, security
+tags: [admin]
+aliases:
+ - /admin/organization/roles/
+ - /security/for-admins/roles-and-permissions/
+grid:
+  - title: "Core roles"
+    description: Learn about Docker's built-in Member, Editor, and Owner roles with predefined permissions.
+    icon: "admin_panel_settings"
+    link: /admin/organization/core-roles/
+  - title: "Custom roles"
+    description: Create tailored permission sets that match your organization's specific needs.
+    icon: "tune"
+    link: /admin/organization/custom-roles/
+weight: 40
+---
+
+{{< summary-bar feature_name="General admin" >}}
+
+Roles control what users can do in your Docker organization. When you invite users or create teams, you assign them roles that determine their permissions for repositories, teams, and organization settings.
+
+Docker provides two types of roles to meet different organizational needs:
+
+- Core roles with predefined permissions
+- Custom roles that you can tailor to your specific requirements
+
+## Core roles versus custom roles
+
+### Core roles
+
+Core roles are Docker's built-in roles with predefined permission sets:
+
+- Member: Non-administrative role with basic access. Members can view other organization members and pull images from repositories they have access to.
+- Editor: Partial administrative access. Editors can create, edit, and delete repositories, and manage team permissions for repositories.
+- Owner: Full administrative access. Owners can manage all organization settings, including repositories, teams, members, billing, and security features.
+
+### Custom roles
+
+Custom roles allow you to create tailored permission sets by selecting specific permissions from categories like user management, team management, billing, and Hub permissions. Use custom roles when Docker's core roles don't fit your needs.
+
+## When to use each type
+
+Use core roles when:
+
+- Docker's predefined permission sets match your organizational structure
+- You want simple, straightforward role assignments
+- You're getting started with Docker organization management
+- Your access control needs are standard and don't require fine-grained permissions
+
+Use custom roles when:
+- You need specific permission combinations not available in core roles
+- You want to create specialized roles like billing administrators, security auditors, or repository managers
+- You need department-specific access control
+- You want to implement the principle of least privilege with precise permission grants
+
+## How roles work together
+
+Users and teams can be assigned either a core role or a custom role, but not both. However, roles work in combination with team permissions:
+
+1. Role permissions: Applied organization-wide (core or custom role)
+2. Team permissions: Additional permissions for specific repositories when users are added to teams
+
+This layered approach gives you flexibility to provide broad organizational access through roles and specific repository access through team memberships.
+
+## Next steps
+
+Choose the role type that best fits your organization's needs:
+
+{{< grid >}}
\ No newline at end of file
diff --git a/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md b/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md
new file mode 100644
index 000000000000..66ee062330c3
--- /dev/null
+++ b/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md
@@ -0,0 +1,176 @@
+---
+title: Custom roles
+description:
+keywords:
+---
+
+Custom roles allow you to create tailored permission sets that match your
+organization's specific needs. This page covers custom roles, and steps
+to create and manage them.
+
+## What are custom roles?
+
+Custom roles let you create tailored permission sets for your organization. You
+can assign custom roles to individual users or teams, and they work alongside
+Docker's default roles (Owner, Editor, Member). Users get either a default role
+or custom role, but not both.
+
+Use custom roles when Docker's default roles don't fit your needs, such as for
+billing administrators, security auditors, repository managers, or
+department-specific access control.
+
+## Prerequisites
+
+To configure custom roles, you need owner permissions in your Docker
+organization.
+
+## Create a custom role
+
+Before you can assign a custom role to users, you must create one in the
+Admin Console:
+
+1. Sign in to [Docker Home](https://app.docker.com).
+1. Select **Admin Console**, then **User management**.
+1. Select **Roles**, then **Create role**.
+1. Create a name and describe what the role is for:
+    - Provide a **Display name**
+    - Enter a unique **Name** identifier (can't be changed later)
+    - Add an optional **Description**
+1. Set permissions for the role by expanding permission categories and selecting
+the checkboxes for permissions. For a full list of available permissions, see
+the [custom roles permissions reference](#custom-roles-permissions-reference).
+1. Select **Review** to review your custom roles configruation and see a summary
+of selected permissions.
+1. Select **Create**.
+
+With a custom role created, you can now [assign custom roles to users](#assign-custom-roles-to-users).
+
+## Edit a custom role
+
+1. Sign in to [Docker Home](https://app.docker.com).
+1. Select **Admin Console**, then **User management**.
+1. Select **Roles**.
+1. Find your custom role from the list, and select the **Actions menu**.
+1. Select **Edit**.
+1. You can edit the following custom role settings:
+    - Display name
+    - Description
+    - Permissions
+1. After you have finished editing, select **Save**.
+
+## Assign custom roles
+
+{{< tabs >}}
+{{< tab name="Individual users" >}}
+
+1. Sign in to [Docker Home](https://app.docker.com).
+1. Select **Members**.
+1. Locate the member you want to assign a custom role to, then select the
+**Actions menu**.
+1. In the drop-down, select **Change role**.
+1. In the **Select a role** drop-down, select your custom role.
+1. Select **Save**.
+
+{{< /tab >}}
+{{< tab name="Bulk users" >}}
+
+1. Sign in to [Docker Home](https://app.docker.com).
+1. Select **Members**.
+1. Use the checkboxes in the username column to select all users you want
+to assign a custom role to.
+1. Select **Change role**.
+1. In the **Select a role** drop-down, select your custom role.
+1. Select **Save**.
+
+{{< /tab >}}
+{{< tab name="Teams" >}}
+
+1. Sign in to [Docker Home](https://app.docker.com).
+1. Select **Teams**.
+1. Locate the team you want to assign a custom role to, then select
+the **Actions menu**.
+1. Select **Assign role**.
+1. Select your custom role, then select **Assign**.
+
+The role column will update to the newly assigned role.
+
+{{< /tab >}}
+{{< /tabs >}}
+
+## View role assignments
+
+To see which users and teams are assigned to roles:
+
+1. Sign in to [Docker Home](https://app.docker.com).
+1. Select **Admin Console**, then **User management**.
+1. Select **Roles**.
+1. In the roles list, view the **Users** and **Teams** columns to see
+assignment counts.
+1. Select a specific role to view its permissions adn assignments in detail.
+
+## Reassign custom roles
+
+{{< tabs >}}
+{{< tab name="Individual users" >}}
+
+1. Sign in to [Docker Home](https://app.docker.com).
+1. Select **Admin Console**, then **User management**.
+1. Select **Roles**.
+1. Find your custom role from the list, and select the **Actions menu**.
+1. Select **Reassign**.
+1. On the reassignment page, **Select a role** to reassign, then select **Save**.
+
+{{< /tab >}}
+{{< tab name="Bulk users" >}}
+
+
+{{< /tab >}}
+{{< /tabs >}}
+
+## Duplicate a custom role
+
+1. Sign in to [Docker Home](https://app.docker.com).
+1. Select **Admin Console**, then **User management**.
+1. Select **Roles**.
+1. Find your custom role from the list, and select the **Actions menu**.
+1. Select **Duplicate**.
+1. Modify the duplicated role's name, description, and permissions as needed.
+1. Select **Create** to save the new role.
+
+## Delete a custom role
+
+If you have users or teams assigned to a role, you must reassign them to new roles before deleting.
+
+1. Sign in to [Docker Home](https://app.docker.com).
+1. Select **Admin Console**, then **User management**.
+1. Select **Roles**.
+1. Find your custom role from the list, and select the **Actions menu**.
+1. If the role has assigned users or teams, select **Reassign** first to move
+them to different roles.
+1. Once no users or teams are assigned, select the **Actions menu** again.
+1. Select **Delete**.
+1. In the confirmation window, select **Delete** to confirm.
+
+## Custom roles permissions reference
+
+Custom roles can included any combination of the following permissions.
+
+### User and role management permissions
+
+- **Invite members**: Send organization invitations
+- **Manage members**: Remove users from the organizatino
+- **Manage member roles**: Assign roles to users
+- **Create custom roles**: Create, edit, and delete custom roles
+- **View member activity**: View activity logs in the organization
+- **Export and reporting**: Export users and activity logs
+
+### Team management permissions
+
+- **Create teams**:
+- **Manage teams**:
+
+### Organization configuration permissions
+
+### Billing permissions
+
+### Hub permissions
\ No newline at end of file
diff --git a/content/manuals/enterprise/security/roles-and-permissions.md b/content/manuals/enterprise/security/roles-and-permissions/roles-and-permissions.md
similarity index 99%
rename from content/manuals/enterprise/security/roles-and-permissions.md
rename to content/manuals/enterprise/security/roles-and-permissions/roles-and-permissions.md
index 7a7fa6c10dc6..e79e01366a36 100644
--- a/content/manuals/enterprise/security/roles-and-permissions.md
+++ b/content/manuals/enterprise/security/roles-and-permissions/roles-and-permissions.md
@@ -1,11 +1,11 @@
 ---
-title: Roles and permissions
+title: Core roles
 description: Control access to content, registry, and organization management with roles in your organization.
 keywords: members, teams, organization, company, roles, access, docker hub, admin console, security, permissions
 aliases:
 - /docker-hub/roles-and-permissions/
 - /security/for-admins/roles-and-permissions/
-weight: 40
+- /enterprise/security/roles-and-permissions/
 ---
 
 {{< summary-bar feature_name="General admin" >}}
diff --git a/hugo_stats.json b/hugo_stats.json
index 2ef66639cf23..c567ea2274b4 100644
--- a/hugo_stats.json
+++ b/hugo_stats.json
@@ -14,6 +14,8 @@
       "AWS-Route-53",
       "Admin-Console",
       "After",
+      "After-multi-stage",
+      "After-single-stage",
       "Angular",
       "Apt",
       "Arch",
@@ -23,6 +25,7 @@
       "Bake",
       "Bash",
       "Before",
+      "Bulk-users",
       "CLI",
       "CentOS-RHEL-and-Fedora",
       "Circle-CI",
@@ -34,7 +37,6 @@
       "Custom-builder",
       "DNS-resolution",
       "Debian",
-      "Debian-GNU/Linux",
       "Diff",
       "Docker-Build-Cloud",
       "Docker-Desktop",
@@ -72,6 +74,7 @@
       "HTTP",
       "Heredocs",
       "Hyper-V-backend-x86_64",
+      "Individual-users",
       "Inline",
       "Installation-time-setup",
       "Instant-verification",
@@ -130,6 +133,7 @@
       "Single-container",
       "Specific-version",
       "Svelte",
+      "Teams",
       "Testcontainers-Cloud",
       "Ubuntu",
       "Ubuntu/Debian",
@@ -509,8 +513,6 @@
       "rounded-full",
       "rounded-md",
       "rounded-sm",
-      "rss-button",
-      "rss-subscribe",
       "scale-50",
       "scale-75",
       "scroll-mt-2",

From dfdc4ac42bb1ef4ab551ac929e0258988c6a6c6c Mon Sep 17 00:00:00 2001
From: sarahsanders-docker <sarah.sanders@docker.com>
Date: Tue, 14 Oct 2025 09:42:21 -0400
Subject: [PATCH 2/3] update Teams

---
 .../security/roles-and-permissions/_index.md  | 12 +++++------
 ...roles-and-permissions.md => core-roles.md} |  9 ++++----
 .../roles-and-permissions/custom-roles.md     | 21 +++++++++++++------
 3 files changed, 25 insertions(+), 17 deletions(-)
 rename content/manuals/enterprise/security/roles-and-permissions/{roles-and-permissions.md => core-roles.md} (95%)

diff --git a/content/manuals/enterprise/security/roles-and-permissions/_index.md b/content/manuals/enterprise/security/roles-and-permissions/_index.md
index 04e168f6ca63..e483c6b3c788 100644
--- a/content/manuals/enterprise/security/roles-and-permissions/_index.md
+++ b/content/manuals/enterprise/security/roles-and-permissions/_index.md
@@ -11,11 +11,11 @@ grid:
   - title: "Core roles"
     description: Learn about Docker's built-in Member, Editor, and Owner roles with predefined permissions.
     icon: "admin_panel_settings"
-    link: /admin/organization/core-roles/
+    link: /enterprise/security/roles-and-permissions/core-roles/
   - title: "Custom roles"
     description: Create tailored permission sets that match your organization's specific needs.
     icon: "tune"
-    link: /admin/organization/custom-roles/
+    link: /enterprise/security/roles-and-permissions/custom-roles/
 weight: 40
 ---
 
@@ -25,10 +25,10 @@ Roles control what users can do in your Docker organization. When you invite use
 
 Docker provides two types of roles to meet different organizational needs:
 
-- Core roles with predefined permissions
-- Custom roles that you can tailor to your specific requirements
+- [Core roles](/manuals/enterprise/security/roles-and-permissions/core-roles.md) with predefined permissions
+- [Custom roles](/manuals/enterprise/security/roles-and-permissions/custom-roles.md) that you can tailor to your specific requirements
 
-## Core roles versus custom roles
+## Docker roles
 
 ### Core roles
 
@@ -42,7 +42,7 @@ Core roles are Docker's built-in roles with predefined permission sets:
 
 Custom roles allow you to create tailored permission sets by selecting specific permissions from categories like user management, team management, billing, and Hub permissions. Use custom roles when Docker's core roles don't fit your needs.
 
-## When to use each type
+## When to use each role
 
 Use core roles when:
 
diff --git a/content/manuals/enterprise/security/roles-and-permissions/roles-and-permissions.md b/content/manuals/enterprise/security/roles-and-permissions/core-roles.md
similarity index 95%
rename from content/manuals/enterprise/security/roles-and-permissions/roles-and-permissions.md
rename to content/manuals/enterprise/security/roles-and-permissions/core-roles.md
index e79e01366a36..dab08686de08 100644
--- a/content/manuals/enterprise/security/roles-and-permissions/roles-and-permissions.md
+++ b/content/manuals/enterprise/security/roles-and-permissions/core-roles.md
@@ -10,13 +10,12 @@ aliases:
 
 {{< summary-bar feature_name="General admin" >}}
 
-Roles control what users can do in your organization. When you invite users, you assign them a role that determines their permissions for repositories, teams, and organization settings.
+Core roles are Docker's built-in roles with predefined permission sets.
+This page provides an overview of Docker's core and permissions for each role.
 
-This page provides an overview of Docker roles and permissions for each role.
+## What are core roles?
 
-## Organization roles
-
-Docker organizations have three main roles:
+Docker organizations have three core roles:
 
 - Member: Non-administrative role with basic access. Members can view other organization members and pull images from repositories they have access to.
 - Editor: Partial administrative access. Editors can create, edit, and delete repositories. They can also manage team permissions for repositories.
diff --git a/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md b/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md
index 66ee062330c3..f41053858f62 100644
--- a/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md
+++ b/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md
@@ -4,6 +4,8 @@ description:
 keywords:
 ---
 
+{{< summary-bar feature_name="General admin" >}}
+
 Custom roles allow you to create tailored permission sets that match your
 organization's specific needs. This page covers custom roles, and steps
 to create and manage them.
@@ -11,13 +13,10 @@ to create and manage them.
 ## What are custom roles?
 
 Custom roles let you create tailored permission sets for your organization. You
-can assign custom roles to individual users or teams, and they work alongside
-Docker's default roles (Owner, Editor, Member). Users get either a default role
-or custom role, but not both.
+can assign custom roles to individual users or teams.
+Users get either a core role or custom role, but not both.
 
-Use custom roles when Docker's default roles don't fit your needs, such as for
-billing administrators, security auditors, repository managers, or
-department-specific access control.
+Use custom roles when Docker's default roles don't fit your needs.
 
 ## Prerequisites
 
@@ -124,6 +123,16 @@ assignment counts.
 {{< tab name="Bulk users" >}}
 
 
+{{< /tab >}}
+{{< tab name="Teams" >}}
+
+1. Sign in to [Docker Home](https://app.docker.com).
+1. Select **Teams**.
+1. Locate the team, then select the **Actions menu**.
+1. Select **Change role**.
+1. In the pop-up window, select a role from the drop-down menu, then
+select **Save**.
+
 {{< /tab >}}
 {{< /tabs >}}
 

From 8b63e94180a20e55785dfeef402ef0f73d63e8bd Mon Sep 17 00:00:00 2001
From: sarahsanders-docker <sarah.sanders@docker.com>
Date: Thu, 23 Oct 2025 13:37:44 -0400
Subject: [PATCH 3/3] fix build issues

---
 content/manuals/docker-hub/release-notes.md                   | 4 ++--
 .../enterprise/security/roles-and-permissions/custom-roles.md | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/content/manuals/docker-hub/release-notes.md b/content/manuals/docker-hub/release-notes.md
index 898c43ddb4fa..1e2f34f24560 100644
--- a/content/manuals/docker-hub/release-notes.md
+++ b/content/manuals/docker-hub/release-notes.md
@@ -47,13 +47,13 @@ known issues for each Docker Hub release.
 
 ## 2023-08-28
 
-- Organizations with SSO enabled can assign members to roles, organizations, and teams with [SCIM role mapping](scim.md#set-up-role-mapping). 
+- Organizations with SSO enabled can assign members to roles, organizations, and teams with [SCIM role mapping](scim.md#set-up-role-mapping).
 
 ## 2023-07-26
 
 ### New
 
-- Organizations can assign the [editor role](/manuals/enterprise/security/roles-and-permissions/roles-and-permissions.md) to members to grant additional permissions without full administrative access.
+- Organizations can assign the [editor role](/manuals/enterprise/security/roles-and-permissions/_index.md) to members to grant additional permissions without full administrative access.
 
 ## 2023-05-09
 
diff --git a/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md b/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md
index f41053858f62..ecd1fdac1781 100644
--- a/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md
+++ b/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md
@@ -42,7 +42,7 @@ the [custom roles permissions reference](#custom-roles-permissions-reference).
 of selected permissions.
 1. Select **Create**.
 
-With a custom role created, you can now [assign custom roles to users](#assign-custom-roles-to-users).
+With a custom role created, you can now [assign custom roles to users](#assign-custom-roles).
 
 ## Edit a custom role