Custom org roles can include repository permissions - [Public Beta] (#51927)

Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com>
Co-authored-by: Hirsch Singhal <1666363+hpsin@users.noreply.github.com>
Co-authored-by: Siara <108543037+SiaraMist@users.noreply.github.com>

content/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles.md

@@ -1,6 +1,6 @@
 ---
 title: About custom organization roles
-intro: "You can control access to your organization's settings with custom organization roles."
+intro: "You can control access to your {% ifversion org-custom-role-with-repo-permissions %}organization and repository's{% else %} organization's{% endif %} settings with custom organization roles."
 versions:
   feature: 'custom-org-roles'
 topics:
@@ -10,20 +10,28 @@ permissions: 'Organization owners and users with the "Manage custom organization
 product: 'Organizations on {% data variables.product.prodname_ghe_cloud %}{% ifversion ghes %} and {% data variables.product.prodname_ghe_server %}{% endif %}'
 ---
 
-## About custom organization roles
-
 {% data reusables.organizations.custom-org-roles-intro %}
 
-You can create and assign custom organization roles in your organization's settings. You can also manage custom roles using the REST API. For more information, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles)."
+You can create and assign custom organization roles in your organization's settings. You can also manage custom roles using the REST API. See "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles)."
 
-Organization permissions do not grant read, write, or administrator access to any repositories. Some permissions may implicitly grant visibility of repository metadata, as marked in the table below.
+{% ifversion org-custom-role-with-repo-permissions %}
 
-To granularly control access to your organization's repositories, you can create a custom repository role. For more information, see "[AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles)."
+You can also create a custom organization role that includes permissions for repositories. Repository permissions grant access to all current and future repositories in the organization. There are several ways to combine permissions for repositories and organizations. You can create a custom organization role with:
 
-## Permissions for custom roles
+You can create a role that includes permissions for organization settings, a base role for repository access, or both. If you add a base role for repository access, you can also include additional repository permissions. You can't create a role with repository permissions unless it includes a base repository role. Without repository permissions or a base repository role, the organization role doesn't grant access to any repositories.
+
+>[!NOTE] Adding repository permissions to a custom organization role is currently in public beta and subject to change.
+
+{% endif %}
+
+To grant access to **specific** repositories in your organization, you can create a custom repository role. See "[AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles)."
+
+## Permissions for organization access
 
 When you include a permission in a custom organization role, any users with that role will have access to the corresponding settings via both the web browser and API. In the organization's settings in the browser, users will see only the pages for settings they can access.
 
+Organization permissions do not grant read, write, or administrator access to any repositories. Some permissions may implicitly grant visibility of repository metadata, as marked in the table below.
+
 {% rowheaders %}
 
 | Permission | Description | More information |
@@ -56,3 +64,31 @@ Manage organization OAuth application policies | Access to the "OAuth applicatio
 |  {% endif %} |
 
 {% endrowheaders %}
+
+{% ifversion org-custom-role-with-repo-permissions %}
+
+## Base roles for repository access
+
+The base repository role determines the initial set of permissions included in the custom role. Repository access is granted across **all** current and future repositories in the organization.
+
+The base repository roles are:
+
+* **Read**: Grants read access to all repositories in the organization.
+* **Write**: Grants write access to all repositories in the organization.
+* **Triage**: Grants triage access to all repositories in the organization.
+* **Maintain**: Grants maintenance access to all repositories in the organization.
+* **Admin**: Grants admin access to all repositories in the organization.
+
+## Additional permissions for repository access
+
+After choosing a base repository role, you can select additional permissions for your custom organization role.
+
+You can only choose an additional permission if it's not already included in the base repository role. For example, if the base role offers **Write** access to a repository, then the "Close a pull request" permission will already be included in the base role.
+
+{% data reusables.organizations.additional-permissions %}
+
+## Precedence for different levels of access
+
+{% data reusables.organizations.precedence-for-different-levels %}
+
+{% endif %}

content/organizations/managing-peoples-access-to-your-organization-with-roles/index.md

@@ -14,9 +14,9 @@ topics:
   - Teams
 children:
   - /roles-in-an-organization
+  - /using-organization-roles
   - /about-custom-organization-roles
   - /managing-custom-organization-roles
-  - /using-organization-roles
   - /maintaining-ownership-continuity-for-your-organization
   - /adding-a-billing-manager-to-your-organization
   - /removing-a-billing-manager-from-your-organization

content/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles.md

@@ -2,7 +2,9 @@
 title: Using organization roles
 intro: "Learn how to{% ifversion org-pre-defined-roles %} view organization role permissions and{% endif %} manage organization role assignments."
 versions:
-  feature: 'custom-org-roles'
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.14'
 topics:
   - Organizations
   - Access management
@@ -10,7 +12,7 @@ topics:
   - Permissions
 permissions: 'Organization owners{% ifversion ghec %} and users with the "Manage custom organization roles" permission{% endif %}'
 product: 'Organizations on {% data variables.product.prodname_free_team %}, {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, {% data variables.product.prodname_ghe_cloud %}, and {% data variables.product.prodname_ghe_server %}'
-shortTitle: Using organization roles
+shortTitle: Use organization roles
 ---
 
 ## About organization roles

content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles.md

@@ -30,7 +30,9 @@ You can also use the REST API to create and manage custom repository roles. For
 {% endif %}
 
 {% ifversion custom-org-roles %}
-Custom repository roles manage access to repositories in your organization. To granularly control access to your organization's administration settings, you can use custom organization roles. For more information, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles)."
+Custom repository roles manage access to specific repositories in your organization. To {% ifversion org-custom-role-with-repo-permissions %}grant access to all repositories, and to {% endif %}control access to your organization's administration settings, you can use custom organization roles. See "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles)."
+
+Custom organization roles differ from repository roles by granting permissions across **all** current and future repositories in the organization. Custom repository roles, however, allow you to grant permissions to **specific** repositories within the organization.
 {% endif %}
 
 ## About the inherited role
@@ -62,79 +64,8 @@ After choosing an inherited role, you can select additional permissions for your
 
 You can only choose an additional permission if it's not already included in the inherited role. For example, if the inherited role offers **Write** access to a repository, then the "Close a pull request" permission will already be included in the inherited role.
 
-{% ifversion discussions %}
-
-### Discussions
-
-* Create a discussion category
-* Edit a discussion category
-* Delete a discussion category
-* Mark or unmark discussion answers
-* Hide or unhide discussion comments
-* Convert issues to discussions
-
-For more information, see "[AUTOTITLE](/discussions)."
-{% endif %}
-
-### Issue and Pull Requests
-
-* Assign or remove a user
-* Add or remove a label
-
-### Issue
-
-* Close an issue
-* Reopen a closed issue
-* Delete an issue
-* Mark an issue as a duplicate
-
-### Pull Request
-
-* Close a pull request
-* Reopen a closed pull request
-* Request a pull request review
-
-### Repository
-
-* Set milestones
-* Manage wiki settings
-* Manage project settings
-* Manage pull request merging settings
-* Manage {% data variables.product.prodname_pages %} settings (see "[AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)")
-* Manage webhooks
-* Manage deploy keys
-* Edit repository metadata
-{%- ifversion ghec %}
-* Set interaction limits
-{%- endif %}
-* Set the social preview
-* Push commits to protected branches
-  * Base role must be `write`
-  * Branch protection rules will still apply
-* Create protected tags
-* Delete protected tags
-* Bypass branch protections
-{%- ifversion edit-repository-rules %}
-* Edit repository rules
-{%- endif %}
-
-### Security
-
-* View {% data variables.product.prodname_code_scanning %} results
-* Dismiss or reopen {% data variables.product.prodname_code_scanning %} results
-* Delete {% data variables.product.prodname_code_scanning %} results
-* View {% data variables.product.prodname_dependabot_alerts %}
-* Dismiss or reopen {% data variables.product.prodname_dependabot_alerts %}
-* View {% data variables.product.prodname_secret_scanning %} results
-* Dismiss or reopen {% data variables.product.prodname_secret_scanning %} results
+{% data reusables.organizations.additional-permissions %}
 
 ## Precedence for different levels of access
 
-If a person is given different levels of access through different avenues, such as team membership and the base permissions for an organization, the highest access overrides the others. For example, if an organization owner gives an organization member a custom role that uses the "Read" inherited role, and then an organization owner sets the organization's base permission to "Write", then this custom role will have write access, along with any additional permissions included in the custom role.
-
-{% data reusables.organizations.mixed-roles-warning %}
-
-To resolve conflicting access, you can adjust your organization's base permissions or the team's access, or edit the custom role. For more information, see:
-* "[AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/setting-base-permissions-for-an-organization)"
-* "[AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-team-access-to-an-organization-repository)"
-* "[Editing a repository role](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization#editing-a-repository-role)"
+{% data reusables.organizations.precedence-for-different-levels %}

content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository.md

@@ -33,14 +33,14 @@ If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}
 
 For more information about repository roles, see "[AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-personal-account-repository)" and "[AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization)."
 
