glab(1)

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.

•   Alternative: Use GITLAB_TOKEN set to a project or group access token with the api scope.

•   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 documentation for example.

-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 specified as 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)