GitLabgitlab-org

cli

main
ply7 git calls32 ms98 KiB5 cachedprotocol v2
154 lines5.4 KiBRaw

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 matching docs/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.

  1. .gitlab/CODEOWNERS grants approval, scoped per path.
  2. Protected branch Allowed to merge on main grants the merge button, scoped to the whole branch.
  3. 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

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

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

shell
glab api --method POST "projects/gitlab-org%2Fcli/share" \
  -f group_id=<GROUP_ID> -f group_access=30

Developer 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:

shell
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/.

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>

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.

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"

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

shell
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

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"

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-org group.
  • Delete and recreate the protected branch. Use PATCH, which leaves main protected throughout.
1---
2name: delegate-path-ownership
3description: Give a team approval and merge rights over a subtree of the GitLab CLI repository without granting the Maintainer role. Use when someone asks to add a group or user to CODEOWNERS, to let a team review and merge its own paths, or when a team asks for Maintainer so they can press the merge button. Takes a group (or usernames) and one or more paths.
4---
6# Delegate path ownership in the GitLab CLI
8Grant a team approval rights over its paths and the ability to merge, while
9the CLI maintainers keep project administration.
11Background and the reasoning behind the model:
12[`docs/path_ownership.md`](../../../docs/path_ownership.md).
14## Inputs
16Collect these before starting. Ask only for what is missing.
18- **Group path** such as `gitlab-org/orbit/team`, or a list of usernames when
19 the team has no group. Prefer a group.
20- **Paths** to delegate, such as `internal/commands/orbit`. Ask whether the
21 matching `docs/source/<area>/` subtree is included. It usually is.
23## The model
25Three independent controls. Only the third needs the Maintainer role, and
26delegation never needs it.
281. `.gitlab/CODEOWNERS` grants **approval**, scoped per path.
291. Protected branch **Allowed to merge** on `main` grants the **merge button**,
30 scoped to the whole branch.
311. The project role grants **administration**.
33If someone asks for Maintainer so they can merge, they need control 2.
35## Steps
37### 1. Resolve IDs and check access
39```shell
40glab api "groups/<GROUP_PATH_URLENCODED>" | jq '{id, full_path}'
41glab api "projects/gitlab-org%2Fcli" | jq '.shared_with_groups'
42glab api "projects/gitlab-org%2Fcli/protected_branches/main"
43```
45Save the protected branch response before changing it. It is the rollback
46reference.
48For a username list, resolve each and confirm the person is already a project
49member:
51```shell
52glab api "users?username=<USERNAME>" | jq '.[0].id'
53glab api "projects/gitlab-org%2Fcli/members/all/<USER_ID>" | jq '.access_level'
54```
56### 2. Invite the group at Developer
58Skip if `shared_with_groups` already lists it.
60```shell
61glab api --method POST "projects/gitlab-org%2Fcli/share" \
62 -f group_id=<GROUP_ID> -f group_access=30
63```
65Developer is the right level. It is enough to approve, and the merge button
66comes from step 4, not from the role.
68**On `404 Not Found`:** the caller lacks the Maintainer or Owner role **in the
69invited group**. This is a property of the invited group, not of `gitlab-org`.
70Do not retry and do not escalate to a `gitlab-org` Owner. Instead, find who can
71run it:
73```shell
74glab api "groups/<GROUP_ID>/members/all?per_page=100" \
75 | jq -r '.[] | select(.access_level >= 40) | .username'
76```
78Report those usernames and stop this step. The remaining steps still work, so
79continue to them and flag the invite as outstanding.
81### 3. Edit CODEOWNERS
83Read [`.gitlab/CODEOWNERS`](../../../.gitlab/CODEOWNERS) and add one line per
84path, placed with the other specific patterns.
86Repeat the maintainers on every line, because a later pattern replaces the
87owners of an earlier one rather than adding to them. Add `@gl-docsteam` on any
88line under `docs/`.
90```plaintext
91/internal/commands/<area>/ @gitlab-com/ai-engineering/ai-coding/teams/gitlab-cli-maintainers @<group>
92/docs/source/<area>/ @gitlab-com/ai-engineering/ai-coding/teams/gitlab-cli-maintainers @gl-docsteam @<group>
93```
95The file is one section, so one approval from any owner on the matching line
96satisfies the requirement. Listing the maintainers alongside a team means
97either can approve, not both. Say this plainly when reporting, because people
98expect it to mean both.
100### 4. Grant merge access on `main`
102Additive. Do not repeat existing entries.
104```shell
105echo '{"allowed_to_merge":[{"group_id":<GROUP_ID>}]}' \
106 | glab api --method PATCH "projects/gitlab-org%2Fcli/protected_branches/main" \
107 --input - -H "Content-Type: application/json"
108```
110Use `{"user_id":<USER_ID>}` for individuals. Several entries can go in one
111call.
113Both flags matter: `--input -` and the explicit `Content-Type` header. Without
114the header the request fails with `415`.
116### 5. Verify and open the merge request
118```shell
119glab api "projects/gitlab-org%2Fcli/protected_branches/main" \
120 | jq '.merge_access_levels[] | {access_level_description, user_id, group_id}'
121```
123The CODEOWNERS edit is the only file change, so it goes in a merge request.
124The membership and protected branch changes take effect immediately and are
125not part of the diff. Say which is which in the description.
127## Report back
129State separately:
131- Which changes are already live, meaning the invite and the merge access.
132- Which are pending review, meaning the CODEOWNERS merge request.
133- Anything blocked, such as an invite that needs a group Maintainer, and who
134 can unblock it.
136## Rollback
138```shell
139echo '{"allowed_to_merge":[{"id":<ENTRY_ID>,"_destroy":true}]}' \
140 | glab api --method PATCH "projects/gitlab-org%2Fcli/protected_branches/main" \
141 --input - -H "Content-Type: application/json"
142```
144Entry IDs come from the saved response in step 1.
146## Do not
148- Grant the Maintainer role to give someone the merge button.
149- Assume a merge access entry is path-scoped. It covers the whole branch, and
150 the approval requirement is what scopes a change.
151- Try to lower an inherited role at the project level. It is not possible;
152 inherited roles are changed in the `gitlab-org` group.
153- Delete and recreate the protected branch. Use `PATCH`, which leaves `main`
154 protected throughout.
Diagnostics7 git calls · 32 ms
CallStatusSizeTime032 ms
discover200185 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
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 KiB3 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=UPDATING
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 · hit4 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=32926
git.response.cache=HIT
git.response.duration_ms=4
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
fetchtree:0200120 B · 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=120
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=f9777e39e1ede4fb4ed1f3db7172c8ae6cc6afc8
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=120
git.pkt.payload.max=93
git.sideband.band1.bytes=93
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=93
git.pack.trailer=bfa6ba712f54e9c23144c1a5729495fda31667cf
Open pack map
fetchtree:0200106 B · hit1 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=1
git.response.bytes=106
git.response.cache=HIT
git.response.duration_ms=1
git.fetch.filter=tree:0
git.fetch.wants=8165769fc4769aba91bb5106c9417bc336e4431e
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=106
git.pkt.payload.max=79
git.sideband.band1.bytes=79
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=79
git.pack.trailer=c6f34805eef6e69738174ad6ce4857b998f638d6
Open pack map
fetch2002.4 KiB · hit24 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=24
git.response.bytes=2409
git.response.cache=HIT
git.response.duration_ms=24
git.fetch.wants=9766a8510e72ab399b4a1b249bf29f4d2f6f1ea8
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=2409
git.pkt.payload.max=2382
git.sideband.band1.bytes=2382
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
a5e31b21ce143e6e
Request
65ba658e…
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