doc/user/project/releases/_index.md
{{< details >}}
{{< /details >}}
Create a release to package your project at critical milestones. Releases combine code, binaries, documentation, and release notes into a complete snapshot of your project. When a release is created, GitLab automatically tags your code, archives a snapshot, and generates audit-ready evidence. This creates a permanent record that's perfect for compliance requirements and can give your users confidence in your development process.
Your users benefit from:
[!warning] Deleting a Git tag associated with a release also deletes the release.
When you create a release, or after, you can:
To view a list of releases:
In the left sidebar, select Deploy > Releases, or
On the project's overview page, if at least one release exists, select the number of 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.
You can access the latest release page through a permanent link. GitLab always redirects the permanent link URL to the address of the latest release page.
The format of the URL is:
https://gitlab.example.com/namespace/project/-/releases/permalink/latest
You can also add a suffix to the permanent link URL. For example, if the latest release is v17.7.0#release in the gitlab-org namespace and gitlab-runner project, the readable link would be:
https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v17.7.0#release
You can access the latest release URL with the following permanent link:
https://gitlab.com/gitlab-org/gitlab-runner/-/releases/permalink/latest#release
To learn about adding permanent links to release assets, see Permanent links to latest release assets.
By default, GitLab fetches the release using released_at time. The use of the query parameter ?order_by=released_at is optional, and support for ?order_by=semver is tracked in this issue.
GitLab provides an RSS feed of a project's releases, in Atom format. To view the feed:
You can create a release:
Prerequisites:
To create a release in the Releases page:
You can create a release directly as part of the GitLab CI/CD pipeline by using the
release keyword in the job definition.
You should likely create a release as one of the last steps in your CI/CD pipeline.
The release is created only if the job processes without error. If the API returns an error during release creation, the release job fails.
The following links show typical example configurations for creating a release using a CI/CD job:
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 glab 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.
A pipeline can have multiple release jobs, for example:
ios-release:
script:
- echo "iOS release job"
release:
tag_name: v1.0.0-ios
description: 'iOS release v1.0.0'
android-release:
script:
- echo "Android release job"
release:
tag_name: v1.0.0-android
description: 'Android release v1.0.0'
You can use Generic packages to host your release assets.
To create a release with packaged assets:
From a CI/CD pipeline, build your package files.
Create a release with the glab CLI job:
Create Release:
stage: release
image: registry.gitlab.com/gitlab-org/cli:latest
rules:
- if: $CI_COMMIT_TAG
script:
- |
glab release create "$CI_COMMIT_TAG" \
--name "Release ${VERSION}" \
--notes "Your release notes here" \
path/to/your/release-asset-file \
--use-package-registry
For every asset you want to include, add an additional --assets-link link.
You can create a release ahead of time by using the Releases API.
When you set a future released_at date, an Upcoming Release badge is displayed next to the
release tag. When the released_at date and time has passed, the badge is automatically removed.
{{< history >}}
{{< /history >}}
You can create a release in the past using either the
Releases API or the UI. When you set
a past released_at date, an Historical release badge is displayed next to
the release tag. Due to being released in the past, release evidence
is not available.
To edit the details of a release after it's created, you can use the Update a release API or the UI.
Prerequisites:
In the UI:
{{< history >}}
{{< /history >}}
When you delete a release, its assets are also deleted. However, the associated Git tag is not deleted. Deleting a Git tag associated with a release also deletes the release.
Prerequisites:
To delete a release, use either the Delete a release API or the UI.
In the UI:
You can associate a release with one or more project milestones.
GitLab Premium customers can specify group milestones to associate with a release.
You can do this in the user interface, or by including a milestones array in your request to
the Releases API.
In the user interface, to associate milestones to a release:
On the Deploy > Releases page, the Milestone is listed in the top section, along with statistics about the issues in the milestones.
Releases are also visible on the Plan > Milestones page, and when you select a milestone on this page.
Here is an example of milestones with no releases, one release, and two releases.
[!note] A subgroup's project releases cannot be associated with a parent group's milestone. To learn more, read issue #328054, Releases cannot be associated with a supergroup milestone.
You can be notified by email when a new release is created for your project.
To subscribe to notifications for releases:
Prevent unintended production releases during a period of time you specify by setting a deploy freeze period. Deploy freezes help reduce uncertainty and risk when automating deployments.
A maintainer can set a deploy freeze window in the user interface or by using the Freeze Periods API to set a freeze_start and a freeze_end, which
are defined as crontab entries.
If the job that's executing is in a freeze period, GitLab CI/CD creates an environment
variable named $CI_DEPLOY_FREEZE.
To prevent the deployment job from executing in multiple projects in a group,
define the .freezedeployment job in a file shared across the group.
Use the includes keyword to incorporate the
template in your project's .gitlab-ci.yml file:
.freezedeployment:
stage: deploy
before_script:
- '[[ ! -z "$CI_DEPLOY_FREEZE" ]] && echo "INFRASTRUCTURE OUTAGE WINDOW" && exit 1; '
rules:
- if: '$CI_DEPLOY_FREEZE'
when: manual
allow_failure: true
- when: on_success
To prevent the deployment job from executing, use the extends keyword in the deploy_to_production job of your .gitlab-ci.yml file to inherit the configuration from the .freezedeployment template job:
deploy_to_production:
extends: .freezedeployment
script: deploy_to_prod.sh
environment: production
This configuration blocks deployment jobs conditionally and maintains pipeline continuity. When a freeze period is defined, the job fails and the pipeline can proceed without deployment. Manual deployment is possible after the freeze period.
This approach offers deployment control during critical maintenance, and ensures the uninterrupted flow of the CI/CD pipeline.
To set a deploy freeze window in the UI, complete these steps:
If a project contains multiple freeze periods, all periods apply. If they overlap, the freeze covers the complete overlapping period.
For more information, see Deployment safety.
{{< history >}}
{{< /history >}}
You can make releases accessible to non-project members while keeping repository-related information, such as source code and release evidence, available only to project members. These settings are ideal for projects that use releases to give access to new versions of software, but do not want the source code to be publicly available.
To make releases available publicly, set the following project settings:
As an example of release permission control, you can allow only
users with the Maintainer or Owner role
to create, update, and delete releases by protecting the tag with a wildcard (*),
and set Maintainer in the Allowed to create column.
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Group-level release metrics are available by navigating to Group > Analytics > CI/CD. These metrics include:
The Guided Exploration project Utterly Automated Software and Artifact Versioning with GitVersion demonstrates:
You can copy the example project to your own group or instance for testing. More details on what other GitLab CI patterns are demonstrated are available at the project page.
If the release is associated with a protected tag, the UI/API request might result in an authorization failures, such as:
403 ForbiddenSomething went wrong while creating a new releaseMake sure that the user or a service/bot account is allowed to create the protected tag too.
See the release permissions for more information.
This feature is built on top of Git tags, so virtually no extra data is needed besides to create the release itself. Additional assets and the release evidence that is automatically generated consume storage.
The way of using the release keyword is planned to change.
The release-cli tool is being replaced by the GitLab CLI tool.
You must use GitLab CLI tool v1.58.0 or higher, or you could receive one of these error messages or warnings:
Error: glab command not found. Please install glab v1.58.0 or higher.Error: Please use glab v1.58.0 or higher.Warning: release-cli will not be supported after 20.0. Please use glab version >= 1.58.0.There are two ways to have the GitLab CLI tool:
registry.gitlab.com/gitlab-org/release-cli:<version> container image,
you can start using either registry.gitlab.com/gitlab-org/cli:v1.58.0 or
registry.gitlab.com/gitlab-org/release-cli:v0.24.0, which contains glab v1.58.0.v1.58.0.