Delegate path ownership in the GitLab CLI
Grant a team approval rights over its paths and the ability to merge, while the CLI maintainers keep project administration.
Background and the reasoning behind the model: docs/path_ownership.md.
Inputs
Collect these before starting. Ask only for what is missing.
- Group path such as
gitlab-org/orbit/team, or a list of usernames when the team has no group. Prefer a group. - Paths to delegate, such as
internal/commands/orbit. Ask whether the matchingdocs/source/<area>/subtree is included. It usually is.
The model
Three independent controls. Only the third needs the Maintainer role, and delegation never needs it.
.gitlab/CODEOWNERSgrants approval, scoped per path.- Protected branch Allowed to merge on
maingrants the merge button, scoped to the whole branch. - The project role grants administration.
If someone asks for Maintainer so they can merge, they need control 2.
Steps
1. Resolve IDs and check access
glab api "groups/<GROUP_PATH_URLENCODED>" | jq '{id, full_path}'
glab api "projects/gitlab-org%2Fcli" | jq '.shared_with_groups'
glab api "projects/gitlab-org%2Fcli/protected_branches/main"Save the protected branch response before changing it. It is the rollback reference.
For a username list, resolve each and confirm the person is already a project member:
glab api "users?username=<USERNAME>" | jq '.[0].id'
glab api "projects/gitlab-org%2Fcli/members/all/<USER_ID>" | jq '.access_level'2. Invite the group at Developer
Skip if shared_with_groups already lists it.
glab api --method POST "projects/gitlab-org%2Fcli/share" \
-f group_id=<GROUP_ID> -f group_access=30Developer is the right level. It is enough to approve, and the merge button comes from step 4, not from the role.
On 404 Not Found: the caller lacks the Maintainer or Owner role in the invited group. This is a property of the invited group, not of gitlab-org. Do not retry and do not escalate to a gitlab-org Owner. Instead, find who can run it:
glab api "groups/<GROUP_ID>/members/all?per_page=100" \
| jq -r '.[] | select(.access_level >= 40) | .username'Report those usernames and stop this step. The remaining steps still work, so continue to them and flag the invite as outstanding.
3. Edit CODEOWNERS
Read .gitlab/CODEOWNERS and add one line per path, placed with the other specific patterns.
Repeat the maintainers on every line, because a later pattern replaces the owners of an earlier one rather than adding to them. Add @gl-docsteam on any line under docs/.
/internal/commands/<area>/ @gitlab-com/ai-engineering/ai-coding/teams/gitlab-cli-maintainers @<group>
/docs/source/<area>/ @gitlab-com/ai-engineering/ai-coding/teams/gitlab-cli-maintainers @gl-docsteam @<group>The file is one section, so one approval from any owner on the matching line satisfies the requirement. Listing the maintainers alongside a team means either can approve, not both. Say this plainly when reporting, because people expect it to mean both.
4. Grant merge access on main
Additive. Do not repeat existing entries.
echo '{"allowed_to_merge":[{"group_id":<GROUP_ID>}]}' \
| glab api --method PATCH "projects/gitlab-org%2Fcli/protected_branches/main" \
--input - -H "Content-Type: application/json"Use {"user_id":<USER_ID>} for individuals. Several entries can go in one call.
Both flags matter: --input - and the explicit Content-Type header. Without the header the request fails with 415.
5. Verify and open the merge request
glab api "projects/gitlab-org%2Fcli/protected_branches/main" \
| jq '.merge_access_levels[] | {access_level_description, user_id, group_id}'The CODEOWNERS edit is the only file change, so it goes in a merge request. The membership and protected branch changes take effect immediately and are not part of the diff. Say which is which in the description.
Report back
State separately:
- Which changes are already live, meaning the invite and the merge access.
- Which are pending review, meaning the CODEOWNERS merge request.
- Anything blocked, such as an invite that needs a group Maintainer, and who can unblock it.
Rollback
echo '{"allowed_to_merge":[{"id":<ENTRY_ID>,"_destroy":true}]}' \
| glab api --method PATCH "projects/gitlab-org%2Fcli/protected_branches/main" \
--input - -H "Content-Type: application/json"Entry IDs come from the saved response in step 1.
Do not
- Grant the Maintainer role to give someone the merge button.
- Assume a merge access entry is path-scoped. It covers the whole branch, and the approval requirement is what scopes a change.
- Try to lower an inherited role at the project level. It is not possible; inherited roles are changed in the
gitlab-orggroup. - Delete and recreate the protected branch. Use
PATCH, which leavesmainprotected throughout.