Roles and permissions

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

You can assign users a default role or a custom role.

The available default roles are:

• Guest (This role applies to private and internal projects only.)
• Planner
• 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.

Group members permissions

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

The following table lists group permissions available for each role:

Analytics group permissions

Group permission for analytics features including value streams, product analytics, and insights:

Application security group permissions

Group permissions for Application Security features including dependency management, security analyzers, security policies, and vulnerability management.

CI/CD group permissions

Group permissions for CI/CD features including runners, variables, and protected environments:

Compliance group permissions

Group permissions for compliance features including compliance center, audit events, compliance frameworks, and licenses.

Footnotes

1. Users can view only events based on their individual actions. For more details, see the prerequisites.

GitLab Duo group permissions

Group permissions for GitLab Duo:

Footnotes

1. If the user has GitLab Duo Pro or Enterprise, the user must be assigned a seat to gain access to that GitLab Duo add-on. If the user has GitLab Duo Core, there are no other requirements.

Groups group permissions

Group permissions for group features:

Footnotes

1. Developers and Maintainers can only view events based on their individual actions. For more information, see the prerequisites.
2. Developers, Maintainers and Owners: Only if the project creation role is set for the instance or for the group.
   Developers: 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”.
3. Maintainers: Only if users with the Maintainer role can create subgroups.
4. Does not apply to subgroups.

Project planning group permissions

Footnotes

1. You must have permission to view the epic.
2. You must have permission to view the epic and edit the issue.
3. You must have permission to view the parent and child epics.

Group permissions for wikis:

Footnotes

1. Guests: In addition, if your group is public or internal, all users who can see the group can also see group wiki pages.
2. Guests: In addition, if your group is public or internal, all users who can see the group can also search group wiki pages.

Packages and registries group permissions

Group permissions for container registry:

Footnotes

1. Guests can only view events based on their individual actions.

Group permissions for package registry:

Repository group permissions

Group permissions for repository features including merge requests, push rules, and deploy tokens.

User management group permissions

Group permissions for user management:

Workspace group permissions

Groups permissions for workspaces:

Project members permissions

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.
• 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.
• 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 tables list the project permissions available for each role.

Analytics

Project permissions for analytics features including value streams, usage trends, product analytics, and insights.

Application security

Project permissions for application security features including dependency management, security analyzers, security policies, and vulnerability management.

Footnotes

1. The admin_vulnerability permission was removed from the Developer role in GitLab 17.0.

CI/CD

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

• Project-based pipeline visibility: 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.

Project Owners can perform any listed action, and can delete pipelines:

Footnotes

1. Non-members and guests: Only if the project is public.
2. Non-members: Only if the project is public and Project-based pipeline visibility is enabled in Project Settings > CI/CD.
   Guests: Only if Project-based pipeline visibility is enabled in Project Settings > CI/CD.
3. Non-members: Only if the project is public, Project-based pipeline visibility is enabled in Project Settings > CI/CD, and artifacts:public: false is not set on the job.
   Guests: Only if Project-based pipeline visibility is enabled in Project Settings > CI/CD and artifacts:public: false is not set on the job.
   Reporters: Only if artifacts:public: false is not set on the job.
4. Guests: Only if Project-based pipeline visibility is enabled in Project Settings > CI/CD.
5. Reporters: Only if the user is part of a group with access to the protected environment.
   Developers and maintainers: Only if the user is allowed to deploy to the protected branch.
6. Developers and maintainers: Only if the user is allowed to merge or push to the protected branch.
7. Developers: Only if the job was triggered by the user and runs for a non-protected branch.
8. Cancellation permissions can be restricted in the pipeline settings.

This table shows granted privileges for jobs triggered by specific roles.

Project Owners can do any listed action, but no users can push source and LFS together. Guest users and members with the Reporter role cannot do any of these actions.

Footnotes

1. Developers and Maintainers: Only if the triggering user is not an external user.
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.
3. You cannot push container images to other projects.

Compliance

Project permissions for compliance features including compliance center, audit events, compliance frameworks, and licenses.

Footnotes

1. On GitLab Self-Managed, users with the Guest role are able to perform this action only on public and internal projects (not on private projects). External users must have at least the Reporter role, even if the project is internal. Users with the Guest role on GitLab.com are able to perform this action only on public projects because internal visibility is not available.
2. Users can only view events based on their individual actions. For more details, see the prerequisites.

GitLab Duo

Project permissions for GitLab Duo:

Footnotes

