Custom roles

DETAILS: Tier: Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

• Custom roles feature introduced in GitLab 15.7 with a flag named customizable_roles.
• Enabled by default in GitLab 15.9.
• Feature flag removed in GitLab 15.10.
• 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 roles allow an organization to create user roles with the precise privileges and permissions required for that organization's needs.

For a demo of the custom roles feature, see [Demo] Ultimate Guest can view code on private repositories via custom role.

You can discuss individual custom role and permission requests in issue 391760.

NOTE: Most custom roles are considered billable users that use a seat. 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.

Available permissions

For more information on available permissions, see custom permissions.

WARNING: Depending on the permissions added to a lower base role such as Guest, a user with a custom role might be able to perform actions that are usually restricted to the Maintainer role or higher. For example, if a custom role is Guest plus managing CI/CD variables, a user with this role can manage CI/CD variables added by other Maintainers or Owners for that group or project.

Create a custom role

You create a custom role by adding permissions to a base role.

You can select any number of permissions. For example, you can create a custom role with the permission to:

• View vulnerability reports.
• Change the status of vulnerabilities.
• Approve merge requests.

GitLab SaaS

Prerequisites:

• You must have the Owner role for the group.

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > Roles and Permissions.
3. Select New role.
4. In Base role to use as template, select an existing default role.
5. In Role name, enter the custom role's title.
6. In Description, enter a description for the custom role. 255 characters max.
7. Select the Permissions for the new custom role.
8. Select Create 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.

GitLab self-managed

Prerequisites:

• You must be an administrator for the self-managed instance.

After you create a custom role for your self-managed instance, you can assign that custom role to a user in any group or subgroup in that instance.

1. On the left sidebar, at the bottom, select Admin.
2. Select Settings > Roles and Permissions.
3. Select New role.
4. In Base role to use as template, select an existing default role.
5. In Role name, enter the custom role's title.
6. In Description, enter a description for the custom role. 255 characters max.
7. Select the Permissions for the new custom role.
8. Select Create 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.

Edit a custom role

• Introduced in GitLab 17.0.

After a custom role has been created, you can edit that custom role's name, description, and permissions. You cannot change the base role. If you need to change the base role, you must create a new custom role.

GitLab SaaS

Prerequisites:

• You must have the Owner role for the group.

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > Roles and Permissions.
3. Select the vertical ellipsis ({ellipsis_v}) for the custom role, then select Edit role.
4. Modify the role as needed.
5. Select Save role to update the role.

GitLab self-managed

Prerequisites:

• You must be an administrator for the self-managed instance.

1. On the left sidebar, at the bottom, select Admin.
2. Select Settings > Roles and Permissions.
3. Select the vertical ellipsis ({ellipsis_v}) for the custom role, then select Edit role.
4. Modify the role as needed.
5. Select Save role to update the role.

To edit a custom role, you can also use the API.

Delete the custom role

Prerequisites:

• You must be an administrator or have the Owner role for the group.

You can remove a custom role from a group only if no members have that role. See unassign a custom role from a group or project member.

1. On the left sidebar:
   • For self-managed, at the bottom, select Admin.
   • For SaaS, select Search or go to and find your group.
2. Select Settings > Roles and Permissions.
3. Select Custom Roles.
4. In the Actions column, select Delete role ({remove}) and confirm.

You can also use the API to delete a custom role. To use the API, you must know the id of the custom role. If you do not know this id, find it by making an API request on the group or an API request on the instance.

Add a user with a custom role to your group or project

Prerequisites:

If you are adding a user with a custom role:

• To your group, you must have the Owner role for the group.
• To your project, you must have at least the Maintainer role for the project.

To add a user with a custom role:

• To a group, see add users to a group.
• To a project, see add users to a project.

If a group or project member has a custom role, the group or project members list displays "Custom Role" in the Max role column of the table.

Assign a custom role to an existing group or project member

Prerequisites:

If you are assigning a custom role to an existing:

• Group member, you must have the Owner role for the group.
• Project member, you must have at least the Maintainer role for the project.

Use the UI to assign a custom role

1. On the left sidebar, select Search or go to and find your group or project.
2. Select Manage > Members.
3. In the Max role column, select the role for the member. The Role details drawer opens.
4. Using the Role dropdown list, select the custom role you want to assign to the member.
5. Select Update role to assign the role.

Use the API to assign a custom role

