Repo sync

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/roles-in-an-enterprise
+  - /admin/managing-accounts-and-repositories/managing-users-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

content/admin/index.md

@@ -73,7 +73,7 @@ featuredLinks:
   startHere:
     - '{% ifversion ghec %}/admin/managing-iam/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud{% endif %}'
     - /admin/managing-iam/understanding-iam-for-enterprises/about-identity-and-access-management
-    - '{% ifversion ghec %}/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise{% endif %}'
+    - '{% ifversion ghec %}/admin/managing-accounts-and-repositories/managing-users-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 %}'

content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/custom-organization-roles.md

@@ -0,0 +1,25 @@
+---
+title: Creating custom organization roles in an enterprise
+intro: Create roles with fine-grained permissions for a consistent experience across your organizations.
+versions:
+  feature: ent-owner-custom-org-roles
+type: how_to
+topics:
+  - Enterprise
+  - Organizations
+shortTitle: Custom organization roles
+---
+
+To define consistent sets of permissions for settings and repositories, you can create custom organization roles for use in all of the enterprise's organizations. This allows centralized management of common roles such as "Developer" or "SRE team."
+
+Custom organization roles created at the enterprise level use the same organization and repository permissions and base roles as roles created at the organization level. There is no difference in how these roles function or what they can allow. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles).
+
+Enterprise owners can create and edit custom organization roles, but cannot assign them. Organization owners can assign custom roles in an organization.
+
+>[!NOTE] An enterprise can create up to 20 custom organization roles. This limit applies to the enterprise: each organization can also create up to 20 custom organization roles.
+
+{% data reusables.enterprise-accounts.access-enterprise %}
+{% data reusables.enterprise-accounts.people-tab %}
+1. In the left sidebar, select **Organization roles**.
+1. Click **Create custom role**.
+1. Enter the details, then click **Create role**.

content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/index.md

@@ -25,6 +25,7 @@ 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

content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise.md → content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/abilities-of-roles.md

@@ -1,18 +1,22 @@
 ---
-title: Roles in an enterprise
-intro: "Learn which roles you can assign to control access to your enterprise's settings and data."
+title: Abilities of roles in an enterprise
+intro: Learn which roles you can assign to control access to your enterprise's settings and data.
+shortTitle: Capabilities of roles
 redirect_from:
   - /github/setting-up-and-managing-your-enterprise/managing-users-in-your-enterprise/roles-in-an-enterprise
   - /github/setting-up-and-managing-your-enterprise-account/roles-for-an-enterprise-account
   - /articles/permission-levels-for-a-business-account
   - /articles/roles-for-an-enterprise-account
   - /github/setting-up-and-managing-your-enterprise/roles-in-an-enterprise
   - /admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise
+  - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise
 versions:
   ghec: '*'
   ghes: '*'
 topics:
   - Enterprise
+allowTitleToDifferFromFilename: true
+contentType: reference
 ---
 
 ## About roles in an enterprise
@@ -35,33 +39,6 @@ All users that are part of your enterprise have one of the following roles.
 
 People with collaborator access to repositories are listed in your enterprise's "People" tab, but are not enterprise members and do not have access to the enterprise. See {% ifversion ghec %}[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators-or-repository-collaborators).{% else %}[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators).{% endif %}
 
-## How do I assign roles?
-
-{% ifversion ghec %}
-If you use an **enterprise with personal accounts**:
-
-* People become enterprise members when they are added as a member or owner of an organization. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization).
-* You can invite someone to become an enterprise owner or billing manager. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise).
-
-If you use an **{% data variables.enterprise.prodname_emu_enterprise %}**:
-
-* You must provision all users through your identity provider (IdP).
-* You select each user's enterprise role using your IdP. The role cannot be changed on {% data variables.product.prodname_dotcom %}.
-* To assign the guest collaborator role, you may need to update your IdP.
-
-For more information about the different types of enterprise accounts, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud#about-types-of-enterprises).
-
-{% elsif ghes %}
-
-When a user has joined your {% data variables.product.prodname_ghe_server %} instance, you can:
-
-* Add the user to an organization. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/adding-people-to-your-organization).
-* Invite the user to become an enterprise owner. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise).
-
-If you provision users with SCIM, you assign each user's enterprise role on your identity provider (IdP). The role cannot be changed on {% data variables.product.prodname_dotcom %}.
-
-{% endif %}
-
 ## Enterprise owners
 
 Enterprise owners have complete control over the enterprise and can take every action, including:
@@ -70,8 +47,8 @@ Enterprise owners have complete control over the enterprise and can take every a
 * {% ifversion ghec %}Adding and removing {% elsif ghes %}Managing{% endif %} organizations{% ifversion remove-enterprise-members %}
 * Removing enterprise members from all organizations{% endif %}
 * Managing enterprise settings
