diff options
Diffstat (limited to 'doc/user/custom_roles.md')
| -rw-r--r-- | doc/user/custom_roles.md | 93 |
1 files changed, 79 insertions, 14 deletions
diff --git a/doc/user/custom_roles.md b/doc/user/custom_roles.md index bbb48724078..1f3628efa39 100644 --- a/doc/user/custom_roles.md +++ b/doc/user/custom_roles.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom roles **(ULTIMATE ALL)** @@ -15,7 +15,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Ability to create and remove a custom role with the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393235) in GitLab 16.4. > - Ability to manage group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17364) in GitLab 16.5. > - Ability to manage project access tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421778) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `manage_project_access_tokens`. -> - Ability to archive projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425957) in GitLab 16.6 in [with a flag](../administration/feature_flags.md) named `archive_project`. Disabled by default. +> - Ability to archive projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425957) in GitLab 16.7. +> - Ability to use the UI to add a user to your group with a custom role, change a user's custom role, or remove a custom role from a group member [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393239) in GitLab 16.7. Custom roles allow group Owners or instance administrators to create roles specific to the needs of their organization. @@ -50,7 +51,7 @@ with the ability to: ### GitLab SaaS -Prerequisite: +Prerequisites: - You must have the Owner role in the group you are creating the custom role in. @@ -59,25 +60,40 @@ Prerequisite: 1. Select **Add new role**. 1. In **Base role to use as template**, select an existing non-custom role. 1. In **Role name**, enter the custom role's title. +1. Optional. In **Description**, enter a description for the custom role. 1. Select the **Permissions** for the new custom role. 1. Select **Create new role**. +In **Settings > Roles and Permissions**, the list of all custom roles displays the: + +- Custom role name. +- Role ID. +- Base role that the custom role uses as a template. +- Permissions. + ### Self Managed GitLab Instances -Prerequisite: +Prerequisites: - You must be an administrator for the self-managed instance you are creating the custom role in. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Roles and Permissions**. 1. From the top dropdown list, select the group you want to create a custom role in. 1. Select **Add new role**. 1. In **Base role to use as template**, select an existing non-custom role. 1. In **Role name**, enter the custom role's title. +1. Optional. In **Description**, enter a description for the custom role. 1. Select the **Permissions** for the new custom role. 1. Select **Create new role**. +In **Settings > Roles and Permissions**, the list of all custom roles displays the: + +- Custom role name. +- Role ID. +- Base role that the custom role uses as a template. +- Permissions. + To create a custom role, you can also [use the API](../api/member_roles.md#add-a-member-role-to-a-group). ### Available permissions @@ -95,10 +111,10 @@ These requirements are documented in the `Required permission` column in the fol | `read_vulnerability` | GitLab 16.1 and later | Not applicable | View [vulnerability reports](application_security/vulnerability_report/index.md). | | `admin_vulnerability` | GitLab 16.1 and later | `read_vulnerability` | Change the [status of vulnerabilities](application_security/vulnerabilities/index.md#vulnerability-status-values). | | `read_dependency` | GitLab 16.3 and later | Not applicable | View [project dependencies](application_security/dependency_list/index.md). | -| `admin_merge_request` | GitLab 16.4 and later | Not applicable | View and approve [merge requests](project/merge_requests/index.md), and view the associated merge request code. <br> Does not allow users to view or change merge request approval rules. | +| `admin_merge_request` | GitLab 16.4 and later | Not applicable | View and approve [merge requests](project/merge_requests/index.md), revoke merge request approval, and view the associated merge request code. <br> Does not allow users to view or change merge request approval rules. | | `manage_project_access_tokens` | GitLab 16.5 and later | Not applicable | Create, delete, and list [project access tokens](project/settings/project_access_tokens.md). | | `admin_group_member` | GitLab 16.5 and later | Not applicable | Add or remove [group members](group/manage.md). | -| `archive_project` | GitLab 16.6 and later | Not applicable | Archive and unarchive [projects](project/settings/index.md#archive-a-project). | +| `archive_project` | GitLab 16.6 and later | Not applicable | Archive and unarchive [projects](project/settings/migrate_projects.md#archive-a-project). | ## Billing and seat usage @@ -112,7 +128,50 @@ This does not apply when the user's custom role only has the `read_code` permiss enabled. Guest users with that specific permission only are not considered billable users and do not use a seat. -## Associate a custom role with an existing group member +## Add a user to your group with a custom role + +Prerequisites: + +- You must be an administrator, or have the Owner role in the group you are creating the custom role in. + +To add a user to your group with a custom role: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Manage > Members**. +1. Select **Invite members**. +1. In **Username or email address**, if the user: + - Has a GitLab account, enter their username. + - Does not have a GitLab account, enter their email address. +1. In **Select a role**, select a static or custom role. +1. Optional. In **Access expiration date (optional)**, enter or select a date. + From that date onward, the user can no longer access the group. +1. Select **Invite**. If you invite the user by their: + - GitLab username, the user is added to the member list. + - Email address, the user receives an email invitation and is prompted to create an account. + If the invitation is not accepted, GitLab sends reminder emails two, five, and ten days later. + Unaccepted invites are automatically deleted after 90 days. + +The new member with custom role and custom permissions appears on the [group's members list](group/index.md#view-group-members). + +NOTE: +Most custom roles are considered [billable users that use a seat](#billing-and-seat-usage). When you add a user to your group with a custom role, a warning is displayed if you are about to incur additional charges for having more seats than are included in your subscription. + +### Change a member's custom role + +To change a group member's custom role: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Manage > Members**. +1. Select the **Max role** dropdown list for the member you want to select a custom role for. +1. On the **Change role** dialog, select a different custom role. + +### Associate a custom role with an existing group member + +You can use the API to associate a custom role with an existing group member. + +Prerequisites: + +- You must have the Owner role for the group. To associate a custom role with an existing group member, a group member with the Owner role: @@ -143,9 +202,9 @@ the Owner role: ## Remove a custom role -Prerequisite: +Prerequisites: -- You must be an administrator or have the Owner role in the group you are removing the custom role from. +- You must be an administrator, or have the Owner role in the group you are removing the custom role from. You can remove a custom role from a group only if no group members have that role. @@ -153,7 +212,14 @@ To do this, you can either remove the custom role from all group members with th ### Remove a custom role from a group member -To remove a custom role from a group member, use the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project) +To remove a custom role from a group member: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Manage > Members**. +1. Select the **Max role** dropdown list for the member you want to remove a custom role from. +1. On the **Change role** dialog, select a static role. + +You can update or remove a custom role from a group member also with the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project). and pass an empty `member_role_id` value: ```shell @@ -178,8 +244,7 @@ curl --request PUT --header "Content-Type: application/json" --header "Authoriza After you have made sure no group members have that custom role, delete the custom role. -1. On the left sidebar, select **Search or go to**. -1. GitLab.com only. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Roles and Permissions**. 1. Select **Custom Roles**. 1. In the **Actions** column, select **Delete role** (**{remove}**) and confirm. |