GitLab Roles – How to define Permissions

If you’re working with GitLab, you’ve probably noticed that managing who can do what gets complicated fast. This post walks through the built-in roles GitLab gives you, what each one actually lets users do, and how to use Groups to keep permissions manageable at scale.

One thing worth knowing upfront: everything here applies across all GitLab tiers, including the free ones.

The Role Hierarchy

GitLab ships with seven predefined roles, ordered by increasing privilege:

1. Minimal Access
2. Guest
3. Planner
4. Reporter
5. Developer
6. Maintainer
7. Owner

I’ll skip Minimal Access since it’s rarely used in practice, but the rest are worth understanding.

Guest

Guests have the lowest privilege level. They can view issues they’ve created or been assigned to, but that’s about it. They can’t see code, run pipelines, or interact with merge requests.

Reporter

Reporters get read-only access to the project. They can view code, download artifacts, comment on issues and commits, and create milestones. They still can’t run CI/CD jobs or push any changes.

Developer

This is where things get more interesting. Developers can push code, create branches and tags, run CI/CD pipelines, and manage merge requests (submit, review, approve). They can also handle CI/CD variables in most cases. What they can’t do is change project-level settings or invite new members.

Maintainer

Maintainers do just about everything with a project except delete it. On top of what developers can do, they can assign members, manage GitLab Pages, handle cluster integrations, and rename the project itself.

Owner

When you create a project, your account automatically gets the Owner role for that project. Owners have full access: they can delete the project, transfer it to another user, change visibility settings, and manage all member roles. It’s the highest level of project-level access.

There’s one quirk worth knowing: if you’re an Owner and want to stop being a member while keeping the project alive, you can do that. Go to the Members section of your project and look for the “Leave project” option. It’s the red button in the interface.

Administrator

The Administrator role sits above everything else I’ve described so far, but it’s not managed at the project or group level. Administrators have server-wide access on self-managed GitLab instances. They can clone any project, create or delete any project, manage user accounts, configure runners, and change any setting across the entire instance.

To assign the Administrator role to a user, you need to already be an Administrator yourself. Edit the user account and look for the “Access” section. You’ll see options there to change their role level.

Using Groups to Manage Permissions at Scale

Here’s where things get practical. If you’re managing thousands of projects and need consistent permissions across hundreds of developers, Groups are your friend.

Instead of assigning permissions project-by-project, you create a Group for each team. Developers go in the Developers Group, operations staff go in the Operations Group, and so on. When you add a group as a member to a project, everyone in that group inherits the same access level automatically.

This matters because GitLab applies the highest permission level when a user has membership in both a project and its parent groups. Give a user direct access to a subgroup, and that access can actually override lower access granted at a higher level.

The real win is that when you need to add a new developer, you add them to the group once and they’re set across every project that group has access to. No hunting through dozens of project settings.

One thing to keep in mind: when you create a group, it doesn’t have to contain any projects. Groups are just containers for users. You can create a group with zero projects and use it purely to manage who has access to what.

How Inheritance Works

GitLab follows a straightforward inheritance model: permissions flow downward from parent groups to subgroups and projects. If you grant a user access at the group level, that access cascades down to everything inside. But here’s the catch I mentioned earlier — if you grant someone direct access at a lower level in the hierarchy, you can’t easily reduce their privileges at higher levels. The higher permission wins.

For example, if you add a user directly to a subgroup with Developer access, but their parent group only has Guest access, GitLab will give them the higher level (Developer) across the board. Plan your group structure before you start adding people, because unravelling mixed permissions later is tedious.

For more on GitLab permissions, check the official docs at https://docs.gitlab.com.