-![Screenshot of the "Manage access" page for a repository.](/assets/images/help/repository/manage-access-overview.png)
-
 ## Filtering the list of teams and people
 
 {% data reusables.repositories.navigate-to-repo %}
 {% data reusables.repositories.sidebar-settings %}
 {% data reusables.repositories.click-collaborators-teams %}
-1. Under "Manage access", in the search field, start typing the name of the team or person you'd like to find. Optionally, use the dropdown menus to filter your search.
+1. Under "Manage access", in the search field, start typing the name of the team or person you'd like to find. Optionally, use the dropdown menus to filter your search. {% ifversion org-custom-role-with-repo-permissions %}
+
+   You can also toggle between the **Direct access** and **Organization access** tabs to view who has direct access to the repository and who can access the repository via a team or organization role.{% endif %}
 
 ## Changing permissions for a team or person
 

data/features/org-custom-role-with-repo-permissions.yml

@@ -0,0 +1,5 @@
+# Issue #11307
+# Documentation for custom organization roles can include repository permissions
+versions:
+  ghec: '*'
+  ghes: '>=3.15'

data/reusables/organizations/additional-permissions.md

@@ -0,0 +1,65 @@
+{% ifversion discussions %}
+
+### Discussions
+
+* Create a discussion category
+* Edit a discussion category
+* Delete a discussion category
+* Mark or unmark discussion answers
+* Hide or unhide discussion comments
+* Convert issues to discussions
+
+For more information, see "[AUTOTITLE](/discussions)."
+{% endif %}
+
+### Issue and Pull Requests
+
+* Assign or remove a user
+* Add or remove a label
+
+### Issue
+
+* Close an issue
+* Reopen a closed issue
+* Delete an issue
+* Mark an issue as a duplicate
+
+### Pull Request
+
+* Close a pull request
+* Reopen a closed pull request
+* Request a pull request review
+
+### Repository
+
+* Set milestones
+* Manage wiki settings
+* Manage project settings
+* Manage pull request merging settings
+* Manage {% data variables.product.prodname_pages %} settings (see "[AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)")
+* Manage webhooks
+* Manage deploy keys
+* Edit repository metadata
+{%- ifversion ghec %}
+* Set interaction limits
+{%- endif %}
+* Set the social preview
+* Push commits to protected branches
+  * Base role must be `write`
+  * Branch protection rules will still apply
+* Create protected tags
+* Delete protected tags
+* Bypass branch protections
+{%- ifversion edit-repository-rules %}
+* Edit repository rules
+{%- endif %}
+
+### Security
+
+* View {% data variables.product.prodname_code_scanning %} results
+* Dismiss or reopen {% data variables.product.prodname_code_scanning %} results
+* Delete {% data variables.product.prodname_code_scanning %} results
+* View {% data variables.product.prodname_dependabot_alerts %}
+* Dismiss or reopen {% data variables.product.prodname_dependabot_alerts %}
+* View {% data variables.product.prodname_secret_scanning %} results
+* Dismiss or reopen {% data variables.product.prodname_secret_scanning %} results

