Lesson 7: Roles and Permissions#
Everything in the previous lessons — who can dismiss a vulnerability, who can change a security policy, who can apply a compliance framework — comes down to roles and permissions. A solid DevSecOps program runs on the principle of least privilege: every person gets exactly the access their job needs, and no more. This is also the foundation of separation of duties — the idea that the people who write code should not be the same people who approve the security gates around it.
GitLab gives you two levers for this: a set of built-in default roles, and custom roles that let you grant a single, specific capability without handing over a broad role.
This lesson covers:
- How GitLab roles work
- Default roles and the permission hierarchy
- Security-relevant permissions by role
- The Security Manager role
- Why custom roles
- Creating a custom security role
- Assigning a custom role
- Security and compliance custom permissions reference
How GitLab roles work#
A role is a named bundle of permissions. You assign a role to a member at the group or project level, and it determines what actions that member can take. Roles assigned higher in the hierarchy (a top-level group) cascade down to the subgroups and projects beneath them.
GitLab offers two kinds of roles:
- Default roles — the built-in roles every GitLab instance ships with (Guest, Reporter, Developer, and so on). Simple, but coarse-grained: each is a fixed bundle.
- Custom roles — a default role used as a base, plus one or more added permissions you select. This lets you grant a narrow capability (for example, “manage vulnerabilities”) without granting everything a higher default role would include.
The rest of this lesson works through both, with an emphasis on the security and compliance capabilities you set up in Lessons 2–6.
Default roles and the permission hierarchy#
GitLab’s default roles, ordered roughly from least to most privileged:
| Role | What it’s for |
|---|---|
| Minimal Access | View limited group information without access to projects (Premium/Ultimate) |
| Guest | View and comment on issues and epics; cannot push code or access the repository |
| Planner | Create and manage issues, epics, milestones, and iterations |
| Reporter | View code, create issues, and generate reports; cannot push code |
| Security Manager | View and manage security vulnerabilities, compliance configurations, and audit events — without code push access |
| Developer | Push code to non-protected branches, create merge requests, and run CI/CD pipelines |
| Maintainer | Manage branches, merge requests, CI/CD settings, security policies, and project members |
| Owner | Full control over the project or group, including deletion and visibility settings |
The Security Manager role is not a simple rung on this ladder — it is a specialized security-operations role positioned conceptually between Reporter and Developer, but deliberately without code-push access. We cover it in its own section below.
Security-relevant permissions by role#
When designing access for a DevSecOps team, these are the capabilities that matter most and the lowest default role that has each one:
| Capability | Lowest default role with access |
|---|---|
| View the vulnerability report | Reporter |
| Run on-demand DAST scans | Developer |
| Create or assign a security policy project | Maintainer |
| Manage (create/edit/apply) compliance frameworks | Maintainer |
| View audit events | Reporter |
| Manage audit events / audit event streams | Maintainer |
This table reveals the core tension: a security analyst whose job is to triage vulnerabilities needs more than Reporter (which can view but not change vulnerability status), but giving them Developer or Maintainer hands over code-push and configuration rights they don’t need. That gap is exactly what the Security Manager role and custom roles exist to close.
The Security Manager role#
The Security Manager default role is built for exactly the security-operations use case above. It can:
- View and manage security vulnerabilities (triage, change status, link issues)
- View and manage compliance configurations
- View and manage audit events
…all without the ability to push code. It’s the out-of-the-box answer for an AppSec engineer who triages findings and owns compliance posture but should not be merging application code.
The Security Manager role is available on Free, Premium, and Ultimate. It was introduced as a Beta in GitLab 18.11 — as with any beta feature, confirm its exact capabilities on your instance before relying on it for a compliance control.
To assign it, follow the same steps as any default role: Manage > Members, select the member’s current role, and choose Security Manager.
Why custom roles#
The Security Manager role covers a common pattern, but real organizations have needs it doesn’t match exactly. Maybe you want someone who can only triage vulnerabilities — nothing else. Or a contractor who can read your dependency list but see nothing else. Default roles can’t express that; custom roles can.
A custom role is a base default role + added permissions:
- The base role sets the floor — the minimum the role can do.
- You then add specific permissions on top, drawn from a catalog of fine-grained abilities.
For example, a custom role with a Reporter base plus the admin_vulnerability permission produces a “security analyst” who can view code and triage vulnerabilities (change status, severity, linked issues) — but still cannot push code, change CI/CD settings, or manage members. That is least privilege in action.
Custom roles require GitLab Ultimate. On GitLab.com they are created at the top-level group level by a group Owner; on GitLab Self-Managed and Dedicated they are created instance-wide by an administrator. There is a limit of 10 custom roles per group (GitLab.com) or per instance (Self-Managed).
Creating a custom security role#
Let’s create the “Security Analyst” role described above — a Reporter who can triage vulnerabilities.
Prerequisites: the Owner role on your top-level group (GitLab.com), GitLab Ultimate, and fewer than 10 existing custom roles.
On the top bar, select Search or go to and find your group
Select Settings > Roles and permissions
Select New role
Enter a Name (
Security Analyst) and a Description (Reporter who can triage and manage vulnerabilities without code access)From the Base role dropdown, select Reporter
The base role cannot be changed after the role is created. If you need a different base later, create a new role.
- Select the permissions to add. For a triage-focused analyst, enable:
read_vulnerability— read vulnerability reports and security dashboardsadmin_vulnerability— change the status, severity, and linked issue of a vulnerability (requiresread_vulnerability)read_dependency— read the dependency list and licenses (optional, but useful for triage)
- Select Create role
The role now appears in your group’s list of roles and is ready to assign.
On GitLab Self-Managed and Dedicated, the path is Admin > Settings > Roles and permissions > New role > Member role, then the same name/base/permissions steps. Self-managed instances can also create Admin roles for fine-grained administrative access — these are not available on GitLab.com.
Assigning a custom role#
A custom role is assigned exactly like a default role, from the member list:
On the top bar, select Search or go to and find your group or project
Select Manage > Members
In the Role column, select the member’s current role
From the Role dropdown, choose your Security Analyst custom role
Select Update role
The member now has Reporter access plus vulnerability management — and nothing more. They can work through the vulnerability report from Lesson 4, change statuses, and link issues, without ever being able to push to the repository.
A custom role cannot be deleted while it is still assigned to any member. Reassign affected members to a different role first, then delete the custom role.
Security and compliance custom permissions reference#
Custom roles draw from a large catalog of abilities that grows with most GitLab releases. The permissions most relevant to the DevSecOps workflows in this tutorial are:
| Permission | What it grants |
|---|---|
read_vulnerability | Read vulnerability reports and security dashboards |
admin_vulnerability | Edit status, severity, and linked issue of a vulnerability (requires read_vulnerability) |
read_dependency | Read-only access to dependencies and licenses |
manage_security_policy_link | Link security policy projects (the policies from Lesson 2) |
read_security_scan_profiles | Read the security scan/configuration profiles from Lesson 2 |
apply_security_scan_profiles | Apply security configuration profiles to projects |
read_security_attribute / admin_security_attributes | Read and manage security categories and attributes |
admin_compliance_framework | Create, read, update, and delete compliance frameworks and assign framework labels (the work from Lesson 6) |
read_compliance_dashboard | Read compliance adherence, violations, and frameworks |
update_sec_ai_workflow_settings | Update security AI workflow settings, such as SAST vulnerability resolution (Lesson 5) |
Mix and match these on top of a base role to build precisely the access a person needs. A few common DevSecOps patterns:
- Vulnerability triager — Reporter +
read_vulnerability+admin_vulnerability - Compliance manager — Reporter +
admin_compliance_framework+read_compliance_dashboard(so they can run Lesson 6’s frameworks without Maintainer access) - Read-only auditor — Guest +
read_vulnerability+read_dependency+read_compliance_dashboard
The available custom permissions change frequently. Always check the custom permissions reference for the current list and the exact GitLab version each permission was introduced in.
You now understand how GitLab roles map to the DevSecOps responsibilities from the rest of this tutorial — and how to enforce least privilege and separation of duties with both the built-in Security Manager role and purpose-built custom roles.
This completes the Tanuki Shop DevSecOps tutorial. You have learned to configure scanners and policies, work through the developer and AppSec security workflows, accelerate triage and remediation with GitLab Duo, bundle it all into compliance frameworks, and control who can do what with roles and permissions.
To learn more about GitLab and the value it can bring to your organization, visit https://about.gitlab.com/.