glab(1)

📦
version 1.128.0 · 13 versions
, in arch rolling

💅 glab(1) — the release-create glow-up 🎀

okay so bestie, welcome to the glab(1)</> manual page — specifically the part about glab-release-create, which is the one you're gonna be obsessed with if you've ever wanted to ship a release without losing your entire mind ✨

🌸 NAME 🌸

glab-release-create — create a new GitLab release, or update an existing one. literally that's it. that's the vibe. 💖

🦋 SYNOPSIS 🦋

glab release create  [...] [flags]

✨ DESCRIPTION ✨

So here's the deal, bestie: this command creates a brand-new GitLab release for a repository, or updates one that already exists. Requires at least the Developer role — no cap, don't even try it without the perms.

If a release already exists, it gets updated with all the new info you hand it. slay.

🎀 how 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.

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

like, the way that just works?? iconic. 💅

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

💜 OPTIONS 💜

  • -a, --assets-links="" — JSON string representation of assets links. see Examples for usage, bestie.
  • -m, --milestone=[] — the title of each milestone the release is associated with. multiple milestones can be comma-separated or specified by repeating the flag. 💫
  • -n, --name="" — the release name or title.
  • --no-close-milestone[=false] — prevent closing milestones after creating the release. very "leave it open, i'm not ready" energy.
  • --no-update[=false] — prevent updating the existing release.
  • -N, --notes="" — the release notes or description. accepts Markdown. 🍓
  • -F, --notes-file="" — read release notes from file. to read from stdin, use -.
  • --package-name="release-assets" — the package name, when uploading assets to the generic package release with --use-package-registry.
  • --publish-to-catalog=false ⟨EXPERIMENTAL⟩ — publish the release to the GitLab CI/CD catalog. 👑
  • -r, --ref="" — 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="" — ISO 8601 datetime when the release was ready. defaults to the current datetime.
  • -T, --tag-message="" — message to use if creating a new annotated tag.
  • --use-package-registry[=false] — 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 🌈

  • -h, --help[=false] — show help for this command.
  • -R, --repo="" — select another repository. you can use either OWNER/REPO or GROUP/NAMESPACE/REPO. the full URL or Git URL is also accepted. 💖

💀 EXAMPLE 💀

# 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
🙈 fair warning bestie: for that --publish-to-catalog one, do NOT run it manually. it's for CI/CD pipelines using the "release" keyword. periodt.

⭐ SEE ALSO ⭐

okay that's the whole page, go forth and ship releases like the main character you are 👑

this gorgeous little page was auto generated by spf13/cobra, and it's the Nov 2026 edition of the glab(1) manual — mwah, bye bestie, ily 💜

📦 where this page comes from