data/reusables/organizations/custom-org-roles-create-new-step.md

@@ -1,4 +1,14 @@
 1. Click **Create a role**.
-1. Type a name and description for the custom role.
-1. Under "Add permissions", click the text field, then select the permissions you want to add to the custom role. For more information about the available permissions, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles#additional-permissions-for-custom-roles)."
+1. Type a name and description for the custom role.{% ifversion org-custom-role-with-repo-permissions %}
+1. Under "Add permissions", click the **Organization** or **Repository** tab to select the type of permissions you want to add to the custom role.
+
+   * To add permissions for the organization, click the **Organization** tab, then select the dropdown menu and click the permissions you want your custom role to include.
+   * To choose a base repository role to inherit, click the **Repository** tab, then select the dropdown menu and click the base role you want to include in the custom role. For more information about the available base repository roles, see "[Base roles for repository access](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles#base-roles-for-repository-access)."
+
+      Once you've selected a base repository role, you can add additional permissions to the custom role. For more information about the available permissions, see "[Additional permissions for repository access](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles#additional-permissions-for-repository-access)."
+
+      >[!NOTE] Adding a repository role and permissions to a custom organization role is currently in public beta and subject to change.
+
+{% else %}
+1. Under "Add permissions", click the text field, then select the permissions you want to add to the custom role. For more information about the available permissions, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles#additional-permissions-for-custom-roles)."{% endif %}
 1. Click **Create role**.

data/reusables/organizations/custom-org-roles-intro.md

@@ -1 +1 @@
-You can have more granular control over the access you grant to your organization's settings by creating custom organization roles. Organization roles are a way to grant an organization member the ability to administer certain subsets of settings without granting full administrative control of the organization and its repositories. For example, you could create a role that contains the "View organization audit log" permission.
+You can have more granular control over the access you grant to your {% ifversion org-custom-role-with-repo-permissions %}organization and repository's{% else %} organization's{% endif %} settings by creating custom organization roles. Organization roles are a way to grant an organization member the ability to administer certain subsets of settings without granting full administrative control of the organization and its repositories. For example, you could create a role that contains the "View organization audit log" permission.

data/reusables/organizations/precedence-for-different-levels.md

@@ -0,0 +1,9 @@
+Roles and permissions are additive. If a person is given different levels of access through different avenues, such as team membership and the base permissions for an organization, the user has the sum of all access grants. For example, if an organization owner gives an organization member a custom role that uses the "Read" inherited role, and then an organization owner sets the organization's base permission to "Write", then members with the custom role will have write access, along with any additional permissions included in the custom role.
+
+{% data reusables.organizations.mixed-roles-warning %}
+
+To resolve conflicting access, you can adjust your organization's base permissions or the team's access, or edit the custom role. For more information, see:
+* "[AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/setting-base-permissions-for-an-organization)"
+* "[AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-team-access-to-an-organization-repository)"
+* "[Editing a repository role](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization#editing-a-repository-role)"{% ifversion custom-org-roles %}
+* "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles#editing-a-custom-role)"{% endif %}