Custom roles

{{< details >}}

• Tier: Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• Ability to create and remove a custom role with the UI introduced in GitLab 16.4.
• 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 in GitLab 16.7.
• Ability to create and remove an instance-wide custom role on GitLab Self-Managed introduced in GitLab 16.9.
• Custom admin roles introduced as an experiment in GitLab 17.7 with a flag named custom_ability_read_admin_dashboard.
• Ability to manage custom admin roles with the UI introduced in GitLab 17.9 with a flag named custom_admin_roles. Disabled by default.
• Custom admin roles generally available in GitLab 18.3. Feature flag custom_admin_roles enabled by default.

{{< /history >}}

Custom roles allow you to create roles with only the specific custom permissions required by your organization. Each custom role is based on an existing default role. For example, you might create a custom role based on the Guest role, but also include permission to view code in a project repository.

GitLab provides two types of custom roles:

• Custom member roles:
  • Can be assigned to members of a group or project.
  • Gains the same permissions in any subgroups or projects. For more information, see membership types.
  • Uses a seat and becomes a billable user.
    • A custom Guest member role that includes only the read_code permission does not use a seat.
  • Can be assigned to members of an SAML or LDAP group.
• Custom admin roles:
  • Can be assigned to any user on the instance.
  • Gains permissions to perform specific admin actions.
  • Can be assigned to members of an LDAP group.

<i class="fa-youtube-play" aria-hidden="true"></i> For a demo of the custom roles feature, see [Demo] Ultimate Guest can view code on private repositories via custom role.

<!-- Video published on 2023-02-13 -->

Create a custom member role

To create a custom member role, you select a default GitLab role and add additional permissions. The base role defines the minimum permissions available to the custom role. You cannot use auditor as a base role.

Custom permissions can allow actions typically restricted to the Maintainer or Owner role. For example, a custom role with permission to manage CI/CD variables also allows management of CI/CD variables added by other Maintainers or Owners.

Custom member roles are available to groups and projects:

• On GitLab.com, under the top-level group where the custom role was created.
• On GitLab Self-Managed and GitLab Dedicated, in the entire instance.

Prerequisites:

• For GitLab.com, you must have the Owner role for the group.
• For GitLab Self-Managed and GitLab Dedicated, you must have administrator access to the instance.
• You must have fewer than 10 custom roles.

To create a custom member role:

1. In the left sidebar:
   • For GitLab.com, in the top bar, select Search or go to and find your group.
   • For GitLab Self-Managed and GitLab Dedicated, in the upper-right corner, select Admin.
2. Select Settings > Roles and permissions.
3. Select New role.
4. GitLab Self-Managed and GitLab Dedicated instances only. Select Member role.
5. Enter a name and description for the custom role.
6. From the Base role dropdown list, select a default role.
7. Select any permissions for the custom role.
8. Select Create role.

You can also use the API to create a custom role.

Create a custom admin role

{{< details >}}

• Offering: GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

To create a custom admin role, you add permissions that allow actions typically limited to administrators. Each custom admin role can have one or more permissions.

Prerequisites:

• You must have administrator access to the instance.
• You must have fewer than 10 custom roles.

To create a custom admin role:

1. In the upper-right corner, select Admin.
2. Select Settings > Roles and permissions.
3. Select New role.
4. Select Admin role.
5. Enter a name and description for the custom role.
6. Select any permissions for the custom role.
7. Select Create role.

You can also use the API to create a custom role.

Edit a custom role

{{< history >}}

• Introduced in GitLab 17.0.

{{< /history >}}

You can edit the name, description, and permissions of a custom role, but you cannot edit the base role. If you need to change the base role, you must create a new custom role.

Prerequisites:

• For GitLab.com, you must have the Owner role for the group.
• For GitLab Self-Managed and GitLab Dedicated, you must have administrator access to the instance.

To edit a custom role:

1. In the left sidebar:
   • For GitLab.com, in the top bar, select Search or go to and find your group.
   • For GitLab Self-Managed and GitLab Dedicated, in the upper-right corner, select Admin.
2. Select Settings > Roles and permissions.
3. Next to a custom role, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) > Edit role.
4. Modify the role.
5. Select Save role.

You can also use the API to edit a custom member role or a custom admin role.

View details of a custom role

The Roles and permissions page lists basic information about all available default and custom roles. This includes information like the name, description, and number of users assigned each custom role. Each custom role includes either a Custom member role or Custom admin role badge.

You can also view more detailed information about a custom role including the role ID, base role, and specific permissions.

Prerequisites:

• For GitLab.com, you must have the Owner role for the group.
• For GitLab Self-Managed and GitLab Dedicated, you must have administrator access to the instance.

