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

Admin

Name Required permission Description Introduced in Feature flag Enabled in
read_admin_dashboard   Read-only access to admin dashboard GitLab 17.6    

Code review workflow

Name Required permission Description Introduced in Feature flag Enabled in
manage_merge_request_settings   Configure merge request settings at the group or project level. Group actions include managing merge checks and approval settings. Project actions include managing MR configurations, approval rules and settings, and branch targets. In order to enable Suggested reviewers, the “Manage project access tokens” custom permission needs to be enabled. GitLab 17.0    

Compliance management

Name Required permission Description Introduced in Feature flag Enabled in
admin_compliance_framework   Create, read, update, and delete compliance frameworks. Users with this permission can also assign a compliance framework label to a project, and set the default framework of a group. GitLab 17.0    
read_compliance_dashboard   Read compliance capabilities including adherence, violations, and frameworks for groups and projects. GitLab 17.7    

Continuous delivery

Name Required permission Description Introduced in Feature flag Enabled in
manage_deploy_tokens   Manage deploy tokens at the group or project level. GitLab 17.0    

Groups and projects

Name Required permission Description Introduced in Feature flag Enabled in
admin_group_member   Add or remove users in a group, and assign roles to users. When assigning a role, users with this custom permission must select a role that has the same or fewer permissions as the default role used as the base for their custom role. GitLab 16.5 admin_group_member GitLab 16.6
archive_project   Allows archiving of projects. GitLab 16.6 archive_project GitLab 16.7
remove_group   Ability to delete or restore a group. This ability does not allow deleting top-level groups. Review the Retention period settings to prevent accidental deletion. GitLab 16.10    
remove_project   Allows deletion of projects. GitLab 16.8    

Infrastructure as code

Name Required permission Description Introduced in Feature flag Enabled in
admin_terraform_state   Execute terraform commands, lock/unlock terraform state files, and remove file versions. GitLab 16.8    

Integrations

Name Required permission Description Introduced in Feature flag Enabled in
admin_integrations   Create, read, update, and delete integrations with external applications. GitLab 17.1    

Runner

Name Required permission Description Introduced in Feature flag Enabled in
admin_runners   Create, view, edit, and delete group or project Runners. Includes configuring Runner settings. GitLab 17.1    
read_runners   Allows read-only access to group or project runners, including the runner fleet dashboard. GitLab 17.2    

Secrets management

Name Required permission Description Introduced in Feature flag Enabled in
admin_cicd_variables   Create, read, update, and delete CI/CD variables. GitLab 16.10    

Security policy management

Name Required permission Description Introduced in Feature flag Enabled in
manage_security_policy_link   Allows linking security policy projects. GitLab 16.11    

Source code management

Name Required permission Description Introduced in Feature flag Enabled in
admin_merge_request   Allows approval of merge requests. GitLab 16.4    
admin_protected_branch   Create, read, update, and delete protected branches for a project. GitLab 17.4    
admin_push_rules   Configure push rules for repositories at the group or project level. GitLab 16.11    
read_code   Allows read-only access to the source code in the user interface. Does not allow users to edit or download repository archives, clone or pull repositories, view source code in an IDE, or view merge requests for private projects. You can download individual files because read-only access inherently grants the ability to make a local copy of the file. GitLab 15.7 customizable_roles GitLab 15.9

System access

Name Required permission Description Introduced in Feature flag Enabled in
manage_group_access_tokens   Create, read, update, and delete group access tokens. When creating a token, users with this custom permission must select a role for that token that has the same or fewer permissions as the default role used as the base for the custom role. GitLab 16.8    
manage_project_access_tokens   Create, read, update, and delete project access tokens. When creating a token, users with this custom permission must select a role for that token that has the same or fewer permissions as the default role used as the base for the custom role. GitLab 16.5 manage_project_access_tokens GitLab 16.8

Team planning

Name Required permission Description Introduced in Feature flag Enabled in
read_crm_contact   Read CRM contact. GitLab 17.1    

Vulnerability management

Name Required permission Description Introduced in Feature flag Enabled in
admin_vulnerability   Edit the vulnerability object, including the status and linking an issue. Includes the read_vulnerability permission actions. GitLab 16.1    
read_dependency   Allows read-only access to the dependencies and licenses. GitLab 16.3    
read_vulnerability   Read vulnerability reports and security dashboards. GitLab 16.1    

Webhooks

Name Required permission Description Introduced in Feature flag Enabled in
admin_web_hook   Manage webhooks GitLab 17.0