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.
- On the left sidebar, select Search or go to and find your group.
- Select Settings > Roles and Permissions.
- Select New role.
- In Base role to use as template, select an existing default role.
- In Role name, enter the custom role's title.
- In Description, enter a description for the custom role. 255 characters max.
- Select the Permissions for the new custom role.
- 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.
- On the left sidebar, at the bottom, select Admin area.
- Select Settings > Roles and Permissions.
- Select New role.
- In Base role to use as template, select an existing default role.
- In Role name, enter the custom role's title.
- In Description, enter a description for the custom role. 255 characters max.
- Select the Permissions for the new custom role.
- 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.
- On the left sidebar, select Search or go to and find your group.
- Select Settings > Roles and Permissions.
- Select the vertical ellipsis ({ellipsis_v}) for the custom role, then select Edit role.
- Modify the role as needed.
- Select Save role to update the role.
GitLab self-managed and GitLab Dedicated
Prerequisites:
- You must be an administrator for the self-managed instance.
- On the left sidebar, at the bottom, select Admin area.
- Select Settings > Roles and Permissions.
- Select the vertical ellipsis ({ellipsis_v}) for the custom role, then select Edit role.
- Modify the role as needed.
- 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.
- On the left sidebar:
- For self-managed, at the bottom, select Admin area.
- For SaaS, select Search or go to and find your group.
- Select Settings > Roles and Permissions.
- Select Custom Roles.
- 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
- On the left sidebar, select Search or go to and find your group or project.
- Select Manage > Members.
- Select the Max role dropdown list for the member you want to select a custom role for.
- On the Change role dialog, select a different custom role.
Use the API to assign a custom role
-
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.
-
Optional. If you do not know the
id
of the Guest user receiving a custom role, find thatid
by making an API request. -
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>
: Theid
or URL-encoded path of the project or group associated with the membership receiving the custom role. -
<member_role_id>
: Theid
of the member role created in the previous section. -
<user_id>
: Theid
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:
- On the left sidebar, select Search or go to and find your group.
- Select Manage > Members.
- Select the Max role dropdown list for the member you want to remove a custom role from.
- On the Change role dialog, select a default 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
- Subgroup B
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.
Supported objects
You can assign custom roles and permissions to the following:
Object | Version | Issue |
---|---|---|
Users | 15.9 | Released |
Groups | Not supported | Issue 443369 |
Tokens | Not supported | Issue 434354 |
Supported group links
You can sync users to custom roles with following authentication providers:
- See Configure SAML Group Links.
- LDAP Group Links are not supported, but issue 435229 proposes to change this.
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.