Custom permissions

You can create a custom role by adding one or more custom permissions to a base role.

Some permissions depend on other permissions. For example, the admin_vulnerability permission requires you to also include the read_vulnerability permission. Any dependencies are noted in the Description column for each permission.

Code review workflow

PermissionDescriptionAPI AttributeScopeIntroduced
Manage merge request approvals and settingsConfigure 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.manage_merge_request_settingsGroup,
Project
GitLab 17.0

Compliance management

PermissionDescriptionAPI AttributeScopeIntroduced
Manage and assign compliance frameworksCreate, 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.admin_compliance_frameworkGroup,
Project
GitLab 17.0
Read compliance dashboardRead compliance capabilities including adherence, violations, and frameworks for groups and projects.read_compliance_dashboardGroup,
Project
GitLab 17.7

Continuous delivery

PermissionDescriptionAPI AttributeScopeIntroduced
Manage deploy tokensManage deploy tokens at the group or project level.manage_deploy_tokensGroup,
Project
GitLab 17.0

Groups and projects

PermissionDescriptionAPI AttributeScopeIntroduced
Archive projectAllows archiving of projects.archive_projectProjectGitLab 16.6
Delete groupAbility to delete or restore a group. This ability does not allow deleting top-level groups. Review the Retention period settings to prevent accidental deletion.remove_groupGroupGitLab 16.10
Delete projectAllows deletion of projects.remove_projectProjectGitLab 16.8
Manage group membersAdd 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.admin_group_memberGroupGitLab 16.5

Infrastructure as code

PermissionDescriptionAPI AttributeScopeIntroduced
Manage Terraform stateExecute terraform commands, lock/unlock terraform state files, and remove file versions.admin_terraform_stateProjectGitLab 16.8

Integrations

PermissionDescriptionAPI AttributeScopeIntroduced
Manage integrationsCreate, read, update, and delete integrations with external applications.admin_integrationsGroup,
Project
GitLab 17.1

Runner

PermissionDescriptionAPI AttributeScopeIntroduced
Manage runnersCreate, view, edit, and delete group or project Runners. Includes configuring Runner settings.admin_runnersGroup,
Project
GitLab 17.1
View runnersAllows read-only access to group or project runners, including the runner fleet dashboard.read_runnersGroup,
Project
GitLab 17.2

Secrets management

PermissionDescriptionAPI AttributeScopeIntroduced
Manage CI/CD variablesCreate, read, update, and delete CI/CD variables.admin_cicd_variablesGroup,
Project
GitLab 16.10

Security policy management

PermissionDescriptionAPI AttributeScopeIntroduced
Link to a security policy projectAllows linking security policy projects.manage_security_policy_linkGroup,
Project
GitLab 16.11

Source code management

PermissionDescriptionAPI AttributeScopeIntroduced
Approve merge requestAllows approval of merge requests.admin_merge_requestProjectGitLab 16.4
Manage Protected BranchesCreate, read, update, and delete protected branches for a project.admin_protected_branchProjectGitLab 17.4
Manage push rulesConfigure push rules for repositories at the group or project level.admin_push_rulesGroup,
Project
GitLab 16.11
View repository codeAllows 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.read_codeGroup,
Project
GitLab 15.7

System access

PermissionDescriptionAPI AttributeScopeIntroduced
Manage group access tokensCreate, 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.manage_group_access_tokensGroupGitLab 16.8
Manage project access tokensCreate, 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.manage_project_access_tokensProjectGitLab 16.5

Team planning

PermissionDescriptionAPI AttributeScopeIntroduced
View CRM contactRead CRM contact.read_crm_contactGroupGitLab 17.1

Vulnerability management

PermissionDescriptionAPI AttributeScopeIntroduced
Manage vulnerabilitiesEdit the vulnerability object, including the status and linking an issue. Includes the read_vulnerability permission actions.admin_vulnerabilityGroup,
Project
GitLab 16.1
View dependency listAllows read-only access to the dependencies and licenses.read_dependencyGroup,
Project
GitLab 16.3
View vulnerability reports and dashboardsRead vulnerability reports and security dashboards.read_vulnerabilityGroup,
Project
GitLab 16.1

Webhooks

PermissionDescriptionAPI AttributeScopeIntroduced
Manage web hooksManage webhooksadmin_web_hookGroup,
Project
GitLab 17.0