-* Enforcing policy across organizations
-{% ifversion ghec %}- Managing billing settings{% endif %}
+* Enforcing policy across organizations{% ifversion ghec %}
+* Managing billing settings{% endif %}
 
 For security, we recommend making **only a few people** enterprise owners.
 
@@ -128,17 +105,6 @@ You can add unaffiliated users from your identity provider (for {% data variable
 
 {% endif %}
 
-## Custom organization roles
-
-With {% data variables.product.prodname_ghe_cloud %} and starting from {% data variables.product.prodname_ghe_server %} 3.19, enterprise owners can create custom organization roles for use in all of the enterprise's organizations. This allows centralized management of common roles such as "Developer" or "SRE team". Only enterprise owners can create or edit these roles, and any organization owner or user with the "Manage organization roles" permission can assign them in an organization.
-
-When creating an organization role, enterprise owners can use the same organization and repository permissions and base roles as organization owners—there is no difference in how these roles function or what they can allow.
-
-{% data reusables.enterprise-accounts.access-enterprise %}
-{% data reusables.enterprise-accounts.people-tab %}
-1. Select the "Organization Roles" section in the left-hand menu.
-1. Create a new role using the "Create custom role" button, or edit an existing role using the ellipsis menu (...).
-
-See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles) for more information about creating and assigning custom organization roles.
+## Next steps
 
-At this time, up to 20 custom organization roles can be created by the enterprise. This limit is only for the enterprise - each organization can also create up to 20 custom organization roles.
+When you have decided which roles your users require, assign the roles to them. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/assign-roles).

content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/assign-roles.md

@@ -0,0 +1,41 @@
+---
+title: Assigning roles to users in an enterprise
+intro: Assign roles to govern what people can do in your enterprise.
+versions:
+  ghec: '*'
+  ghes: '*'
+type: how_to
+shortTitle: Assign roles
+---
+
+Users in an enterprise have roles for the enterprise and for organizations where they have access. For more information, see [AUTOTITLE](/admin/overview/about-roles).
+
+## Assigning enterprise roles
+
+{% ifversion ghec %}
+If you use an **enterprise with personal accounts**:
+
+* People become enterprise members when they are added as a member or owner of an organization. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization).
+* You can invite someone to become an enterprise owner or billing manager. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise).
+* You can add people as unaffiliated users without adding them to the enterprise. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/invite-users-directly).
+
+If you use an **{% data variables.enterprise.prodname_emu_enterprise %}**:
+
+* You must provision all users through your identity provider (IdP).
+* You select each user's enterprise role using your IdP. The role cannot be changed on {% data variables.product.prodname_dotcom %}.
+* To assign the guest collaborator role, you may need to update your IdP.
+
+{% elsif ghes %}
+
+When a user has joined your {% data variables.product.prodname_ghe_server %} instance, you can:
+
+* Add the user to an organization. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/adding-people-to-your-organization).
+* Invite the user to become an enterprise owner. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise).
+
+If you provision users with SCIM, you assign each user's enterprise role on your identity provider (IdP). The role cannot be changed on {% data variables.product.prodname_dotcom %}.
+
+{% endif %}
+
+## Assigning organization roles
+
+Organization administrators can assign roles to users and teams in their organization. See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles#assigning-an-organization-role).

content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/index.md

@@ -17,10 +17,11 @@ versions:
 topics:
   - Enterprise
 children:
-  - /roles-in-an-enterprise
+  - /abilities-of-roles
   - /best-practices-for-user-security
   - /create-enterprise-teams
   - /invite-users-directly
+  - /assign-roles
   - /inviting-people-to-manage-your-enterprise
   - /managing-invitations-to-organizations-within-your-enterprise
   - /managing-organization-members-in-your-enterprise
@@ -42,3 +43,4 @@ children:
   - /enabling-guest-collaborators
 shortTitle: Manage users
 ---
+

content/admin/overview/about-roles.md

@@ -0,0 +1,46 @@
+---
+title: About 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: '*'
+shortTitle: About roles
+type: overview
+topics:
+  - Enterprise
+  - Fundamentals
+---
+
+## 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.
+
+* 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.
+
+## Predefined and custom roles for organizations
+
+Organization roles can be **predefined** or **custom**.
+
+* 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.
+
+We recommend using custom roles wherever possible. However, if a predefined role meets your needs, this is the quickest way to grant permissions.
+
+## Who can assign roles?
+
+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 %}
+
+Organization administrators can grant organization roles and create custom organization roles, but can't affect roles at the enterprise level.
+
+## Next steps
+
+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 %}.
+
+* [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)
+
+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.

content/admin/overview/index.md

@@ -20,6 +20,7 @@ children:
   - /establishing-a-governance-framework-for-your-enterprise
   - /accessing-compliance-reports-for-your-enterprise
   - /about-teams
+  - /about-roles
 ---
 
 For more information, or to purchase {% data variables.product.prodname_enterprise %}, see [{% data variables.product.prodname_enterprise %}](https://github.com/enterprise).