github · docs-bot · Oct 23, 2025 · Oct 23, 2025 · Oct 23, 2025 · Oct 23, 2025
diff --git a/content/admin/concepts/enterprise-fundamentals/roles-in-an-enterprise.md b/content/admin/concepts/enterprise-fundamentals/roles-in-an-enterprise.md
@@ -2,8 +2,7 @@
 title: Roles in an enterprise
 intro: 'Learn how roles allow you to control people''s access to your enterprise''s settings and resources.'
 versions:
-  ghec: '*'
-  ghes: '*'
+  feature: enterprise-custom-roles
 shortTitle: Roles
 topics:
   - Enterprise
@@ -15,34 +14,30 @@ contentType: concepts
 
 ## What are roles?
 
-A role is a **set of permissions** that you can assign to individuals or teams. A permission is the ability to perform a specific action, such as changing billing settings.
-
-A user in an enterprise has a role for both the enterprise account itself and for each individual organization in the enterprise.
+Roles allow you to delegate administrative duties and manage access securely at every level of your enterprise.
 
-* The enterprise-level role defines the user's access to enterprise settings, and to internal repositories across the enterprise.
-* Organization-level roles define the user's access to organization settings and repositories in that organization.
+A role is a **set of permissions** that you can assign to individuals or teams. A permission is the ability to perform a specific action, such as changing billing settings.
 
-## Predefined and custom roles for organizations
+A user in an enterprise has roles for both the enterprise account and organizations where they have access.
 
-Organization roles can be **predefined** or **custom**.
+* The enterprise-level roles define the user's access to enterprise settings.
+* Organization-level roles define the user's access to organization settings and repositories in an organization.
 
-* Predefined roles, such as organization owner or billing manager, grant blanket permissions to users or teams. They may contain more permissions than someone needs to do their job.
-* Custom roles include fine-grained permissions for organization settings and repository access. They allow you to follow the principle of least privilege by giving teams just the access they need to do their jobs. For example, you could allow a team to view your audit logs without allowing them to change policies.
+## Predefined and custom roles
 
-We recommend using custom roles wherever possible. However, if a predefined role meets your needs, this is the quickest way to grant permissions.
+Organization and enterprise roles can be **predefined** or **custom**. Enterprise custom roles are in {% data variables.release-phases.public_preview %}.
 
-## Who can assign roles?
+* Predefined roles, such as enterprise owner, organization owner, or billing manager, are available for all accounts. They grant a predefined set of permissions to users or teams and may contain more permissions than someone needs to do their job.
+* Custom roles include your choice of fine-grained permissions. They can include access to account settings and (for organization custom roles) repository access, allowing you to provide teams with just the access they need to do their jobs. For example, you could allow a team to view your enterprise's audit logs without allowing them to change any settings.
 
-Enterprise roles are assigned when a user is invited to the enterprise (personal accounts) or provisioned from an identity provider.{% ifversion ent-owner-custom-org-roles %} Enterprise owners can also create custom organization roles to be used across organizations, but these roles can only be assigned by organization administrators.{% endif %}
+To follow the principle of least privilege access, we recommend using custom roles if they allow for the permissions you require. However, not all capabilities of predefined roles can currently be replicated in custom roles.
 
-Organization administrators can grant organization roles and create custom organization roles, but can't affect roles at the enterprise level.
+## Who manages roles?
 
-## Further reading
+Enterprise owners can create custom enterprise roles and assign enterprise roles to users and teams. They can also create custom organization roles to be used across organizations, but these roles can only be assigned by organization owners.
 
-Review the predefined roles and fine-grained permissions available with custom organization roles, and plan out what roles will be required for your teams to do their jobs on {% data variables.product.github %}.
+Organization owners can grant organization roles and create custom organization roles, but cannot edit roles or change role assignments that are defined at the enterprise level.
 
-* [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/abilities-of-roles)
-* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#about-organization-roles)
-* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles#permissions-for-organization-access)
+## Next steps
 
-To ensure continued access, we recommend giving the enterprise owner role to at least two people, and the organization owner role to at least two people per organization. However, you should grant most teams only the minimum level of access they require.
+Now that you understand roles, plan which roles will be required for your teams to do their jobs on {% data variables.product.github %}. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/identify-role-requirements).
diff --git a/content/admin/concepts/enterprise-fundamentals/teams-in-an-enterprise.md b/content/admin/concepts/enterprise-fundamentals/teams-in-an-enterprise.md
@@ -2,7 +2,7 @@
 title: Teams in an enterprise
 intro: 'Learn how teams simplify administration of user access, licensing, and communication.'
 versions:
-  ghec: '*'
+  feature: enterprise-teams
 shortTitle: Teams
 topics:
   - Enterprise
@@ -16,10 +16,11 @@ contentType: concepts
 
 Teams are **groups of users** in an enterprise or organization. By creating teams, you can manage users at scale and simplify access, licensing, and communication. For example, you could create an auditor team for users who need access to audit logs, or a {% data variables.product.prodname_copilot_short %} team for users who receive {% data variables.product.prodname_copilot_short %} licenses.
 
-Administrators can create teams in an enterprise account or in organizations within an enterprise.
+**Enterprise teams** are managed at the enterprise level and can include users from across the enterprise and its organizations. With enterprise teams, you can centralize administration and manage organization access, roles, and licensing at scale.
 
