自定义角色

自定义角色允许你创建仅包含组织所需特定自定义权限的角色。每个自定义角色都基于现有的默认角色。例如，你可以基于 Guest 角色创建自定义角色，但同时包含查看项目仓库中代码的权限。

自定义角色有两种类型：

• 自定义成员角色：
  • 可以分配给组或项目的成员。
  • 在任何子组或项目中获得相同的权限。更多信息，请参见成员类型。
  • 占用席位并成为计费用户。
    • 仅包含 read_code 权限的自定义 Guest 成员角色不占用席位。
• 自定义管理员角色：
  • 可以分配给实例上的任何用户。
  • 获得执行特定管理员操作的权限。

有关自定义角色功能的演示，请参见 [Demo] Ultimate Guest can view code on private repositories via custom role。

创建自定义成员角色

要创建自定义成员角色，你需要选择一个默认的 GitLab 角色并添加额外的权限。 基础角色定义了自定义角色可用的最低权限。你不能使用审计员作为基础角色。

自定义权限可以允许通常仅限于 Maintainer 或 Owner 角色的操作。例如，具有管理 CI/CD 变量权限的自定义角色也允许管理其他 Maintainer 或 Owner 添加的 CI/CD 变量。

自定义成员角色对组和项目可用：

• 在 GitLab.com 上，在创建自定义角色的顶级组下。
• 在 GitLab Self-Managed 和 GitLab Dedicated 上，在整个实例中。

先决条件：

• 对于 GitLab.com，你必须拥有该组的 Owner 角色。
• 对于 GitLab Self-Managed 和 GitLab Dedicated，你必须拥有实例的管理员访问权限。
• 你的自定义角色必须少于 10 个。

创建自定义成员角色的步骤：

1. 在左侧边栏：
   • 对于 GitLab.com，选择 Search or go to 并找到你的组。
   • 对于 GitLab Self-Managed 和 GitLab Dedicated，在底部选择 Admin。
2. 选择 Settings > Roles and permissions。
3. 选择 New role。
4. 仅限 GitLab Self-Managed 和 GitLab Dedicated 实例。选择 Member role。
5. 输入自定义角色的名称和描述。
6. 从 Base role 下拉列表中选择一个默认角色。
7. 为自定义角色选择任何权限。
8. 选择 Create role。

你也可以使用 API创建自定义角色。

创建自定义管理员角色

要创建自定义管理员角色，你需要添加通常仅限于管理员才能执行的操作的权限。每个自定义管理员角色可以有一个或多个权限。

先决条件：

• 你必须拥有实例的管理员访问权限。
• 你的自定义角色必须少于 10 个。

创建自定义管理员角色的步骤：

1. 在左侧边栏底部，选择 Admin。
2. 选择 Settings > Roles and permissions。
3. 选择 New role。
4. 选择 Admin role。
5. 输入自定义角色的名称和描述。
6. 为自定义角色选择任何权限。
7. 选择 Create role。

你也可以使用 API创建自定义角色。

编辑自定义角色

你可以编辑自定义角色的名称、描述和权限，但不能编辑基础角色。如果需要更改基础角色，你必须创建新的自定义角色。

先决条件：

• 对于 GitLab.com，你必须拥有该组的 Owner 角色。
• 对于 GitLab Self-Managed 和 GitLab Dedicated，你必须拥有实例的管理员访问权限。

编辑自定义角色的步骤：

1. 在左侧边栏：
   • 对于 GitLab.com，选择 Search or go to 并找到你的组。
   • 对于 GitLab Self-Managed 和 GitLab Dedicated，在底部选择 Admin。
2. 选择 Settings > Roles and permissions。
3. 在自定义角色旁边，选择垂直省略号 ( ) > Edit role。
4. 修改角色。
5. 选择 Save role。

你也可以使用 API 编辑自定义成员角色或自定义管理员角色。

查看自定义角色的详细信息

Roles and permissions 页面列出了所有可用默认角色和自定义角色的基本信息。这包括名称、描述以及分配给每个自定义角色的用户数量等信息。每个自定义角色都包含一个 Custom member role 或 Custom admin role 标识。

你还可以查看自定义角色的更详细信息，包括角色 ID、基础角色和特定权限。

先决条件：

• 对于 GitLab.com，你必须拥有该组的 Owner 角色。
• 对于 GitLab Self-Managed 和 GitLab Dedicated，你必须拥有实例的管理员访问权限。

查看自定义角色详细信息的步骤：

1. 在左侧边栏：
   • 对于 GitLab.com，选择 Search or go to 并找到你的组。
   • 对于 GitLab Self-Managed 和 GitLab Dedicated，在底部选择 Admin。
2. 选择 Settings > Roles and permissions。
3. 在自定义角色旁边，选择垂直省略号 ( ) > View details。

删除自定义角色

你不能删除仍分配给用户的自定义角色。请参见为用户分配自定义角色。

先决条件：

• 对于 GitLab.com，你必须拥有该组的 Owner 角色。
• 对于 GitLab Self-Managed 和 GitLab Dedicated，你必须拥有实例的管理员访问权限。

删除自定义角色的步骤：

1. 在左侧边栏：
   • 对于 GitLab.com，选择 Search or go to 并找到你的组。
   • 对于 GitLab Self-Managed 和 GitLab Dedicated，在底部选择 Admin。
2. 选择 Settings > Roles and permissions。
3. 在自定义角色旁边，选择垂直省略号 ( ) > Delete role。
4. 在确认对话框中，选择 Delete role。

你也可以使用 API 删除自定义成员角色或自定义管理员角色。

为用户分配自定义成员角色

你可以为组和项目的成员分配或修改角色。你可以为现有用户执行此操作，或者在将用户添加到组、项目或实例时执行。

