This document explains how a team gets approval and merge rights over a subtree of this repository without being granted the Maintainer role on the whole project.
The three layers
Approval, merging, and administration are separate controls. Keeping them separate is what lets a domain team own its own paths while the CLI maintainers keep the project settings.
The Maintainer role is only needed for the third layer. A team that wants to review and ship changes to its own paths needs the Developer role, a CODEOWNERS entry, and an Allowed to merge entry.
Behavior to understand before you change anything
A merge access entry is not path-scoped. Anyone in Allowed to merge can merge any merge request that targets main, not only the paths they own. The approval requirement is what keeps changes scoped, because an unapproved merge request cannot be merged by anyone.
.gitlab/CODEOWNERS is a single section, so a file matches exactly one pattern, and one approval from any owner listed on that pattern satisfies the requirement. Listing a domain team next to the maintainers means either can approve, not both.
A later pattern replaces the owners of an earlier one rather than adding to them. Every pattern repeats the maintainers, and every documentation pattern also repeats @gl-docsteam.
An inherited role cannot be lowered at the project level. Members who hold a role through the gitlab-org group keep it regardless of what is configured here.
An invited group grants each member the lower of their role in that group and the level the group was invited at. Inviting a group at Developer does not promote anyone. When auditing, remember that the members/all endpoint for a group also lists people who inherit into it from a parent group, so it overstates who the invite actually covers.
Approvals are recomputed when owned files change, because selective_code_owner_removals is enabled. Pushing a change to an owned file drops that owner's approval and keeps the others.
Documentation subtrees for a delegated area list @gl-docsteam as well as the owning team, so a documentation-only change does not need the owning team.
Delegate a path to a team
Prefer a group over a list of usernames. A group keeps CODEOWNERS short, and membership is then managed by the team instead of by a CLI maintainer.
Prerequisites
The Maintainer role on gitlab-org/cli.
The Maintainer or Owner role in the group you are inviting. This is a property of the invited group, not of gitlab-org. Without it, the invite returns 404 Not Found.
Steps
Invite the group to the project with the Developer role. A group can only be used in CODEOWNERS or in a protected branch rule after it has been invited, unless it is an ancestor of the project. A sibling subgroup under gitlab-org is not an ancestor.
shell
glab api --method POST "projects/gitlab-org%2Fcli/share" \
-f group_id=<GROUP_ID> -f group_access=30
Add the CODEOWNERS entries. Repeat the maintainers on every line, and add @gl-docsteam on documentation lines.
4info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/marketing/product-and-technical-marketing/technical-writing/#assignments>
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.