Releases

In GitLab, a release enables you to create a snapshot of your project for your users, including installation packages and release notes. You can create a GitLab release on any branch. Creating a release also creates a Git tag to mark the release point in the source code.

caution
Deleting a Git tag associated with a release also deletes the release.

A release can include:

  • A snapshot of the source code of your repository.
  • Generic packages created from job artifacts.
  • Other metadata associated with a released version of your code.
  • Release notes.

When you create a release:

  • GitLab automatically archives source code and associates it with the release.
  • GitLab automatically creates a JSON file that lists everything in the release, so you can compare and audit releases. This file is called release evidence.

When you create a release, or after, you can:

View releases

Introduced in GitLab 12.8.

To view a list of releases:

  • On the left sidebar, select Deployments > Releases, or

  • On the project’s overview page, if at least one release exists, select the number of releases.

    Number of Releases

    • On public projects, this number is visible to all users.
    • On private projects, this number is visible to users with Reporter permissions or higher.

Sort releases

To sort releases by Released date or Created date, select from the sort order dropdown list. To switch between ascending or descending order, select Sort order.

Sort releases dropdown list options

Create a release

Introduced in GitLab 12.9. Releases can be created directly in the GitLab UI.

You can create a release:

We recommend creating a release as one of the last steps in your CI/CD pipeline.

Prerequisites:

  • You must have at least the Developer role for a project. For more information, read Release permissions.

Create a release in the Releases page

To create a release in the Releases page:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Deployments > Releases and select New release.
  3. From the Tag name dropdown, either:
    • Select an existing Git tag. Selecting an existing tag that is already associated with a release results in a validation error.
    • Enter a new Git tag name.
      1. From the Create from dropdown, select a branch or commit SHA to use when creating the new tag.
  4. Optional. Enter additional information about the release, including:
  5. Select Create release.

Create a release in the Tags page

To create a release in the Tags page, add release notes to either an existing or a new Git tag.

To add release notes to a new Git tag:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Repository > Tags.
  3. Select New tag.
  4. Optional. Enter a tag message in the Message text box.
  5. In the Release notes text box, enter the release’s description. You can use Markdown and drag and drop files to this text box.
  6. Select Create tag.

To edit release notes of an existing Git tag:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Repository > Tags.
  3. Select Edit release notes ( ).
  4. In the Release notes text box, enter the release’s description. You can use Markdown and drag and drop files to this text box.
  5. Select Save changes.

Creating a release by using a CI/CD job

You can create a release directly as part of the GitLab CI/CD pipeline by using the release keyword in the job definition.

The release is created only if the job processes without error. If the API returns an error during release creation, the release job fails.

Methods for creating a release using a CI/CD job include:

  • Create a release when a Git tag is created.
  • Create a release when a commit is merged to the default branch.

Create a release when a Git tag is created

In this CI/CD example, pushing a Git tag to the repository, or creating a Git tag in the UI triggers the release. You can use this method if you prefer to create the Git tag manually, and create a release as a result.

note
Do not provide Release notes when you create the Git tag in the UI. Providing release notes creates a release, resulting in the pipeline failing.

Key points in the following extract of an example .gitlab-ci.yml file:

  • The rules stanza defines when the job is added to the pipeline.
  • The Git tag is used in the release’s name and description.
release_job:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  rules:
    - if: $CI_COMMIT_TAG                 # Run this job when a tag is created
  script:
    - echo "running release_job"
  release:                               # See https://docs.gitlab.com/ee/ci/yaml/#release for available properties
    tag_name: '$CI_COMMIT_TAG'
    description: '$CI_COMMIT_TAG'

Create a release when a commit is merged to the default branch

In this CI/CD example, merging a commit to the default branch triggers the pipeline. You can use this method if your release workflow does not create a tag manually.

Key points in the following extract of an example .gitlab-ci.yml file:

  • The Git tag, description, and reference are created automatically in the pipeline.
  • If you manually create a tag, the release_job job does not run.
release_job:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  rules:
    - if: $CI_COMMIT_TAG
      when: never                                  # Do not run this job when a tag is created manually
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  # Run this job when commits are pushed or merged to the default branch
  script:
    - echo "running release_job for $TAG"
  release:                                         # See https://docs.gitlab.com/ee/ci/yaml/#release for available properties
    tag_name: 'v0.$CI_PIPELINE_IID'                # The version is incremented per pipeline.
    description: 'v0.$CI_PIPELINE_IID'
    ref: '$CI_COMMIT_SHA'                          # The tag is created from the pipeline SHA.
note
Environment variables set in before_script or script are not available for expanding in the same job. Read more about potentially making variables available for expanding.

Skip multiple pipelines when creating a release

Creating a release using a CI/CD job could potentially trigger multiple pipelines if the associated tag does not exist already. To understand how this might happen, consider the following workflows:

  • Tag first, release second:
    1. A tag is created via UI or pushed.
    2. A tag pipeline is triggered, and runs release job.
    3. A release is created.
  • Release first, tag second:
    1. A pipeline is triggered when commits are pushed or merged to default branch. The pipeline runs release job.
    2. A release is created.
    3. A tag is created.
    4. A tag pipeline is triggered. The pipeline also runs release job.

In the second workflow, the release job runs in multiple pipelines. To prevent this, you can use the workflow:rules keyword to determine if a release job should run in a tag pipeline:

release_job:
  rules:
    - if: $CI_COMMIT_TAG  
      when: never                                  # Do not run this job in a tag pipeline
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  # Run this job when commits are pushed or merged to the default branch
  script:
    - echo "Create release"
  release:
    name: 'My awesome release'
    tag_name: '$CI_COMMIT_TAG'

Use a custom SSL CA certificate authority

You can use the ADDITIONAL_CA_CERT_BUNDLE CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when the release-cli creates a release through the API using HTTPS with custom certificates. The ADDITIONAL_CA_CERT_BUNDLE value should contain the text representation of the X.509 PEM public-key certificate or the path/to/file containing the certificate authority. For example, to configure this value in the .gitlab-ci.yml file, use the following:

release:
  variables:
    ADDITIONAL_CA_CERT_BUNDLE: |
        -----BEGIN CERTIFICATE-----
        MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
        ...
        jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
        -----END CERTIFICATE-----
  script:
    - echo "Create release"
  release:
    name: 'My awesome release'
    tag_name: '$CI_COMMIT_TAG'

The ADDITIONAL_CA_CERT_BUNDLE value can also be configured as a custom variable in the UI, either as a file, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.

release-cli command line

The entries under the release node are transformed into Bash commands and sent to the Docker container, which contains the release-cli. You can also call the release-cli directly from a script entry.

For example, if you use the YAML described previously:

release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION