GitLabgitlab-org

cli

main
ply7 git calls248 ms100 KiB4 cachedprotocol v2
148 lines6.5 KiBRaw

Create a new GitLab release, or update an existing one.

Synopsis

Create a new GitLab release for a repository, or update an existing one. Requires at least the Developer role.

An existing release is updated with the new information you provide.

To create a release from an annotated Git tag:

  1. Create the tag locally with Git, and push the tag to GitLab.

  2. Run this command.

  3. If the Git tag you specify doesn't exist, the command creates a release from the latest state of the default branch, and tags it with the tag name you specify.

    To override this behavior, use --ref. The ref can be a commit SHA, another tag name, or a branch name.

  4. Optional. To fetch the new tag locally after the release, run git fetch --tags origin.

Authentication in CI/CD:

  • Recommended: Use CI_JOB_TOKEN and turn on CI auto-login by setting GLAB_ENABLE_CI_AUTOLOGIN=true. glab sends CI_JOB_TOKEN in the JOB-TOKEN header, which the Releases API accepts.
    • The Milestones API does not accept CI_JOB_TOKEN, so the token cannot close milestones.
    • If you use --milestone, the release is still created and the command exits successfully. The milestone stays open and glab logs an error. To avoid the error, use --no-close-milestone.
  • Alternative: Use GITLAB_TOKEN set to a project or group access token with the api scope. With this token, --milestone can close milestones.
  • Do not set GITLAB_TOKEN=$CI_JOB_TOKEN because the Releases API will return a 404 Not Found. GITLAB_TOKEN is sent as a personal access token in the PRIVATE-TOKEN header, which the Releases API does not accept.

The --publish-to-catalog flag is an experiment: it might be unstable or removed at any time, and is not ready for production use. For more information, see https://docs.gitlab.com/policy/development_stages_support/.

plaintext
glab release create <tag> [<files>...] [flags]

Examples

console
# Create a release interactively
glab release create v1.0.1

# Create a release non-interactively by specifying a note
glab release create v1.0.1 --notes "bugfix release"

# Use release notes from a file
glab release create v1.0.1 -F changelog.md

# Update an existing release (e.g., change the release date) without modifying notes
glab release create v1.0.1 --released-at "2024-01-15T10:00:00Z"

# Upload a release asset with a display name (type will default to 'other')
glab release create v1.0.1 '/path/to/asset.zip#My display label'

# Upload a release asset with a display name and type
glab release create v1.0.1 '/path/to/asset.png#My display label#image'

