GitLabgitlab-org

cli

main
ply5 git calls27 ms98 KiB3 cachedprotocol v2
151 lines6.8 KiBRaw

Release process

Automated weekly release

A new version is released automatically every Tuesday at 12:00 UTC by a pipeline schedule. You don't need to do anything for a normal weekly release.

How it works:

  1. The Weekly automated release schedule (0 12 * * 2, Etc/UTC) runs on main with the release_schedule input set to true, which sets the RELEASE_SCHEDULE CI/CD variable.
  2. The tag-release job (.gitlab-ci.yml) runs scripts/release/create-release-tag.sh, which:
    • Finds the latest vX.Y.Z tag.
    • Skips the release if there are no releasable commits since that tag (merge commits don't count).
    • Bumps the version based on the Conventional Commit types since that tag: a feat bumps the minor version (vX.Y.Z → vX.(Y+1).0), otherwise it's a patch release (vX.Y.Z → vX.Y.(Z+1)). Then creates an annotated tag through the GitLab API using glab.
  3. Creating the tag triggers the normal tag-driven release pipeline (the release job and the distribution jobs), exactly as a manual tag would.

The schedule only runs tag-release; the heavy build/test jobs are skipped on it (see .skip-on-release-schedule in .gitlab-ci.yml) because the tag pipeline re-runs and gates the actual release. Other schedules, such as the daily main build, are unaffected.

Forcing a release off-cycle

To release before the next Tuesday, run the schedule on demand. It takes the same path as the weekly run, and the normal recurrence is unaffected. Needs the Maintainer role.

Select the play button on the Pipeline schedules page, or run:

shell
# Verify the schedule ID on the Pipeline schedules page linked above.
glab schedule run 4282239 --repo gitlab-org/cli

Caveats:

  • Nothing is released if there are no releasable commits since the last tag, or if the computed tag already exists. Re-running is safe.
  • A breaking change (! in a commit subject) fails the job on purpose.
  • You can't pick the version number. For that, or for a major release, use the manual process below.

Manual release

To release a new version of the CLI manually, you must:

  1. Do a quick test of the CLI in your local development. At this stage, you are only verifying there is no complete failure of the CLI.

  2. To preview which commits will be included in a release, run this command:

    shell
    git log --oneline --invert-grep --grep="Merge branch" --invert-grep --grep="chore" $(git describe --tags --abbrev=0)..main | sort -k2

If those changes are appropriate to be released, proceed with the process:

  1. Tag the latest commit on main (such as git tag v1.74.1).
  2. Push with this command: git push origin v1.74.1

Notifying maintainers

If the release is time-sensitive, such as for a security release, consider emailing the maintainers of the community-maintained channels. Contacts for the different maintainers are available in CLI 1Password Vault in the Maintainers of Community packages note.

Access to distribution channels

Homebrew

Homebrew releases were automated by the CI build. These manual instructions are provided if the automation fails.

Prerequisites:

  • An account on GitHub. (Any account is fine.)

To manually update the version available through Homebrew:

  1. Generate a new token with the repo, workflow, and gist scopes using this link. If you have an existing token with the correct scope, you can use it instead.

  2. On the Releases page for this project, identify the release version you want to publish.

  3. In the Assets area for the release, download the packaged source code (Source code (tar.gz)) for this release.

  4. To compute the SHA256 checksum, run sha256sum cli-v1.74.1.tar.gz.

  5. Create a pull request with the update with this command, modifying the source code URL and SHA as needed:

    shell
    brew bump-formula-pr --strict glab \
    --url="https://gitlab.com/gitlab-org/cli/-/archive/v1.74.1/cli-v1.74.1.tar.gz" \
    --sha256=b1b8ed3f4c7d8839b540d8a264b3a3ef670e78ae369ef0c01ef5d5e502714905
  6. When the pull request is merged, the update is complete.

Snapcraft

Snapcraft releases are automated:

  • The latest/edge channel is automatically built on every commit to main.
  • The latest/stable channel is automatically built when a new tag is pushed.

No manual action is required for Snapcraft releases.

Scoop

No manual action required.

The glab project was moved to GitLab in pull request 4168. Scoop uses the autoupdate URL for updating to newer versions.

WinGet

Prerequisites:

To update the WinGet package:

  1. On the Releases page for this project, identify the release version you want to publish.

  2. In the Assets area for the release, identify the Windows installer package (the filename should end in _installer.exe) and download it.

  3. Compute the SHA256 checksum for the file by running sha256sum filename.exe, replacing filename with the name of release installer you downloaded in the previous step. For example:

    shell
    $ sha256sum glab_1.23.1_Windows_x86_64_installer.exe
    
    36f9d45f68ea53cbafdbe96ba4206e4412abb4c2b8f00ba667054523bd7cc89e  glab_1.23.1_Windows_x86_64_installer.exe
  4. Copy the SHA from the result.

  5. On GitHub, create a pull request in the microsoft/winget-pkgs project. Use the pull request to update to version 1.23.1 as an example.

Setting up CI/CD for releasing

For automated testing, you need to set up credentials for unit testing.

For releasing, you also need to add a GITLAB_TOKEN_RELEASE. To create this token:

  1. Go to Settings -> Access Tokens
  2. Generate a new project token with api scope and Maintainer role.
  3. Add the new token as GITLAB_TOKEN_RELEASE protected and masked CI/CD variables.
1# Release process
3## Automated weekly release
5A new version is released automatically every Tuesday at 12:00 UTC by a pipeline
6schedule. You don't need to do anything for a normal weekly release.
8How it works:
101. The [**Weekly automated release schedule**](https://gitlab.com/gitlab-org/cli/-/pipeline_schedules)
11 (`0 12 * * 2`, `Etc/UTC`) runs on `main` with the `release_schedule` input set
12 to `true`, which sets the `RELEASE_SCHEDULE` CI/CD variable.
131. The `tag-release` job (`.gitlab-ci.yml`) runs `scripts/release/create-release-tag.sh`, which:
14 - Finds the latest `vX.Y.Z` tag.
15 - Skips the release if there are no releasable commits since that tag (merge
16 commits don't count).
17 - Bumps the version based on the Conventional Commit types since that tag: a
18 `feat` bumps the minor version (`vX.Y.Z` → `vX.(Y+1).0`), otherwise it's a
19 patch release (`vX.Y.Z` → `vX.Y.(Z+1)`). Then creates an annotated tag
20 through the GitLab API using `glab`.
211. Creating the tag triggers the normal tag-driven release pipeline (the `release`
22 job and the distribution jobs), exactly as a manual tag would.
24The schedule only runs `tag-release`; the heavy build/test jobs are skipped on it
25(see `.skip-on-release-schedule` in `.gitlab-ci.yml`) because the tag pipeline
26re-runs and gates the actual release. Other schedules, such as the daily `main`
27build, are unaffected.
29### Forcing a release off-cycle
31To release before the next Tuesday, run the schedule on demand. It takes the same
32path as the weekly run, and the normal recurrence is unaffected. Needs the
33Maintainer role.
35Select the play button on the
36[**Pipeline schedules** page](https://gitlab.com/gitlab-org/cli/-/pipeline_schedules),
37or run:
39```shell
40# Verify the schedule ID on the Pipeline schedules page linked above.
41glab schedule run 4282239 --repo gitlab-org/cli
42```
44Caveats:
46- Nothing is released if there are no releasable commits since the last tag, or
47 if the computed tag already exists. Re-running is safe.
48- A breaking change (`!` in a commit subject) fails the job on purpose.
49- You can't pick the version number. For that, or for a major release, use the
50 manual process below.
52## Manual release
54To release a new version of the CLI manually, you must:
561. Do a quick test of the CLI in your local development. At this stage, you are only verifying there is no complete failure of the CLI.
571. To preview which commits will be included in a release, run this command:
59 ```shell
60 git log --oneline --invert-grep --grep="Merge branch" --invert-grep --grep="chore" $(git describe --tags --abbrev=0)..main | sort -k2
61 ```
63If those changes are appropriate to be released, proceed with the process:
651. Tag the latest commit on `main` (such as `git tag v1.74.1`).
661. Push with this command: `git push origin v1.74.1`
68## Notifying maintainers
70If the release is time-sensitive, such as for a security release, consider emailing
71the maintainers of the community-maintained channels. Contacts for the different maintainers
72are available in CLI 1Password Vault in the **Maintainers of Community packages** note.
74## Access to distribution channels
76### Homebrew
78Homebrew releases were [automated by the CI build](https://gitlab.com/gitlab-org/cli/-/merge_requests/1137).
79These manual instructions are provided if the automation fails.
81Prerequisites:
83- An account on GitHub. (Any account is fine.)
85To manually update the version available through Homebrew:
871. Generate a new token with the `repo`, `workflow`, and `gist` scopes [using this link](https://github.com/settings/tokens/new?scopes=gist,repo,workflow&description=Homebrew).
88 If you have an existing token with the correct scope, you can use it instead.
891. On the [**Releases** page for this project](https://gitlab.com/gitlab-org/cli/-/releases), identify the release version you want to publish.
901. In the **Assets** area for the release, download the packaged source code (`Source code (tar.gz)`) for this release.
911. To compute the SHA256 checksum, run `sha256sum cli-v1.74.1.tar.gz`.
921. Create a pull request with the update with this command, modifying the source code URL and SHA as needed:
94 ```shell
95 brew bump-formula-pr --strict glab \
96 --url="https://gitlab.com/gitlab-org/cli/-/archive/v1.74.1/cli-v1.74.1.tar.gz" \
97 --sha256=b1b8ed3f4c7d8839b540d8a264b3a3ef670e78ae369ef0c01ef5d5e502714905
98 ```
1001. When the pull request is merged, the update is complete.
102### Snapcraft
104Snapcraft releases are automated:
106- The `latest/edge` channel is automatically built on every commit to `main`.
107- The `latest/stable` channel is automatically built when a new tag is pushed.
109No manual action is required for Snapcraft releases.
111### Scoop
113No manual action required.
115The `glab` project was moved to GitLab in [pull request 4168](https://github.com/ScoopInstaller/Main/pull/4168/files).
116Scoop uses the [autoupdate URL](https://github.com/ScoopInstaller/Main/pull/4168/files#diff-f454f19e58d4c978be55818fa3c6ad5e1424e81fbb0b693dca0b76cc879f5457L21) for updating to newer versions.
118### WinGet
120Prerequisites:
122- You must have a GitHub account.
123- You must have signed Microsoft's Contributor License Agreement (CLA).
124- You have read the GitLab policy for [Contributing to a third-party project on behalf of GitLab](https://handbook.gitlab.com/handbook/engineering/open-source/).
125 (The confidential, internal [legal issue](https://gitlab.com/gitlab-com/legal-and-compliance/-/issues/1286) is also available.)
127To update the WinGet package:
1291. On the [**Releases** page for this project](https://gitlab.com/gitlab-org/cli/-/releases), identify the release version you want to publish.
1301. In the **Assets** area for the release, identify the Windows installer package (the filename should end in `_installer.exe`) and download it.
1311. Compute the SHA256 checksum for the file by running `sha256sum filename.exe`, replacing `filename` with the name of release installer you downloaded in the previous step. For example:
133 ```shell
134 $ sha256sum glab_1.23.1_Windows_x86_64_installer.exe
136 36f9d45f68ea53cbafdbe96ba4206e4412abb4c2b8f00ba667054523bd7cc89e glab_1.23.1_Windows_x86_64_installer.exe
137 ```
1391. Copy the SHA from the result.
1401. On GitHub, create a pull request in the `microsoft/winget-pkgs` project. Use the
141 [pull request to update to version 1.23.1](https://github.com/microsoft/winget-pkgs/pull/90349) as an example.
143## Setting up CI/CD for releasing
145For automated testing, you need to [set up credentials](https://gitlab.com/groups/gitlab-org/-/epics/8251) for unit testing.
147For releasing, you also need to add a `GITLAB_TOKEN_RELEASE`. To create this token:
1491. Go to Settings -> [Access Tokens](https://gitlab.com/gitlab-org/cli/-/settings/access_tokens)
1501. Generate a new project token with `api` scope and `Maintainer` role.
1511. Add the new token as `GITLAB_TOKEN_RELEASE` **protected** and **masked** CI/CD variables.
Diagnostics5 git calls · 27 ms
CallStatusSizeTime027 ms
discover200185 B2 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 KiB2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=59849
git.response.cache=UPDATING
git.response.duration_ms=2
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=4
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=21
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
fetch2003.0 KiB · hit21 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=3061
git.response.cache=HIT
git.response.duration_ms=21
git.fetch.wants=7d42b85d0110ccccd0ecdf50d4356b94f60ea424
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=3061
git.pkt.payload.max=3034
git.sideband.band1.bytes=3034
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
a5e120d84aec7fd8
Request
6be76860…
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