GitLabgitlab-org

cli

main
ply5 git calls269 ms97 KiB3 cachedprotocol v2
131 lines5.6 KiBRaw

Path ownership and merge access

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.

LayerWhere it is configuredScopeWhat it grants
Approval.gitlab/CODEOWNERSPer pathSatisfies the required code owner approval on matching files
MergeProtected branch Allowed to merge on mainWhole branchSelects the merge button after approvals are satisfied
AdministrationProject or group roleWhole projectSettings, CI/CD variables, protected branches, membership

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.

Current ownership

PathApprovers in addition to the maintainers
/README.md, /CONTRIBUTING.md, /docs/@gl-docsteam
/internal/dependencyfirewall/, /internal/commands/df/Dependency firewall reviewers
/internal/commands/govern/Govern reviewers
/internal/commands/orbit/@gitlab-org/orbit/team

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

  1. 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
  2. Add the CODEOWNERS entries. Repeat the maintainers on every line, and add @gl-docsteam on documentation lines.

    plaintext
    /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>
  3. Grant merge access on main. The PATCH is additive, so existing entries are preserved and do not need to be repeated.

    shell
    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"

    For an individual instead of a group, use {"user_id":<USER_ID>}. The user must already be a project member.

  4. Verify.

    shell
    glab api "projects/gitlab-org%2Fcli/protected_branches/main"
  5. Do not grant the Maintainer role. If the team asks for it to get the merge button, the Allowed to merge entry from step 3 is what they actually need.

Remove a delegation

Remove the CODEOWNERS lines, then remove the merge access entry by its id:

shell
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"

Removing the project share is a separate step, and is only needed if the team should lose read and write access altogether.

1---
2stage: AI Clients
3group: Developer Clients
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>
5---
7# Path ownership and merge access
9This document explains how a team gets approval and merge rights over a
10subtree of this repository without being granted the Maintainer role on the
11whole project.
13## The three layers
15Approval, merging, and administration are separate controls. Keeping them
16separate is what lets a domain team own its own paths while the CLI
17maintainers keep the project settings.
19| Layer | Where it is configured | Scope | What it grants |
20| --- | --- | --- | --- |
21| Approval | [`.gitlab/CODEOWNERS`](../.gitlab/CODEOWNERS) | Per path | Satisfies the required code owner approval on matching files |
22| Merge | Protected branch **Allowed to merge** on `main` | Whole branch | Selects the merge button after approvals are satisfied |
23| Administration | Project or group role | Whole project | Settings, CI/CD variables, protected branches, membership |
25The Maintainer role is only needed for the third layer. A team that wants to
26review and ship changes to its own paths needs the Developer role, a
27CODEOWNERS entry, and an **Allowed to merge** entry.
29## Behavior to understand before you change anything
31- **A merge access entry is not path-scoped.** Anyone in **Allowed to merge**
32 can merge any merge request that targets `main`, not only the paths they
33 own. The approval requirement is what keeps changes scoped, because an
34 unapproved merge request cannot be merged by anyone.
35- **`.gitlab/CODEOWNERS` is a single section**, so a file matches exactly one
36 pattern, and one approval from any owner listed on that pattern satisfies
37 the requirement. Listing a domain team next to the maintainers means either
38 can approve, not both.
39- **A later pattern replaces the owners of an earlier one** rather than adding
40 to them. Every pattern repeats the maintainers, and every documentation
41 pattern also repeats `@gl-docsteam`.
42- **An inherited role cannot be lowered at the project level.** Members who
43 hold a role through the `gitlab-org` group keep it regardless of what is
44 configured here.
45- **An invited group grants each member the lower of their role in that group
46 and the level the group was invited at.** Inviting a group at Developer does
47 not promote anyone. When auditing, remember that the `members/all` endpoint
48 for a group also lists people who inherit into it from a parent group, so it
49 overstates who the invite actually covers.
50- **Approvals are recomputed when owned files change**, because
51 `selective_code_owner_removals` is enabled. Pushing a change to an owned
52 file drops that owner's approval and keeps the others.
54## Current ownership
56| Path | Approvers in addition to the maintainers |
57| --- | --- |
58| `/README.md`, `/CONTRIBUTING.md`, `/docs/` | `@gl-docsteam` |
59| `/internal/dependencyfirewall/`, `/internal/commands/df/` | Dependency firewall reviewers |
60| `/internal/commands/govern/` | Govern reviewers |
61| `/internal/commands/orbit/` | `@gitlab-org/orbit/team` |
63Documentation subtrees for a delegated area list `@gl-docsteam` as well as the
64owning team, so a documentation-only change does not need the owning team.
66## Delegate a path to a team
68Prefer a group over a list of usernames. A group keeps CODEOWNERS short, and
69membership is then managed by the team instead of by a CLI maintainer.
71### Prerequisites
73- The Maintainer role on `gitlab-org/cli`.
74- The Maintainer or Owner role in the group you are inviting. This is a
75 property of the invited group, not of `gitlab-org`. Without it, the invite
76 returns `404 Not Found`.
78### Steps
801. **Invite the group to the project with the Developer role.** A group can
81 only be used in CODEOWNERS or in a protected branch rule after it has been
82 invited, unless it is an ancestor of the project. A sibling subgroup under
83 `gitlab-org` is not an ancestor.
85 ```shell
86 glab api --method POST "projects/gitlab-org%2Fcli/share" \
87 -f group_id=<GROUP_ID> -f group_access=30
88 ```
901. **Add the CODEOWNERS entries.** Repeat the maintainers on every line, and
91 add `@gl-docsteam` on documentation lines.
93 ```plaintext
94 /internal/commands/<area>/ @gitlab-com/ai-engineering/ai-coding/teams/gitlab-cli-maintainers @<group>
95 /docs/source/<area>/ @gitlab-com/ai-engineering/ai-coding/teams/gitlab-cli-maintainers @gl-docsteam @<group>
96 ```
981. **Grant merge access on `main`.** The `PATCH` is additive, so existing
99 entries are preserved and do not need to be repeated.
101 ```shell
102 echo '{"allowed_to_merge":[{"group_id":<GROUP_ID>}]}' \
103 | glab api --method PATCH "projects/gitlab-org%2Fcli/protected_branches/main" \
104 --input - -H "Content-Type: application/json"
105 ```
107 For an individual instead of a group, use `{"user_id":<USER_ID>}`. The user
108 must already be a project member.
1101. **Verify.**
112 ```shell
113 glab api "projects/gitlab-org%2Fcli/protected_branches/main"
114 ```
1161. **Do not grant the Maintainer role.** If the team asks for it to get the
117 merge button, the **Allowed to merge** entry from step 3 is what they
118 actually need.
120## Remove a delegation
122Remove the CODEOWNERS lines, then remove the merge access entry by its `id`:
124```shell
125echo '{"allowed_to_merge":[{"id":<ENTRY_ID>,"_destroy":true}]}' \
126 | glab api --method PATCH "projects/gitlab-org%2Fcli/protected_branches/main" \
127 --input - -H "Content-Type: application/json"
128```
130Removing the project share is a separate step, and is only needed if the team
131should lose read and write access altogether.
Diagnostics5 git calls · 269 ms
CallStatusSizeTime0269 ms
discover200185 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=59849
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=264
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetch2002.4 KiB264 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2452
git.response.cache=MISS
git.response.duration_ms=264
git.fetch.wants=a491102cf4dde272f9ae33b6eedf2643d859e1b2
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2452
git.pkt.payload.max=2425
git.sideband.band1.bytes=2425
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

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.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e15dcf6c46cf6a
Request
1f35d71e…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format