GitLab protected branches, approvals and code owners
A GitLab project is only as safe as its default branch. Maintainers control it with four related features: protected branches decide who can push, merge, force push or delete; merge request approvals decide how many people, and which, must approve; Code Owners route changes in sensitive paths to the experts; and description templates make every merge request and issue arrive with the information reviewers need. Together they turn “please don’t push to main” into rules GitLab enforces.
The examples configure an invented OrdersPortal project in an orders group. UI paths, tiers and defaults were checked against the GitLab documentation source in November 2026 (GitLab 19.x). Recent versions are moving protected branch settings into Settings > Repository > Branch rules; older instances show a Protected branches section on the same page with the same options. Tier notes matter here: protected branches and optional approvals are in every tier, while required approval rules and Code Owners need Premium or Ultimate.
Topics on this page
Section titled “Topics on this page”| Topic | Answers |
|---|---|
| Create and protect a branch | How to create a branch and protect it by name or wildcard. |
| Protected branch permissions | Who may push, merge, force push and unprotect. |
| Merge request approvals | How many approvals, from whom, and what resets them. |
| Code Owners | Who must approve changes to which paths. |
| Merge request and issue templates | What contributors are asked for. |
Create and protect a branch
Section titled “Create and protect a branch”Create a branch from Code > Branches > New branch (pick the name and the branch, tag or commit to start from), from an issue, or from the command line with git switch -c and git push -u. To protect it, go to Settings > Repository, expand Branch rules, select Add branch rule > Branch name or pattern, choose the branch or type a wildcard, and select Create branch rule. On the rule details page you set Allowed to merge, Allowed to push and merge, force push and Code Owner approval. You need the Maintainer or Owner role (or a custom role with admin_protected_branch).
Wildcards protect families of branches at once and are case-sensitive: release/* matches release/2.4 and release/2.5, *-stable matches production-stable. When several rules match a branch, GitLab applies the most permissive result for most settings, so be deliberate when mixing exact and wildcard rules. The default branch is protected automatically when a project is created; administrators set that default protection level for the instance.
On Premium and Ultimate, group Owners of a top-level group can define protected branches for every project in the group (Group > Settings > Repository > Protected branches); projects cannot loosen a group rule but can add their own.
git switch -c release/2.5 origin/maingit push -u origin release/2.5# then protect release/* once, so every future release branch is coveredPitfalls:
- Protect the pattern before the branch exists. A rule for
release/*coversrelease/2.5from its first push; protecting each branch by hand leaves a window. - Protect tags too. Git lets a tag and a branch share a name. GitLab recommends protecting the same names or patterns for tags so nobody can create an unprotected tag called
release/2.5. - Creating protected branches can be restricted. When “require merge requests” applies, new protected branches can only be created from existing protected branches or commits already in them.
Protected branch permissions
Section titled “Protected branch permissions”Two settings do most of the work. Allowed to merge controls who can merge merge requests into the branch (and create new protected branches through the UI or API). Allowed to push and merge controls who can push directly, and also grants merge. Clearing every role on a setting means nobody can do it. When you create a new branch rule, GitLab selects Maintainers for push and merge; to force all changes through merge requests, set Allowed to push and merge to No one.
GitLab’s documentation recommends, for production branches: Allowed to merge set to Maintainers, Allowed to push and merge set to No one, and Code Owner approval required. For active development branches: merge allowed for Developers and Maintainers, push for No one. Protected branches also reject force pushes unless Allowed to force push is turned on, cannot be deleted with git push, and limit who can run pipelines with protected CI/CD variables and runners, because pipeline permissions follow push and merge permissions.
| Allowed to merge | Allowed to push and merge | A Developer can push directly | A Developer can merge an MR |
|---|---|---|---|
| Developers + Maintainers | No one | No | Yes |
| Maintainers | No one | No | No |
| No one | Developers + Maintainers | Yes | Yes |
On Premium and Ultimate you can add specific users or groups (and deploy keys for push) instead of roles, and restrict who can unprotect a branch.
Pitfalls:
- Allowing push silently allows merge. “Allowed to push and merge” includes merging, even if “Allowed to merge” is narrower.
- Deploy keys need explicit push access. A CI deploy key that pushes version bumps to
mainmust be added to Allowed to push and merge; prefer merge requests from a bot account where possible. - Delete protected branches in the UI only. Maintainers can delete a protected branch from Code > Branches after typing its name; Git clients cannot.
Merge request approvals
Section titled “Merge request approvals”Approvals record that someone reviewed a change. In GitLab Free, any user with at least the Developer role can approve, but approvals are optional and do not block merging. Premium and Ultimate add approval rules: under Settings > Merge requests > Merge request approvals, select Add approval rule, set Approvals required (0 makes the rule optional, up to 100), and choose eligible users or groups. Rules can target protected branches only, several rules can apply at once (for example Backend and Security), and GitLab suggests approvers from the history of the changed files.
Approval settings close common loopholes. By default the MR author cannot approve their own MR. You can also prevent approvals by users who added commits, prevent editing approval rules in individual MRs, require re-authentication to approve, and remove all approvals (or only Code Owner approvals for changed files) when new commits are pushed. Fork MRs use the upstream project’s rules.
OrdersPortal approval setup (Premium)Rule "Backend" : 1 approval from group orders/backend (target: protected branches)Rule "Security" : 1 approval from group orders/security (target: main)Settings : prevent author approval, prevent committer approval, prevent editing rules in MRs, remove approvals when commits are addedCode Owners : required on main (see next section)Pitfalls:
- Free tier approvals are advisory. Without Premium, protect the branch so only Maintainers can merge and treat review as a process rule.
- Overridable rules are weak rules. If authors can edit approval rules in their MR, they can set required approvals to zero; disable overrides for regulated projects.
- Group approvers need visibility. On GitLab.com you can add a group as approvers only if you are a member or the group is public.
Code Owners
Section titled “Code Owners”A CODEOWNERS file lists which users, groups or roles own which paths. GitLab shows owners on files and directories, and when Code owner approval is turned on for a protected branch, MRs into that branch that touch owned files need an approval from an owner of each affected section. GitLab compares the changed files with the CODEOWNERS file on the target branch. The file is read from the first of ./CODEOWNERS, ./docs/CODEOWNERS or ./.gitlab/CODEOWNERS that exists. Code Owners requires Premium or Ultimate.
Patterns follow .gitignore-like rules: a leading / anchors to the repository root, a trailing / matches a directory and everything in it, and within a section the last matching line wins. Sections ([Name]) are evaluated separately, so one change can need an approval from each section it touches; ^[Name] makes a section optional, and [Name][2] requires two approvals from that section’s owners.
# .gitlab/CODEOWNERS for OrdersPortal* @orders/maintainers
[Backend]/src/ @orders/backend
[Payments][2]/src/payments/ @orders/payments-leads
[Security]/src/auth/ @orders/security/.gitlab-ci.yml @orders/platform
^[Documentation]/docs/ @orders/tech-writersCombine Code Owners (expertise by path) with approval rules (expertise that is not tied to a path, such as security or UX review across all files).
Pitfalls:
- No protection, no enforcement. Owners are shown, but approval is only required when the target branch is protected with Code Owner approval enabled.
- Own the CODEOWNERS file itself. Otherwise a change to ownership can be approved by the person removing themselves.
- Owners need access. Users and groups that are not members of the project, or lack the right role, are not eligible approvers, which can make an MR impossible to merge.
Merge request and issue templates
Section titled “Merge request and issue templates”Description templates are Markdown files committed to the default branch: merge request templates in .gitlab/merge_request_templates/ and issue templates in .gitlab/issue_templates/. Contributors choose one from a dropdown when creating an MR or issue. A file named Default.md is used as the default; on Premium and Ultimate you can instead set the default text in project settings (Settings > Merge requests for MRs, Settings > General for issues), which takes priority. Groups can share templates through a template project.
Default MR templates support variables that GitLab fills in on first save, such as %{source_branch}, %{target_branch}, %{first_multiline_commit}, %{all_commits} and %{closes_issue}. Quick actions such as /label ~checkout and /assign me also run from templates when the author has permission.
## What and why%{first_multiline_commit}
%{closes_issue}
## How to test- [ ] Unit tests pass (`npm test`)- [ ] Checked in the review app
## Risk- [ ] Database migration- [ ] Touches payments or auth (Code Owner approval required)
/label ~"needs-review"Pitfalls:
- Templates must be on the default branch. A template added on a feature branch does not appear until it is merged.
- Templates guide, they do not enforce. Pair them with approval rules or a CI check (for example, a Jira key in the title) for anything mandatory.
Choosing between them
Section titled “Choosing between them”| Goal | Feature | Tier |
|---|---|---|
Nobody pushes directly to main |
Protected branch with push set to No one | All |
| A minimum number of reviews | Approval rules | Premium, Ultimate |
| Expert review on sensitive paths | Code Owners plus Code Owner approval | Premium, Ultimate |
| Consistent MR and issue descriptions | Description templates | All (default text in settings: Premium, Ultimate) |
| Branch names, commit messages, secrets | Push rules | Premium, Ultimate |
Interview questions
Section titled “Interview questions”What is the difference between “Allowed to merge” and “Allowed to push and merge”? “Allowed to merge” lets users merge MRs into the protected branch. “Allowed to push and merge” lets users push commits directly and also merge. Setting push to No one forces all changes through merge requests.
What happens when several protected branch rules match one branch? GitLab evaluates all matching rules and, for most settings, the most permissive result applies. Code Owner approval is required if any matching rule requires it.
Where does GitLab look for CODEOWNERS, and which version is used for an MR?
The first of the root, docs/ and .gitlab/ locations. For an MR, GitLab uses the file on the target branch, so an MR cannot change its own required owners.
How do sections change Code Owner approvals?
Each section is evaluated separately, so a change touching paths in two sections needs an approval from each. ^ makes a section optional, and [Section][n] requires n approvals.
Senior scenario: an auditor asks you to prove that every change to payments code in the last quarter was reviewed by two payments experts. How do you set this up going forward and evidence it?
Protect main with push set to No one and Code Owner approval on; add a [Payments][2] section owning /src/payments/; disable approval rule editing in MRs, prevent author and committer approval, and remove approvals on new commits. Use group-level protected branches for consistency across projects. For evidence, MR approval records and the audit events (Premium and Ultimate) show who approved what; export them periodically.
Related pages
Section titled “Related pages”- GitLab administration guides
- Contributor basics: opening the merge requests these rules govern.
- Push rules and server hooks: branch names, commit messages and secrets at push time.
- GitLab Merge Train
- GitHub repository governance: the GitHub equivalents.