Skip to content

Custom roles (ULTIMATE ALL)

Custom roles allow group Owners or instance administrators to create roles specific to the needs of their organization.

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.

Create a custom role

Prerequisites:

  • You must be an administrator for the self-managed instance, or have the Owner role in the group you are creating the custom role in.
  • The group must be in the Ultimate tier.
  • You must have:
    • At least one private project so that you can see the effect of giving a user a custom role. The project can be in the group itself or one of that group's subgroups.
    • If you are using the API to create the custom role, a personal access token with the API scope.

You create a custom role by selecting permissions to add to a base role.

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

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

GitLab SaaS

Prerequisite:

  • You must have the Owner role in the group you are creating the custom role in.
  1. On the left sidebar, select Search or go to and find your group.
  2. Select Settings > Roles and Permissions.
  3. Select Add new role.
  4. In Base role to use as template, select an existing non-custom role.
  5. In Role name, enter the custom role's title.
  6. Select the Permissions for the new custom role.
  7. Select Create new role.

Self Managed GitLab Instances

Prerequisite:

  • 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.
  2. Select Admin Area.
  3. Select Settings > Roles and Permissions.
  4. From the top dropdown list, select the group you want to create a custom role in.
  5. Select Add new role.
  6. In Base role to use as template, select an existing non-custom role.
  7. In Role name, enter the custom role's title.
  8. Select the Permissions for the new custom role.
  9. Select Create new role.

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

Available permissions

The following permissions are available. You can add these permissions in any combination to a base role to create a custom role.

Some permissions require having other permissions enabled first. For example, administration of vulnerabilities (admin_vulnerability) can only be enabled if reading vulnerabilities (read_vulnerability) is also enabled.

These requirements are documented in the Required permission column in the following table.

Permission Version Required permission Description
read_code GitLab 15.7 and later Not applicable View project code. Does not include the ability to pull code.
read_vulnerability GitLab 16.1 and later Not applicable View vulnerability reports.
admin_vulnerability GitLab 16.1 and later read_vulnerability Change the status of vulnerabilities.
read_dependency GitLab 16.3 and later Not applicable View project dependencies.
admin_merge_request GitLab 16.4 and later Not applicable View and approve merge requests, and view the associated merge request code.
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.
admin_group_member GitLab 16.5 and later Not applicable Add or remove group members.
archive_project GitLab 16.6 and later Not applicable Archive and unarchive projects.

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:

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.

Associate a custom role with an existing group member

To associate a custom role with an existing group member, a group member with the Owner role:

  1. Invites 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 the Owner does not know the id of the Guest user receiving a custom role, finds that id by making an API request.

  3. Associates the member with the Guest+1 role using the Group and Project Members API endpoint

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

Remove a custom role

Prerequisite:

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

To do this, you can either remove the custom role from all group members with that custom role, or remove those members from the group.

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 and pass 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>"

Remove a group member with a custom role from the group

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Manage > Members.
  3. On the member row you want to remove, select the vertical ellipsis ({ellipsis_v}) and select Remove member.
  4. In the Remove member confirmation dialog, do not select any checkboxes.
  5. Select Remove member.

Delete the custom role

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.
  2. GitLab.com only. Select Admin Area.
  3. Select Settings > Roles and Permissions.
  4. Select Custom Roles.
  5. In the Actions column, select Delete role ({remove}) and confirm.

To delete a custom role, you can also use the API. 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.

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.