1. Invite a user as a direct member to the root group or any subgroup or project in the root group's hierarchy as a Guest. At this point, this Guest user cannot see any code on the projects in the group or subgroup.

2. Optional. If you do not know the id of the Guest user receiving a custom role, find that id by making an API request.

3. Use the Group and Project Members API endpoint to associate the member with the Guest+1 role:

   # to update a project membership
   curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" --data '{"member_role_id": '<member_role_id>', "access_level": 10}' "https://gitlab.example.com/api/v4/projects/<project_id>/members/<user_id>"
   
   # to update a group membership
   curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" --data '{"member_role_id": '<member_role_id>', "access_level": 10}' "https://gitlab.example.com/api/v4/groups/<group_id>/members/<user_id>"

   Where:

   • <project_id and <group_id>: The id or URL-encoded path of the project or group associated with the membership receiving the custom role.
   • <member_role_id>: The id of the member role created in the previous section.
   • <user_id>: The id of the user receiving a custom role.

   Now the Guest+1 user can view code on all projects associated with this membership.

Unassign a custom role from a group or project member

Prerequisites:

If you are unassigning a custom role from a:

• Group member, you must have the Owner role for the group.
• Project member, you must have at least the Maintainer role for the project.

You can remove a custom role from a group or project only if no group or project members have that role. To do this, you can use one of the following methods:

• Remove a member with a custom role from a group or project.
• Use the UI to change the user role.
• Use the API to change the user role.

Use the UI to change user role

To remove a custom role from a group member:

1. On the left sidebar, select Search or go to and find your group.
2. Select Manage > Members.
3. In the Max role column, select the role for the member. The Role details drawer opens.
4. Using the Role dropdown list, select the default role you want to assign to the member.
5. Select Update role to assign the role.

Use the API to change user role

You can also use the Group and Project Members API endpoint to update or remove a custom role from a group member by passing an empty member_role_id value:

# to update a project membership
curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" --data '{"member_role_id": null, "access_level": 10}' "https://gitlab.example.com/api/v4/projects/<project_id>/members/<user_id>"

# to update a group membership
curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" --data '{"member_role_id": null, "access_level": 10}' "https://gitlab.example.com/api/v4/groups/<group_id>/members/<user_id>"

Inheritance

If a user belongs to a group, they are a direct member of the group and an inherited member of any subgroups or projects. If a user is assigned a custom role by the top-level group, the permissions of the role are also inherited by subgroups and projects.

For example, assume the following structure exists:

• Group A
  • Subgroup B
    • Project 1

If a custom role with Developer + Manage CI/CD variables permission is assigned to Group A, the user also has Manage CI/CD variables permission for Subgroup B and Project 1.

Billing and seat usage

When you enable a custom role for a user with the Guest role, that user has access to elevated permissions over the base role, and therefore:

• Is considered a billable user on self-managed GitLab.
• Uses a seat on GitLab.com.

This does not apply when the user's custom role only has the read_code permission enabled. Guest users with that specific permission only are not considered billable users and do not use a seat.

Assign a custom role to an invited group

• 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.

FLAG: The availability of this feature is controlled by a feature flag. For more information, see the history.

When a group is invited to another group with a custom role, the following rules determine each user's custom permissions in the new group:

• When a user has a custom permission in one group with a base access level that is the same or higher than the default role in the other group, the user's maximum role is the default role. That is, the user is granted the lower of the two access levels.
• When a user is invited with a custom permission with the same base access level as their original group, the user is always granted the custom permission from their original group.

For example, let's say we have 5 users in Group A, and they are assigned the following roles:

• User A: Guest role
• User B: Guest role + read_code custom permission
• User C: Guest role + read_vulnerability custom permission
• User D: Developer role
• User E: Developer + admin_vulnerability custom permission

Group B invites Group A. The following table shows the maximum role that each the users in Group A will have in Group B:

When User C is invited to Group B with the same default role (Guest), but different custom permissions with the same base access level (read_code and read_vulnerability), User C retains the custom permission from Group A (read_vulnerability).

Supported objects

You can assign custom roles and permissions to the following:

Supported group links

You can sync users to custom roles with following authentication providers:

• See Configure SAML Group Links.
• See Manage group memberships via LDAP.

Known issues

• If a user with a custom role is shared with a group or project, their custom role is not transferred over with them. The user has the regular Guest role in the new group or project.
• You cannot use an Auditor user as a template for a custom role.
• There can be only 10 custom roles on your instance or namespace. See issue 450929 for more details.