-* **Enterprise teams** are managed by enterprise owners and can include users from across the enterprise and its organizations. Currently, enterprise teams are used to manage {% data variables.product.prodname_copilot %} licenses for directly assigned users. {% data variables.product.company_short %} plans to expand the capabilities in the near future to include organization and role assignment.
-* **Organization teams** are managed by organization administrators and can only include members of a single organization. Organization administrators can grant teams access to organization repositories, and organization members can mention teams in issues and discussions or add them as reviewers on pull requests.
+**Organization teams** are managed at the organization level and can only include members of a single organization. There are certain features of organization teams that are not currently supported for enterprise teams, such as CODEOWNER status.
+
+>[!NOTE] Enterprise teams are in public preview and subject to change.
 
 ## Can I manage teams from an identity provider?
 
@@ -41,22 +42,29 @@ Team sync with personal accounts is only available with organization teams, and
 
 ## What kind of team should I use?
 
-To simplify administration at scale, {% data variables.product.company_short %} recommends using enterprise teams wherever possible. However, you may need to create organization teams if the functionality you need is not covered by enterprise teams. {% data variables.product.company_short %} plans to address some of these limitations in the near future.
+To simplify administration at scale, {% data variables.product.company_short %} recommends using enterprise teams for any use cases that apply to the enterprise account or to multiple organizations. Organization teams are useful when the need for the team is scoped to a single organization and the team can be managed by an organization administrator.
+
+You may need to create organization teams if the functionality you need is not covered by enterprise teams. {% data variables.product.company_short %} plans to address some limitations in the near future.
 
-Unlike organization teams, enterprise teams currently do **not** support:
+{% data reusables.enterprise.enterprise-teams-can %}
+
+However, unlike organization teams, enterprise teams currently do **not** support:
 
-* Repository or organization access
 * `@-mentions` of the team name in organizations
+* Review requests of the team in pull requests
+* Adding the team to a project board
 * Team sync if you use {% data variables.product.prodname_ghe_cloud %} with personal accounts
 * CODEOWNER status
 * Secret teams
 * Nested teams
 * Team maintainers
 
-In addition, enterprise teams are currently limited to 50 teams for a single enterprise and 500 users to each team.
+{% data reusables.enterprise.enterprise-teams-limits %}
 
 For more information about the capabilities of organization teams, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams).
 
-## Further reading
+## Next steps
+
+If your needs are covered by enterprise teams, create a team. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/create-enterprise-teams).
 
-* [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams)
+If you need to create an organization team, an organization owner must do this from the organization settings. See [AUTOTITLE](/organizations/organizing-members-into-teams/creating-a-team).
diff --git a/content/admin/guides.md b/content/admin/guides.md
@@ -119,7 +119,7 @@ includeGuides:
   - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-projects-using-jira
   - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise
   - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise
-  - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/abilities-of-roles
+  - /admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/abilities-of-roles
   - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise
   - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise
   - /admin/user-management/managing-repositories-in-your-enterprise/migrating-to-internal-repositories

diff --git a/content/admin/index.md b/content/admin/index.md
@@ -73,7 +73,7 @@ featuredLinks:
   startHere:
     - '/admin/concepts/identity-and-access-management\identity-and-access-management-fundamentals'
     - '{% ifversion ghec %}/admin/concepts/identity-and-access-management/enterprise-types-for-github-enterprise-cloud{% endif %}'
-    - '{% ifversion ghec %}/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/abilities-of-roles{% endif %}'
+    - '{% ifversion ghec %}/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/abilities-of-roles{% endif %}'
     - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise
     - '{% ifversion ghes %}/admin/getting-started-with-enterprise/about-upgrades-to-new-releases{% endif %}'
     - '{% ifversion ghes %}/billing/how-tos/set-up-payment/manage-enterprise-invoice{% endif %}'

diff --git a/content/admin/managing-accounts-and-repositories/index.md b/content/admin/managing-accounts-and-repositories/index.md
@@ -18,4 +18,5 @@ children:
   - /managing-users-in-your-enterprise
   - /managing-organizations-in-your-enterprise
   - /managing-repositories-in-your-enterprise
+  - /managing-roles-in-your-enterprise
 ---
diff --git a/...sitories/managing-organizations-in-your-enterprise/custom-organization-roles.md b/...sitories/managing-organizations-in-your-enterprise/custom-organization-roles.md
diff --git a/...ng-accounts-and-repositories/managing-organizations-in-your-enterprise/index.md b/...ng-accounts-and-repositories/managing-organizations-in-your-enterprise/index.md
@@ -13,7 +13,7 @@ redirect_from:
   - /github/setting-up-and-managing-your-enterprise-account/managing-unowned-organizations-in-your-enterprise-account
   - /github/setting-up-and-managing-your-enterprise/managing-unowned-organizations-in-your-enterprise-account
   - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/continuous-integration-using-jenkins
-intro: 'You can use organizations to group users within your company, such as divisions or groups working on similar projects, and manage access to repositories.'
+intro: You can use organizations to group users within your company, such as divisions or groups working on similar projects, and manage access to repositories.
 versions:
   ghec: '*'
   ghes: '*'
@@ -25,11 +25,11 @@ children:
   - /configuring-visibility-for-organization-membership
   - /preventing-users-from-creating-organizations
   - /requiring-two-factor-authentication-for-an-organization
-  - /custom-organization-roles
   - /managing-your-role-in-an-organization-owned-by-your-enterprise
   - /managing-requests-for-copilot-business-from-organizations-in-your-enterprise
   - /removing-organizations-from-your-enterprise
   - /restoring-a-deleted-organization
   - /managing-projects-using-jira
 shortTitle: Manage organizations
 ---
+