1. Code Suggestions requires a user being assigned a seat to gain access to a GitLab Duo add-on.

Machine learning model registry and experiment

Project permissions for model registry and model experiments.

Footnotes

1. Non-members can only view models and versions in public projects with the Everyone with access visibility level. Non-members can’t view internal projects, even if they’re logged in.
2. Non-members can only view model experiments in public projects with the Everyone with access visibility level. Non-members can’t view internal projects, even if they’re logged in.
3. You can also upload and download artifacts with the package registry API, which uses a different set of permissions.

Monitoring

Project permissions for monitoring including error tracking and incident management:

Project planning

Project permissions for issues:

Footnotes

1. Metadata includes labels, assignees, milestones, epics, weight, confidentiality, time tracking, and more. Guest users can only set metadata when creating an issue. They cannot change the metadata on existing issues. Guest users can modify the title and description of issues that they authored or are assigned to.
2. Guest users can close and reopen issues that they authored or are assigned to.
3. Guest users can archive and reopen issues that they authored or are assigned to.
4. Guest users can modify the title and description that they authored or are assigned to.

Project permissions for tasks:

Footnotes

1. Guest users can modify the title and description that they authored or are assigned to.
2. Users who don’t have the Planner or Owner role can delete the tasks they authored.

Project permissions for OKRs:

Project permissions for wikis:

Packages and registry

Project permissions for container registry:

Footnotes:

1. Viewing the container registry and pulling images is controlled by container registry visibility permissions.

Project permissions for package registry:

Footnotes

1. On GitLab Self-Managed, 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.

Projects

Project permissions for project features:

Footnotes

1. On GitLab Self-Managed, 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. Applies only to comments on Design Management designs.

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

4. If the tag is protected, this depends on the access given to Developers and Maintainers.

5. For GitLab Self-Managed, project access tokens are available in all tiers. For GitLab.com, project access tokens are supported in the Premium and Ultimate tier (excluding trial licenses).

6. A Maintainer or Owner can’t change project features visibility level if project visibility is set to private.

Project permissions for GitLab Pages:

Repository

Project permissions for repository features including source code, branches, push rules, and more:

Footnotes

1. On GitLab Self-Managed, 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. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator (on GitLab Self-Managed or GitLab Dedicated) or group owner (on GitLab.com) gives those users permission. The administrator or group owner can create a custom role through the API or UI and assign that role to the users.
2. On GitLab Self-Managed, 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. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can search private repository content if an administrator (on GitLab Self-Managed or GitLab Dedicated) or group owner (on GitLab.com) gives those users permission. The administrator or group owner can create a custom role through the API or UI and assign that role to the users.
3. On GitLab Self-Managed, 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.
4. If the branch is protected, this depends on the access given to Developers and Maintainers.
5. On GitLab Self-Managed, 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. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator (on GitLab Self-Managed or GitLab Dedicated) or group owner (on GitLab.com) gives those users permission. The administrator or group owner can create a custom role through the API or UI and assign that role to the users.
6. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See protected branches.

Merge requests

Project permissions for merge requests:

Footnotes

1. On GitLab Self-Managed, 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. In projects that accept contributions from external members, users can create, edit, and close their own merge requests. For private projects, this excludes the Guest role as those users cannot clone private projects. For internal projects, includes users with read-only access to the project, as they can clone internal projects.
3. For information on eligible approvers for merge requests, see eligible approvers.

User management

Project permissions for user management.

Footnotes

1. Maintainers cannot create, demote, or remove Owners, and they cannot promote users to the Owner role. They also cannot approve Owner role access requests.
2. When Share Group Lock is enabled the project can’t be shared with other groups. It does not affect group with group sharing.

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

Users with the Minimal Access role do not:

• Automatically have access to projects and subgroups in that top-level group.
• Count as licensed seats on GitLab Self-Managed Ultimate subscriptions or any GitLab.com subscriptions, provided the user has no other role anywhere in the instance or in the GitLab.com namespace.

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

You can use the Minimal Access role with SAML SSO for GitLab.com groups to control access to groups and projects in the group hierarchy. You can set the default role to Minimal Access for members automatically added to the top-level group through SSO.

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > SAML SSO.
3. From the Default membership role dropdown list, select Minimal Access.
4. Select Save changes.

Minimal access users receive 404 errors

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 in the parent group. Guest users consume a license seat in the Premium tier but do not in the Ultimate tier.

Related topics

• Custom roles
• 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