GitLabgitlab-org

cli

main
ply5 git calls291 ms97 KiB3 cachedprotocol v2
132 lines5.0 KiBRaw

Security releases

Security fixes are developed in the private gitlab-org/security/cli repository and ship in a regular release from main. The CLI doesn't use patch release branches.

[!warning] Never push a security fix, or a branch that contains one, to gitlab-org/cli. The project is public, so anything pushed there discloses the vulnerability.

How the security repository works

gitlab-org/security/cli is a private fork of gitlab-org/cli. Its main branch pull-mirrors canonical main. The mirror only updates main, and doesn't overwrite a branch that has diverged. When a security fix merges into the security repository's main, the mirror stops updating it until the fix is released and main is resynced.

Every fix merged into the security repository's main ships together in the next release. Merge a fix only when it's ready to release.

The mirror is configured in the security repository's Settings > Repository > Mirroring repositories: it pulls from gitlab-org/cli, the branch filter is main, and overwriting diverged branches is off.

Process

mermaid
graph TD;
A[Confidential issue] --> B[MR to security main]
B --> D[MR from security main to canonical main]
D --> E[Release from canonical main]
E --> F[Resync security main]
F -.-> G[Optional: notify package maintainers]

Start with a confidential issue

A security fix starts with a confidential issue in gitlab-org/cli that describes the vulnerability.

Set up the security repository

Work in a separate clone of the security repository, so origin points to it and a default git push can't reach the public project:

shell
git clone git@gitlab.com:gitlab-org/security/cli.git glab-security
cd glab-security
lefthook install

Don't add gitlab-org/cli as a remote in this clone. To fetch canonical main, use its URL, as the commands in this guide do.

Develop the fix

  1. Create a branch named security-<issue number>, for example security-9999 for issue #9999.
  2. Implement the fix and push the branch to the security repository.
  3. Open a merge request that targets the security repository's main. Follow the same review process as any other change.
  4. Request a review from @ai-security-fix-reviewer-gitlab-org and address its findings. Its review is advisory. Then get a PSIRT review: assign a member of @gitlab-com/gl-security/product-security/psirt-group as a reviewer, or mention the group in a comment (example). PSIRT decides whether the fix needs a CVE.
  5. When the fix is ready to release, merge it.

Merge into canonical main

The merge request to gitlab-org/cli is public, so open it only when you're ready to release. Use the security repository's main as the source:

shell
glab mr create --repo gitlab-org/cli --head gitlab-org/security/cli \
  --source-branch main --target-branch main \
  --title "fix(scope): describe the fix" \
  --description "Merge the security fix from gitlab-org/security/cli." --yes

Pass --description so glab doesn't prompt for a template. Don't use --fill. It pushes and adds a gitlab-org/cli remote. The description is public, so don't describe the vulnerability in it.

In the UI, go to Code > Merge requests > New merge request in gitlab-org/security/cli, select gitlab-org/security/cli and main as the source, and gitlab-org/cli and main as the target.

Merging runs the merged results pipeline and the merge train against the latest canonical main. Squash is on by default, so the merge request title becomes the commit message on main. Use a Conventional Commits title, such as fix(auth): .... For an example, see !2841.

If canonical main has moved and the merge request has conflicts, resolve them in the security repository, not in a public branch. Pushing to the security repository's main needs the Maintainer role:

shell
git checkout main
git pull origin main
git fetch https://gitlab.com/gitlab-org/cli.git main
git merge FETCH_HEAD
git push origin main

Release

Release from canonical main straight away. Run the release schedule on demand. See forcing a release off-cycle.

Validate that the released binary fixes the vulnerability.

Resync the security repository

After the release, reset the security repository's main to canonical main, so the mirror resumes:

shell
git fetch https://gitlab.com/gitlab-org/cli.git main
git push --force origin FETCH_HEAD:main

This needs the Maintainer role in gitlab-org/security/cli.

Notify package maintainers

This step is optional. Homebrew, Snap, and Scoop update automatically after the release. To get the fix to other packages sooner, you can email the maintainers of the community-maintained packages. See notifying maintainers.

