Custom roles

{{< details >}}

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

{{< /details >}}

{{< history >}}

{{< /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.

When you assign a custom role to a user:

  • They gain the same permissions for any subgroups or projects within the group they belong to. For more information, see membership types.
  • They use a seat or become a billable user.
    • Custom Guest roles that include only the read_code permission do not use a seat.

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

{{< alert type=”warning” >}}

Custom roles can allow users to perform actions usually restricted to the Maintainer role or higher. For example, if a custom role includes permission to manage CI/CD variables, users with the role could also manage CI/CD variables added by other Maintainers or Owners for the group or project.

{{< /alert >}}

Create a custom role

You create a custom role by adding permissions to a base role. You can add multiple permissions to that custom role. For example, you can create a custom role with the permission to do all of the following:

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

GitLab SaaS

Prerequisites:

  • You must have the Owner role for the top-level 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 GitLab Self-Managed instance.

After you create a custom role for your GitLab 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

{{< history >}}

{{< /history >}}

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 ({{< icon name=”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 GitLab Self-Managed instance.
  1. On the left sidebar, at the bottom, select Admin.
  2. Select Settings > Roles and permissions.
  3. Select the vertical ellipsis ({{< icon name=”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 a custom role

Prerequisites:

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

You can’t remove a custom role from a group if there are members assigned that role. See assign a custom role to a user.

  1. On the left sidebar:
    • For GitLab 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 ({{< icon name=”remove” >}}) and confirm.

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

Assign a custom role to a user

You can assign or modify roles for members of your groups and projects. This can be done for existing users or when you add a user to the group or project.

Prerequisites:

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

To assign a role to an existing user:

  1. On the left sidebar, 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 group and project members API to assign or modify role assignments.

Assign a custom role to an invited group

{{< history >}}

{{< /history >}}

{{< alert type=”flag” >}}

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

{{< /alert >}}

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:

Scenario User A User B User C User D User E
Group B invites Group A with Guest Guest Guest Guest Guest Guest
Group B invites Group A with Guest + read_code Guest Guest + read_code Guest + read_vulnerability Guest + read_code Guest + read_code
Group B invites Group A with Guest + read_vulnerability Guest Guest + read_code Guest + read_vulnerability Guest + read_vulnerability Guest + read_vulnerability
Group B invites Group A with Developer Guest Guest + read_code Guest + read_vulnerability Developer Developer
Group B invites Group A with Developer + admin_vulnerability Guest Guest + read_code Guest + read_vulnerability Developer Developer + admin_vulnerability

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). The ability to assign a custom role when sharing a group to a project can be tracked in issue 468329.

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

Sync users to custom roles

If you use tools like SAML or LDAP to manage your group membership, you can automatically sync your users to custom roles. For more information, see:

Custom admin roles

{{< history >}}

{{< /history >}}

Prerequisites:

  • You must be an administrator for the GitLab Self-Managed instance.

You can use the API to create and assign custom admin roles. These roles allow you to grant limited access to administrator resources.

For information on available permissions, see custom permissions.

Contribute new permissions

If a permission does not exist, you can:

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.