To view details of a custom role:

1. In the left sidebar:
   • For GitLab.com, in the top bar, select Search or go to and find your group.
   • For GitLab Self-Managed and GitLab Dedicated, in the upper-right corner, select Admin.
2. Select Settings > Roles and permissions.
3. Next to a custom role, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) > View details.

Delete a custom role

You cannot delete custom roles that are still assigned to a user. See assign a custom role to a user.

Prerequisites:

• For GitLab.com, you must have the Owner role for the group.
• For GitLab Self-Managed and GitLab Dedicated, you must have administrator access to the instance.

To delete a custom role:

1. In the left sidebar:
   • For GitLab.com, in the top bar, select Search or go to and find your group.
   • For GitLab Self-Managed and GitLab Dedicated, in the upper-right corner, select Admin.
2. Select Settings > Roles and permissions.
3. Next to a custom role, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) > Delete role.
4. On the confirmation dialog, select Delete role.

You can also use the API to delete a custom member role or a custom admin role.

Assign a custom member role

You can assign or modify roles for members of your groups and projects. You can do this for existing users or when you add a user to a group, project, or instance.

Prerequisites:

• For groups, you must have the Owner role for the group.
• For projects, you must have the Maintainer or Owner role for the project.

To assign a custom member role to an existing user:

1. In the top bar, select Search or go to and find your group or project.
2. Select Manage > Members.
3. In the Role column, select the role for an existing member. The Role details drawer opens.
4. From the Role dropdown list, select a role to assign to the member.
5. Select Update role to assign the role.

You can also use the API to assign or modify custom role assignments.

Assign a custom admin role

{{< details >}}

• Offering: GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

You can assign or modify admin roles to users in your instance. You can do this for existing users or when you add a user to the instance.

Prerequisites:

• You must be an administrator for the GitLab instance.

To assign a custom admin role to an existing user:

1. In the upper-right corner, select Admin.
2. Select Overview > Users.
3. Select Edit for a user.
4. In the Access section, set the access level to either Regular or Auditor.
5. From the Admin area dropdown list, select a custom admin role.

You can also use the API to assign or modify custom role assignments.

Assign a custom role to an invited group

{{< history >}}

• Support for custom roles for invited groups introduced in GitLab 17.4 behind a feature flag named assign_custom_roles_to_group_links_sm. Disabled by default.
• Enabled on GitLab Self-Managed and GitLab Dedicated in GitLab 17.4.

{{< /history >}}

[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.

When you invite a group to a group you can assign a custom role to every user in the group.

The assigned role is compared to user roles and permissions in their original group. Generally, users are assigned the role with the smallest access level. However, if users have a custom role in their original group:

• Only the base role is used for access level comparisons. Custom permissions are not compared.
• If the custom roles both have the same base role, users keep their custom role from the original group.

The following table provides examples of the maximum role available to users invited to a group:

Scenario	User with Guest role	User with Guest role + read_code	User with Guest role + read_vulnerability	User with Developer role	User with Developer role + admin_vulnerability
Invited with Guest role	Guest	Guest	Guest	Guest	Guest
Invited with Guest role + read_code	Guest	Guest + read_code	Guest + read_vulnerability	Guest + read_code	Guest + read_code
Invited with Guest role + read_vulnerability	Guest	Guest + read_code	Guest + read_vulnerability	Guest + read_vulnerability	Guest + read_vulnerability
Invited with Developer role	Guest	Guest + read_code	Guest + read_vulnerability	Developer	Developer
Invited with Developer role + admin_vulnerability	Guest	Guest + read_code	Guest + read_vulnerability	Developer	Developer + admin_vulnerability

You can only assign custom roles when you invite a group to another group. Issue 468329 proposes to assign a custom role when inviting a group to a project.

Supported objects

You can assign custom roles and permissions to the following:

Object	Version	Issue
Users	15.9	Released
Groups	17.7	Partially supported. Further support for group assignment in projects is proposed in Issue 468329
Tokens	Not supported	Issue 434354

Assign a custom role to an external group

{{< details >}}

• Offering: GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

You can assign a custom member role to all users in an external LDAP or SAML group, or a custom admin role to users synced from an LDAP group only.

To assign custom roles to LDAP or SAML groups:

• Assign a custom member role to an SAML group.
• Assign a custom member role to an LDAP group.
• Assign a custom admin role to an LDAP group.

Contribute new permissions

If a permission does not exist, you can:

• Discuss individual custom role and permission requests in issue 391760.
• Create an issue to request the permission with the permission proposal issue template.
• Contribute to GitLab and add the permission.