Permissions and roles (FREE ALL)

When you add a user to a project or group, you assign them a role. The role determines which actions they can take in GitLab.

If you add a user to both a project's group and the project itself, the higher role is used.

GitLab administrators have all permissions.

Roles

The available roles are:

• Guest (This role applies to private and internal projects only.)
• Reporter
• Developer
• Maintainer
• Owner
• Minimal Access (available for the top-level group only)

A user assigned the Guest role has the least permissions, and the Owner has the most.

By default, all users can create top-level groups and change their usernames. A GitLab administrator can change this behavior for the GitLab instance.

Project members permissions

• Introduced in GitLab 14.8, personal namespace owners appear with Owner role in new projects in their namespace. Introduced with a flag named personal_project_owner_with_owner_access. Disabled by default.
• Generally available in GitLab 14.9. Feature flag personal_project_owner_with_owner_access removed.

A user's role determines what permissions they have on a project. The Owner role provides all permissions but is available only:

• For group and project Owners. In GitLab 14.8 and earlier, the role is inherited for a group's projects.
• For Administrators.

Personal namespace owners:

• Are displayed as having the Maintainer role on projects in the namespace, but have the same permissions as a user with the Owner role.
• In GitLab 14.9 and later, for new projects in the namespace, are displayed as having the Owner role.

For more information about how to manage project members, see members of a project.

The following table lists project permissions available for each role:

1. On self-managed GitLab instances, users with the Guest role are able to perform this action only on public and internal projects (not on private projects). External users must be given explicit access (at least the Reporter role) even if the project is internal. Users with the Guest role on GitLab.com are only able to perform this action on public projects because internal visibility is not available.
2. Guest users can only view the confidential issues they created themselves or are assigned to.
3. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See protected branches.
4. If the branch is protected, this depends on the access given to Developers and Maintainers.
5. Guest users can access GitLab Releases for downloading assets but are not allowed to download the source code nor see repository information like commits and release evidence.
6. Actions are limited only to records owned (referenced) by user.
7. When Share Group Lock is enabled the project can't be shared with other groups. It does not affect group with group sharing.
8. For information on eligible approvers for merge requests, see Eligible approvers.
9. Applies only to comments on Design Management designs.
10. Users can only view events based on their individual actions.
11. Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding trial licenses).
12. If the tag is protected, this depends on the access given to Developers and Maintainers.
13. A Maintainer or Owner can't change project features visibility level if project visibility is set to private.
14. Attached design files are moved together with the issue even if the user doesn't have the Developer role.
15. Guest users can only set metadata (for example, labels, assignees, or milestones) when creating an issue. They cannot change the metadata on existing issues.
16. In projects that accept contributions from external members, users can create, edit, and close their own merge requests.
17. Authors and assignees can modify the title and description even if they don't have the Reporter role.
18. Authors and assignees can close and reopen issues even if they don't have the Reporter role.
19. The ability to view the Container Registry and pull images is controlled by the Container Registry's visibility permissions.
20. Maintainers cannot create, demote, or remove Owners, and they cannot promote users to the Owner role. They also cannot approve Owner role access requests.
21. Authors of tasks can delete them even if they don't have the Owner role, but they have to have at least the Guest role for the project.
22. You must have permission to view the epic.
23. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator (on self-managed) or group owner (on GitLab.com) gives those users permission. The administrator or group owner can create a custom role through the API and assign that role to the users.

Project features permissions

More details about the permissions for some project-level features follow.

GitLab CI/CD permissions

GitLab CI/CD permissions for some roles can be modified by these settings:

• Public pipelines: When set to public, gives access to certain CI/CD features to Guest project members.
• Pipeline visibility: When set to Everyone with Access, gives access to certain CI/CD "view" features to non-project members.

1. If the project is public and Public pipelines is enabled in Project Settings > CI/CD.
2. If Public pipelines is enabled in Project Settings > CI/CD.
3. If the project is public.
4. Only if the job was both:
   • Triggered by the user.
   • In GitLab 13.0 and later, run for a non-protected branch.
5. If the user is allowed to merge or push to the protected branch.
6. If the user if part of a group with at least the Reporter role

Job permissions

This table shows granted privileges for jobs triggered by specific types of users:

1. Only if the triggering user is not an external one.
2. Only if the triggering user is a member of the project. See also Usage of private Docker images with if-not-present pull policy.

Group members permissions