先决条件：

• 对于组，你必须拥有该组的 Owner 角色。
• 对于项目，你必须拥有至少该项目的 Maintainer 角色。

为现有用户分配自定义成员角色的步骤：

1. 在左侧边栏，选择 Search or go to 并找到你的组或项目。
2. 选择 Manage > Members。
3. 在 Role 列中，为现有成员选择角色。Role details 抽屉将打开。
4. 从 Role 下拉列表中选择要分配给该成员的角色。
5. 选择 Update role 以分配该角色。

你也可以使用 API来分配或修改自定义角色分配。

为用户分配自定义管理员角色

你可以为实例中的用户分配或修改管理员角色。你可以为现有用户执行此操作，或者在将用户添加到实例时执行。

先决条件：

• 你必须是 GitLab Self-Managed 实例的管理员。

为现有用户分配自定义管理员角色的步骤：

1. 在左侧边栏底部，选择 Admin。
2. 选择 Overview > Users。
3. 选择用户的 Edit。
4. 在 Access 部分，将访问级别设置为 Regular 或 Auditor。
5. 从 Admin area 下拉列表中选择一个自定义管理员角色。

你也可以使用 API来分配或修改自定义角色分配。

为受邀组分配自定义角色

当你邀请组加入组时，你可以为组中的每个用户分配自定义角色。

分配的角色会与用户在其原始组中的角色和权限进行比较。通常，用户会被分配具有最低访问级别的角色。但是，如果用户在其原始组中有自定义角色：

• 仅使用基础角色进行访问级别比较。不比较自定义权限。
• 如果自定义角色具有相同的基础角色，用户将保留其原始组中的自定义角色。

下表提供了受邀组用户可获得的最大角色的示例：

场景	具有 Guest 角色的用户	具有 Guest 角色和 read_code 的用户	具有 Guest 角色和 read_vulnerability 的用户	具有 Developer 角色的用户	具有 Developer 角色和 admin_vulnerability 的用户
以 Guest 角色受邀	Guest	Guest	Guest	Guest	Guest
以 Guest 角色和 read_code 受邀	Guest	Guest + read_code	Guest + read_vulnerability	Guest + read_code	Guest + read_code
以 Guest 角色和 read_vulnerability 受邀	Guest	Guest + read_code	Guest + read_vulnerability	Guest + read_vulnerability	Guest + read_vulnerability
以 Developer 角色受邀	Guest	Guest + read_code	Guest + read_vulnerability	Developer	Developer
以 Developer 角色和 admin_vulnerability 受邀	Guest	Guest + read_code	Guest + read_vulnerability	Developer	Developer + admin_vulnerability

你只能在邀请组加入另一个组时分配自定义角色。Issue 468329 提议在邀请组加入项目时分配自定义角色。

支持的对象

你可以将自定义角色和权限分配给以下对象：

对象	版本	问题
用户	15.9	已发布
组	17.7	部分支持。对项目中组分配的进一步支持在 Issue 468329 中提出
令牌	不支持	Issue 434354

将用户同步到自定义角色

如果你使用 SAML 或 LDAP 等工具管理组成员资格，你可以自动将用户同步到自定义角色。更多信息，请参见：

• 配置 SAML 组链接。
• 通过 LDAP 管理组成员资格。

将 LDAP 组同步到管理员角色

你可以将自定义管理员角色链接到 LDAP 组。此链接会将自定义管理员角色分配给组中的所有用户。

如果用户属于多个具有不同分配的自定义管理员角色的 LDAP 组，GitLab 会分配与较早创建的 LDAP 链接关联的角色。例如，如果用户是 LDAP 组 owner 和 dev 的成员。如果 owner 组在 dev 组之前链接到自定义管理员角色，则用户将被分配与 owner 组关联的角色。

有关 LDAP 和组同步管理的更多信息，请参见 LDAP 同步。

将自定义管理员角色与 LDAP CN 链接

先决条件：

• 你必须已将 LDAP 服务器与你的实例集成。

将自定义管理员角色与 LDAP CN 链接的步骤：

1. 在左侧边栏底部，选择 Admin。
2. 选择 Settings > Roles and permissions。
3. 在 LDAP Synchronization 选项卡上，选择一个 LDAP Server。
4. 在 Sync method 字段中，选择 Group cn。
5. 在 Group cn 字段中，开始输入组的 CN。将显示一个下拉列表，其中包含配置的 group_base 中匹配的 CN。
6. 从下拉列表中选择你的 CN。
7. 在 Custom admin role 字段中，选择一个自定义管理员角色。
8. 选择 Add。

GitLab 开始将角色链接到任何匹配的 LDAP 用户。此过程可能需要超过一小时才能完成。

将自定义管理员角色与 LDAP 过滤器链接

先决条件：

• 你必须已将 LDAP 服务器与你的实例集成。

将自定义管理员角色与 LDAP 过滤器链接的步骤：

1. 在左侧边栏底部，选择 Admin。
2. 选择 Settings > Roles and permissions。
3. 在 LDAP Synchronization 选项卡上，选择一个 LDAP Server。
4. 在 Sync method 字段中，选择 User filter。
5. 在 User filter 框中，输入一个过滤器。详细信息，请参见设置 LDAP 用户过滤器。
6. 在 Custom admin role 字段中，选择一个自定义管理员角色。
7. 选择 Add。

GitLab 开始将角色链接到任何匹配的 LDAP 用户。此过程可能需要超过一小时才能完成。

贡献新权限

如果某个权限不存在，你可以：

• 在 issue 391760 中讨论单个自定义角色和权限请求。
• 使用权限提议问题模板创建问题来请求该权限。
• 贡献代码到 GitLab 并添加该权限。