Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Security and Compliance

Roles, Permissions and Protected Branches

Understand GitLab roles from Guest to Owner, how permissions are inherited, and how protected branches, protected tags, push rules and CODEOWNERS guard your code.

Security in GitLab starts with a simple question: who may do what? A new hire, a contractor and a release manager should not all have the same power. GitLab answers with roles assigned to users on a project or group, and with protection rules on branches and tags that keep even trusted people from damaging important code by accident.

This lesson covers the role ladder, inheritance through groups, protected branches and tags, push rules and CODEOWNERS. The settings are described by menu name because GitLab cannot run on this site; the examples are JavaScript models of the decisions.

The role ladder

Every member has one role per project or group. From least to most powerful:

Role Typical use Can do (summary)
Minimal Access Group member who should see nothing by default (Premium) No project access unless granted
Guest Stakeholders, customers View and comment on issues; cannot read private code (private projects)
Planner Project managers (newer versions) Manage issues, epics and plans, without code access beyond reading
Reporter Testers, analysts Read code, create issues, download artifacts
Developer Engineers Push to non-protected branches, create merge requests, run pipelines
Maintainer Tech leads Manage branches, runners, settings, merge to protected branches
Owner Group or project owner Everything, including deleting the project and managing the group

The exact permission table is long and changes with versions, so treat the official permissions page of your GitLab version as the source of truth. Two principles hold everywhere: give the lowest role that does the job and prefer groups over individual grants.

Inheritance through groups

Projects live inside groups, and groups can have subgroups. A member of a group inherits the same role in every project below it. If someone is Developer on company and Reporter on company/payments/api, GitLab uses the highest of the roles (Developer); you cannot lower an inherited role, only raise it. So give broad groups only the lowest access everybody needs, and add higher roles at the lower level where they are needed. The structure of groups is the subject of Groups, Subgroups and Governance.

flowchart TD
  G["group: company (Ana = Reporter)"] --> S["subgroup: payments"]
  S --> P1["project: api (Ana = Developer, set here)"]
  S --> P2["project: docs (Ana = Reporter, inherited)"]

A role set higher up flows down; a higher role set lower down wins.

Protected branches

By default the default branch (usually main) is protected. In Settings > Repository > Protected branches you decide, per branch or wildcard such as release/*:

  • Allowed to merge: roles that may merge a merge request into the branch.
  • Allowed to push and merge: roles or users that may push directly. "No one" forces all changes through merge requests.
  • Allowed to force push: almost always off, since it rewrites history.
  • Code owner approval: require approval from the owners of the changed files.

A protected branch also cannot be deleted by normal members. Typical safe setup: allowed to merge = Developers and Maintainers, allowed to push = No one, force push off. Then every change to main is a reviewed merge request, and the pipeline runs before the merge.

Protection also connects to CI: protected variables are only given to pipelines running on protected branches and tags, which is how a production key stays away from experimental branches (see CI Variables and Secrets Security).

Protected tags

Tags often trigger releases, so GitLab can protect them too. In Settings > Repository > Protected tags set a pattern such as v* and choose who may create tags matching it. Without protection, any Developer could create v9.9.9 and start a release pipeline. With protection, only Maintainers can.

Merge request approvals and CODEOWNERS

Branch protection says where changes go; approval rules say who must agree. A project can require, for example, two approvals, one of them from a security group. A CODEOWNERS file (in the repository root, docs/ or .gitlab/) maps paths to people or groups:

TEXT
# CODEOWNERS
[Backend]
/app/ @backend-team
/db/migrations/ @dba-team @backend-leads

[Security]
/.gitlab-ci.yml @security-team
/deploy/ @platform-team

With "code owner approval" enabled on the protected branch, a merge request that touches /.gitlab-ci.yml needs a security-team approval. This is an excellent guard because the pipeline file decides what code runs with your secrets.

Push rules

Premium push rules check commits as they arrive: a commit message must match a regular expression (for example reference an issue), the author e-mail must belong to the company domain, certain file names such as *.pem are forbidden, and files over a size limit are refused. They are the earliest defense against secrets reaching the repository. They do not replace scanning (see Security Scanning).

Stand-in: who can push?

The first example evaluates a push and a merge against protection settings, in the order GitLab thinks about them.

JS Protected branch check

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example resolves inherited roles: the highest role found between a project and its parent groups wins.

JS Role inheritance

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Ana is Reporter on a group and Developer on one project inside it. What is her role in that project?

    GitLab uses the highest role that applies. A lower role set on a subgroup or project cannot reduce an inherited higher one.
  2. 2. Which protected-branch setup forces every change to main through a merge request?

    With pushing disabled, the only way into the branch is a merge, and merges can require pipelines and approvals.
  3. 3. Why protect tags such as v*?

    An unprotected tag pattern lets any Developer start a release pipeline that may hold deployment credentials.
  4. 4. What does a CODEOWNERS entry for /.gitlab-ci.yml achieve?

    The pipeline file controls what runs with your secrets, so having a trusted team approve changes to it is a strong safeguard.

Summary

  • Roles run from Minimal Access, Guest, Planner and Reporter through Developer and Maintainer to Owner; give the lowest role that works.
  • Roles flow down from groups to projects and the highest role wins.
  • Protected branches and tags control who pushes, merges and creates releases; protected variables follow the same protection.
  • Approval rules, CODEOWNERS and push rules add review and early checks.

Next: CI Variables and Secrets Security