# Upload all assets in a specified folder (types default to 'other')
glab release create v1.0.1 ./dist/*

# Upload all tarballs in a specified folder (types default to 'other')
glab release create v1.0.1 ./dist/*.tar.gz

# Create a release from a CI/CD job using the job token
GLAB_ENABLE_CI_AUTOLOGIN=true glab release create v1.0.1 --notes "See CHANGELOG.md" --ref "$CI_COMMIT_SHA"

# Create a release from a CI/CD job using a project or group access token with the 'api' scope
GITLAB_TOKEN="$ACCESS_TOKEN" glab release create v1.0.1 --notes "See CHANGELOG.md" --ref "$CI_COMMIT_SHA"

# Create a release with assets, such as packages, specified as a JSON object
glab release create v1.0.1 --assets-links='
[
  {
    "name": "Asset1",
    "url":"https://<domain>/some/location/1",
    "link_type": "other",
    "direct_asset_path": "path/to/file"
  }
]'

# (EXPERIMENTAL) Create a release and publish it to the GitLab CI/CD catalog
# Requires the feature flag `ci_release_cli_catalog_publish_option` to be enabled
# for this project in your GitLab instance. Do NOT run this manually. Use it as part
# of a CI/CD pipeline with the "release" keyword:
#
# - It retrieves components from the current repository by searching for
#   `yml` files within the "templates" directory and its subdirectories.
# - It fails if the feature flag `ci_release_cli_catalog_publish_option`
#   is not enabled for this project in your GitLab instance.

# Components can be defined:

# - In single files ending in `.yml` for each component, like `templates/secret-detection.yml`.
# - In subdirectories containing `template.yml` files as entry points,
#   for components that bundle together multiple related files. For example,
#   `templates/secret-detection/template.yml`.

glab release create v1.0.1 --publish-to-catalog

Options

plaintext
  -a, --assets-links string    JSON string representation of assets links. See Examples for usage.
  -m, --milestone strings      The title of each milestone the release is associated with. Multiple milestones can be comma-separated or specified by repeating the flag.
  -n, --name string            The release name or title.
      --no-close-milestone     Prevent closing milestones after creating the release.
      --no-update              Prevent updating the existing release.
  -N, --notes string           The release notes or description. Accepts Markdown.
  -F, --notes-file string      Read release notes 'file'. To read from stdin, use '-'. If both --notes and --notes-file are set, --notes takes precedence.
      --package-name string    The package name, when uploading assets to the generic package release with --use-package-registry. (default "release-assets")
      --publish-to-catalog     (EXPERIMENTAL) Publish the release to the GitLab CI/CD catalog.
  -r, --ref string             If the specified tag doesn't exist, create a release from the ref and tag it with the specified tag name. Accepts a commit SHA, tag name, or branch name.
  -D, --released-at string     ISO 8601 datetime when the release was ready. Defaults to the current datetime.
  -T, --tag-message string     Message to use if creating a new annotated tag.
      --use-package-registry   Upload release assets to the generic package registry of the project. Overrides the GITLAB_RELEASE_ASSETS_USE_PACKAGE_REGISTRY environment variable.

Options inherited from parent commands

plaintext
  -h, --help          Show help for this command.
  -R, --repo string   Select another repository. You can use either OWNER/REPO or GROUP/NAMESPACE/REPO. The full URL or Git URL is also accepted.
1---
2title: '`glab release create`'
3stage: AI Clients
4group: Developer Clients
5info: 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>
6---
8<!--
9This documentation is auto generated by a script.
10Please do not edit this file directly. Run `make gen-docs` instead.
11-->
13Create a new GitLab release, or update an existing one.
15## Synopsis
17Create a new GitLab release for a repository, or
18update an existing one. Requires at least the Developer role.
20An existing release is updated with the new information you provide.
22To create a release from an annotated Git tag:
241. Create the tag locally with Git, and push the tag to GitLab.
252. Run this command.
263. If the Git tag you specify doesn't exist, the command creates a
27 release from the latest state of the default branch, and tags it
28 with the tag name you specify.
30 To override this behavior, use `--ref`. The `ref`
31 can be a commit SHA, another tag name, or a branch name.
324. Optional. To fetch the new tag locally after the release, run
33 `git fetch --tags origin`.
35Authentication in CI/CD:
37- Recommended: Use `CI_JOB_TOKEN` and turn on CI auto-login by
38 setting `GLAB_ENABLE_CI_AUTOLOGIN=true`. glab sends
39 `CI_JOB_TOKEN` in the `JOB-TOKEN` header, which the Releases
40 API accepts.
41 - The Milestones API does not accept `CI_JOB_TOKEN`, so the token cannot
42 close milestones.
43 - If you use `--milestone`, the release is still created and the command
44 exits successfully. The milestone stays open and glab logs an error.
45 To avoid the error, use `--no-close-milestone`.
46- Alternative: Use `GITLAB_TOKEN` set to a project or group access token with the
47 `api` scope. With this token, `--milestone` can close milestones.
48- Do not set `GITLAB_TOKEN=$CI_JOB_TOKEN` because the Releases API will
49 return a `404 Not Found`. `GITLAB_TOKEN` is sent as a personal access token in
50 the `PRIVATE-TOKEN` header, which the Releases API does not accept.
52The `--publish-to-catalog` flag is an experiment: it might be
53unstable or removed at any time, and is not ready for production use.
54For more information, see
55<https://docs.gitlab.com/policy/development_stages_support/>.
57```plaintext
58glab release create <tag> [<files>...] [flags]
59```
61## Examples
63```console
64# Create a release interactively
65glab release create v1.0.1
67# Create a release non-interactively by specifying a note
68glab release create v1.0.1 --notes "bugfix release"
70# Use release notes from a file
71glab release create v1.0.1 -F changelog.md
73# Update an existing release (e.g., change the release date) without modifying notes
74glab release create v1.0.1 --released-at "2024-01-15T10:00:00Z"
76# Upload a release asset with a display name (type will default to 'other')
77glab release create v1.0.1 '/path/to/asset.zip#My display label'
79# Upload a release asset with a display name and type
80glab release create v1.0.1 '/path/to/asset.png#My display label#image'
82# Upload all assets in a specified folder (types default to 'other')
83glab release create v1.0.1 ./dist/*
85# Upload all tarballs in a specified folder (types default to 'other')
86glab release create v1.0.1 ./dist/*.tar.gz
88# Create a release from a CI/CD job using the job token
89GLAB_ENABLE_CI_AUTOLOGIN=true glab release create v1.0.1 --notes "See CHANGELOG.md" --ref "$CI_COMMIT_SHA"
91# Create a release from a CI/CD job using a project or group access token with the 'api' scope
92GITLAB_TOKEN="$ACCESS_TOKEN" glab release create v1.0.1 --notes "See CHANGELOG.md" --ref "$CI_COMMIT_SHA"
94# Create a release with assets, such as packages, specified as a JSON object
95glab release create v1.0.1 --assets-links='
97 {
98 "name": "Asset1",
99 "url":"https://<domain>/some/location/1",
100 "link_type": "other",
101 "direct_asset_path": "path/to/file"
102 }
103]'
105# (EXPERIMENTAL) Create a release and publish it to the GitLab CI/CD catalog
106# Requires the feature flag `ci_release_cli_catalog_publish_option` to be enabled
107# for this project in your GitLab instance. Do NOT run this manually. Use it as part
108# of a CI/CD pipeline with the "release" keyword:
110# - It retrieves components from the current repository by searching for
111# `yml` files within the "templates" directory and its subdirectories.
112# - It fails if the feature flag `ci_release_cli_catalog_publish_option`
113# is not enabled for this project in your GitLab instance.
115# Components can be defined:
117# - In single files ending in `.yml` for each component, like `templates/secret-detection.yml`.
118# - In subdirectories containing `template.yml` files as entry points,
119# for components that bundle together multiple related files. For example,
120# `templates/secret-detection/template.yml`.
122glab release create v1.0.1 --publish-to-catalog
123```
125## Options
127```plaintext
128 -a, --assets-links string JSON string representation of assets links. See Examples for usage.
129 -m, --milestone strings The title of each milestone the release is associated with. Multiple milestones can be comma-separated or specified by repeating the flag.
130 -n, --name string The release name or title.
131 --no-close-milestone Prevent closing milestones after creating the release.
132 --no-update Prevent updating the existing release.
133 -N, --notes string The release notes or description. Accepts Markdown.
134 -F, --notes-file string Read release notes 'file'. To read from stdin, use '-'. If both --notes and --notes-file are set, --notes takes precedence.
135 --package-name string The package name, when uploading assets to the generic package release with --use-package-registry. (default "release-assets")
136 --publish-to-catalog (EXPERIMENTAL) Publish the release to the GitLab CI/CD catalog.
137 -r, --ref string If the specified tag doesn't exist, create a release from the ref and tag it with the specified tag name. Accepts a commit SHA, tag name, or branch name.
138 -D, --released-at string ISO 8601 datetime when the release was ready. Defaults to the current datetime.
139 -T, --tag-message string Message to use if creating a new annotated tag.
140 --use-package-registry Upload release assets to the generic package registry of the project. Overrides the GITLAB_RELEASE_ASSETS_USE_PACKAGE_REGISTRY environment variable.
141```
143## Options inherited from parent commands
145```plaintext
146 -h, --help Show help for this command.
147 -R, --repo string Select another repository. You can use either OWNER/REPO or GROUP/NAMESPACE/REPO. The full URL or Git URL is also accepted.
148```
Diagnostics7 git calls · 248 ms
CallStatusSizeTime0248 ms
discover200185 B4 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 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
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=3
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 · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=3
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:02001.7 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=1744
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=5e4007a5673eb3bf5d0d7f1a1463c3b2ca3fb3bd
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=1744
git.pkt.payload.max=1717
git.sideband.band1.bytes=1717
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1717
git.pack.trailer=3f1b9ccc7756e8941d6705e8187c87fd922113e6
Open pack map
fetchtree:0200285 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=235
git.response.bytes=285
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=d90a57de1cf05ecdcfb65ca820f300e9b5c627e6
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=285
git.pkt.payload.max=258
git.sideband.band1.bytes=258
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=258
git.pack.trailer=2db708255e5839407968a3665a5b4af1de8a1f1a
Open pack map
fetch2002.7 KiB235 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2746
git.response.cache=MISS
git.response.duration_ms=235
git.fetch.wants=51e92d1775fef55a01dead8147284f4097cf46da
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=2746
git.pkt.payload.max=2719
git.sideband.band1.bytes=2719
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
a5e132d73f14a9fe
Request
50eaf21c…
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