Any user can remove themselves from a group, unless they are the last Owner of the group.

The following table lists group permissions available for each role:

1. Groups can be set to allow either Owners, or Owners and users with the Maintainer role, to create subgroups.
2. Default project creation role can be changed at:
   • The instance level.
   • The group level.
3. Does not apply to subgroups.
4. Developers can push commits to the default branch of a new project only if the default branch protection is set to "Partially protected" or "Not protected".
5. In addition, if your group is public or internal, all users who can see the group can also see group wiki pages.
6. Users can only view events based on their individual actions.
7. You must have permission to view the epic and edit the issue.
8. You must have permission to view the parent and child epics.

Subgroup permissions

When you add a member to a subgroup, they inherit the membership and permission level from the parent groups. This model allows access to nested groups if you have membership in one of its parents.

For more information, see subgroup memberships.

Users with Minimal Access (PREMIUM ALL)

• Introduced in GitLab 13.4.
• Support for inviting users with Minimal Access role introduced in GitLab 15.9.

Users with the Minimal Access role do not:

• Count as licensed seats on self-managed Ultimate subscriptions or any GitLab.com subscriptions.
• Automatically have access to projects and subgroups in that root group.

Owners must explicitly add these users to the specific subgroups and projects.

You can use the Minimal Access role to give the same member more than one role in a group:

1. Add the member to the root group with a Minimal Access role.
2. Invite the member as a direct member with a specific role in any subgroup or project in that group.

Because of an outstanding issue, when a user with the Minimal Access role:

• Signs in with standard web authentication, they receive a 404 error when accessing the parent group.
• Signs in with Group SSO, they receive a 404 error immediately because they are redirected to the parent group page.

To work around the issue, give these users the Guest role or higher to any project or subgroup within the parent group.

Related topics

• The GitLab principles behind permissions
• Members
• Customize permissions on protected branches
• LDAP user permissions
• Value stream analytics permissions
• Project aliases
• Auditor users
• Confidential issues
• Container Registry permissions
• Release permissions
• Read-only namespaces

Custom roles (ULTIMATE ALL)

• 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.
• The ability for a custom role to view a vulnerability report introduced in GitLab 16.1.

FLAG: On self-managed GitLab, by default the ability for a custom role to view a vulnerability report is not available. To make it available, an administrator can enable the feature flag named elevated_guests. On GitLab.com, this feature is available.

Custom roles allow group members who are assigned the Owner role 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.

The following custom roles are available:

• The Guest+1 role, which allows users with the Guest role to view code.
• In GitLab 16.1 and later, you can create a custom role that can view vulnerability reports and change the status of the vulnerabilities.

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

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

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

This does not apply to the Guest+1 custom role because the view_code ability is excluded from this behavior.

Create a custom role

To enable custom roles for your group, a group member with the Owner role:

1. Makes sure that there is at least one private project in this group or one of its subgroups, so that you can see the effect of giving a Guest a custom role.
2. Creates a personal access token with the API scope.
3. Uses the API to create a custom role for the root group.

Custom role requirements

For every ability, a minimal access level is defined. To be able to create a custom role which enables a certain ability, the member_roles table record has to have the associated minimal access level. For all abilities, the minimal access level is Guest. Only users who have at least the Guest role can be assigned to a custom role.

Some roles and abilities require having other abilities enabled. For example, a custom role can only have administration of vulnerabilities (admin_vulnerability) enabled if reading vulnerabilities (read_vulnerability) is also enabled.

You can see the required minimal access levels and abilities requirements in the following table.

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://example.gitlab.com/api/v4/projects/$ID/members/$GUEST_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://example.gitlab.com/api/v4/groups/$ID/members/$GUEST_USER_ID"

   Where:

   • $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.
   • $GUEST_USER_ID: The ID of the Guest user receiving a custom role.

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

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.

curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"member_role_id": "", "access_level": 10}' "https://example.gitlab.com/api/v4/groups/$GROUP_PATH/members/$GUEST_USER_ID"

Now the user is a regular Guest.

Remove a custom role

Removing a custom role also removes all members with that custom role from the group. If you decide to delete a custom role, you must re-add any users with that custom role to the group.

To remove a custom role from a group, a group member with the Owner role:

1. Optional. If the Owner does not know the ID of a custom role, finds that ID by making an API request.
2. Uses the API to delete the custom role.

Known issues

• Additional permissions can only be applied to users with the Guest role.
• 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.