---
name: "glab-release-create"
section: "1"
platform: "linux"
package: "glab"
version: "1.126.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/glab-release-create"
---

# glab-release-create(1)

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

## NAME

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

## SYNOPSIS

**glab release create  \[...\] \[flags\]**

## DESCRIPTION

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

## OPTIONS

**-a**, **--assets-links**=""\
 	JSON string representation of assets links. See Examples for usage.

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

**--no-update**\[=false\]\
 	Prevent updating the existing release.

**-N**, **--notes**=""\
 	The release notes or description. Accepts Markdown.

**-F**, **--notes-file**=""\
 	Read release notes '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
```

## SEE ALSO

**[glab-release(1)](/glab-release/1.md)**