1# Security releases
3Security fixes are developed in the private
4[`gitlab-org/security/cli`](https://gitlab.com/gitlab-org/security/cli) repository and
5ship in a regular release from `main`. The CLI doesn't use patch release branches.
7> [!warning]
8> Never push a security fix, or a branch that contains one, to
9> [`gitlab-org/cli`](https://gitlab.com/gitlab-org/cli). The project is public, so
10> anything pushed there discloses the vulnerability.
12## How the security repository works
14`gitlab-org/security/cli` is a private fork of `gitlab-org/cli`. Its `main` branch
15pull-mirrors canonical `main`. The mirror only updates `main`, and doesn't overwrite a
16branch that has diverged. When a security fix merges into the security repository's
17`main`, the mirror stops updating it until the fix is released and `main` is resynced.
19Every fix merged into the security repository's `main` ships together in the next
20release. Merge a fix only when it's ready to release.
22The mirror is configured in the security repository's
23**Settings > Repository > Mirroring repositories**: it pulls from `gitlab-org/cli`,
24the branch filter is `main`, and overwriting diverged branches is off.
26## Process
28```mermaid
29graph TD;
30A[Confidential issue] --> B[MR to security main]
31B --> D[MR from security main to canonical main]
32D --> E[Release from canonical main]
33E --> F[Resync security main]
34F -.-> G[Optional: notify package maintainers]
35```
37### Start with a confidential issue
39A security fix starts with a confidential issue in `gitlab-org/cli` that describes the
40vulnerability.
42### Set up the security repository
44Work in a separate clone of the security repository, so `origin` points to it and a
45default `git push` can't reach the public project:
47```shell
48git clone git@gitlab.com:gitlab-org/security/cli.git glab-security
49cd glab-security
50lefthook install
51```
53Don't add `gitlab-org/cli` as a remote in this clone. To fetch canonical `main`, use
54its URL, as the commands in this guide do.
56### Develop the fix
581. Create a branch named `security-<issue number>`, for example `security-9999` for
59 issue `#9999`.
601. Implement the fix and push the branch to the security repository.
611. Open a merge request that targets the security repository's `main`. Follow the
62 same review process as any other change.
631. Request a review from `@ai-security-fix-reviewer-gitlab-org` and address its
64 findings. Its review is advisory. Then get a PSIRT review: assign a member of
65 `@gitlab-com/gl-security/product-security/psirt-group` as a reviewer, or mention
66 the group in a comment
67 ([example](https://gitlab.com/gitlab-org/security/cli/-/merge_requests/28)).
68 PSIRT decides whether the fix needs a CVE.
691. When the fix is ready to release, merge it.
71### Merge into canonical `main`
73The merge request to `gitlab-org/cli` is public, so open it only when you're ready to
74release. Use the security repository's `main` as the source:
76```shell
77glab mr create --repo gitlab-org/cli --head gitlab-org/security/cli \
78 --source-branch main --target-branch main \
79 --title "fix(scope): describe the fix" \
80 --description "Merge the security fix from gitlab-org/security/cli." --yes
81```
83Pass `--description` so `glab` doesn't prompt for a template. Don't use `--fill`. It
84pushes and adds a `gitlab-org/cli` remote. The description is public, so don't
85describe the vulnerability in it.
87In the UI, go to **Code > Merge requests > New merge request** in
88`gitlab-org/security/cli`, select `gitlab-org/security/cli` and `main` as the source,
89and `gitlab-org/cli` and `main` as the target.
91Merging runs the merged results pipeline and the merge train against the latest
92canonical `main`. Squash is on by default, so the merge request title becomes the
93commit message on `main`. Use a Conventional Commits title, such as `fix(auth): ...`.
94For an example, see [!2841](https://gitlab.com/gitlab-org/cli/-/merge_requests/2841).
96If canonical `main` has moved and the merge request has conflicts, resolve them in
97the security repository, not in a public branch. Pushing to the security
98repository's `main` needs the Maintainer role:
100```shell
101git checkout main
102git pull origin main
103git fetch https://gitlab.com/gitlab-org/cli.git main
104git merge FETCH_HEAD
105git push origin main
106```
108### Release
110Release from canonical `main` straight away. Run the release schedule on demand. See
111[forcing a release off-cycle](release_process.md#forcing-a-release-off-cycle).
113Validate that the released binary fixes the vulnerability.
115### Resync the security repository
117After the release, reset the security repository's `main` to canonical `main`, so the
118mirror resumes:
120```shell
121git fetch https://gitlab.com/gitlab-org/cli.git main
122git push --force origin FETCH_HEAD:main
123```
125This needs the Maintainer role in `gitlab-org/security/cli`.
127### Notify package maintainers
129This step is optional. Homebrew, Snap, and Scoop update automatically after the
130release. To get the fix to other packages sooner, you can email the maintainers of the
131community-maintained packages. See
132[notifying maintainers](release_process.md#notifying-maintainers).
Diagnostics5 git calls · 291 ms
CallStatusSizeTime0291 ms
discover200185 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
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 · hit5 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=5
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
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=2
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
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=4
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
fetch2002.0 KiB282 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=282
git.response.bytes=2037
git.response.cache=MISS
git.response.duration_ms=282
git.fetch.wants=cdcaee42418046272a07c01b5f86cb82c3aecb6e
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=2037
git.pkt.payload.max=2010
git.sideband.band1.bytes=2010
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
a5e196338fbdb86e
Request
d3f46056…
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