diff options
Diffstat (limited to 'doc/user/project/releases')
| -rw-r--r-- | doc/user/project/releases/index.md | 423 | ||||
| -rw-r--r-- | doc/user/project/releases/release_cicd_examples.md | 100 | ||||
| -rw-r--r-- | doc/user/project/releases/release_cli.md | 30 | ||||
| -rw-r--r-- | doc/user/project/releases/release_fields.md | 274 |
4 files changed, 421 insertions, 406 deletions
diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 1d448ca5c94..d3456e086ce 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -32,12 +32,10 @@ When you create a release, or after, you can: - Add release notes. - Add a message for the Git tag associated with the release. - [Associate milestones with it](#associate-milestones-with-a-release). -- Attach [release assets](#release-assets), like runbooks or packages. +- Attach [release assets](release_fields.md#release-assets), like runbooks or packages. ## View releases -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36667) in GitLab 12.8. - To view a list of releases: - On the left sidebar, select **Deployments > Releases**, or @@ -81,18 +79,18 @@ To create a release in the Releases page: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases** and select **New release**. -1. From the [**Tag name**](#tag-name) dropdown, either: +1. From the [**Tag name**](release_fields.md#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. 1. Optional. Enter additional information about the release, including: - - [Title](#title). + - [Title](release_fields.md#title). - [Milestones](#associate-milestones-with-a-release). - - [Release notes](#release-notes-description). + - [Release notes](release_fields.md#release-notes-description). - Whether or not to include the [Tag message](../../../topics/git/tags.md). - - [Asset links](#links). + - [Asset links](release_fields.md#links). 1. Select **Create release**. ### Create a release in the Tags page @@ -126,99 +124,8 @@ You can create a release directly as part of the GitLab CI/CD pipeline by using 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. - -```yaml -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. - -```yaml -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](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). - -#### 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. - 1. A tag pipeline is triggered, and runs `release` job. - 1. 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. - 1. A release is created. - 1. A tag is created. - 1. 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](../../../ci/yaml/index.md#workflowrules) to determine if a release job should run in a tag pipeline: - -```yaml -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' -``` +For examples of how you can create a release of your application in the CI/CD pipeline, +see [Release CI/CD examples](release_cicd_examples.md). ### Use a custom SSL CA certificate authority @@ -250,18 +157,6 @@ The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a 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](https://gitlab.com/gitlab-org/release-cli). -You can also call the `release-cli` directly from a `script` entry. - -For example, if you use the YAML described previously: - -```shell -release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"} -``` - ### Create multiple releases in a single pipeline A pipeline can have multiple `release` jobs, for example: @@ -298,10 +193,17 @@ release tag. When the `released_at` date and time has passed, the badge is autom  -## Edit a release +## Historical releases + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199429) in GitLab 15.2. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26016) in GitLab 12.6. -> - Asset link editing [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10. +You can create a release in the past using either the +[Releases API](../../../api/releases/index.md#historical-releases) 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](#release-evidence) +is not available. + +## Edit a release Only users with at least the Developer role can edit releases. Read more about [Release permissions](#release-permissions). @@ -430,277 +332,6 @@ complete overlapping period. For more information, see [Deployment safety](../../../ci/environments/deployment_safety.md). -## Release fields - -The following fields are available when you create or edit a release. - -### Title - -The release title can be customized using the **Release title** field when -creating or editing a release. If no title is provided, the release's tag name -is used instead. - -### Tag name - -The release tag name should include the release version. GitLab uses [Semantic Versioning](https://semver.org/) -for our releases, and we recommend you do too. Use `(Major).(Minor).(Patch)`, as detailed in the -[GitLab Policy for Versioning](../../../policy/maintenance.md#versioning). - -For example, for GitLab version `10.5.7`: - -- `10` represents the major version. The major release was `10.0.0`, but often referred to as `10.0`. -- `5` represents the minor version. The minor release was `10.5.0`, but often referred to as `10.5`. -- `7` represents the patch number. - -Any part of the version number can be multiple digits, for example, `13.10.11`. - -### Release notes description - -Every release has a description. You can add any text you like, but we recommend -including a changelog to describe the content of your release. This helps users -quickly scan the differences between each release you publish. - -[Git's tagging messages](https://git-scm.com/book/en/v2/Git-Basics-Tagging) can -be included in Release note descriptions by selecting **Include tag message in -the release notes**. - -Description supports [Markdown](../../markdown.md). - -### Release assets - -A release contains the following types of assets: - -- [Source code](#source-code) -- [Link](#links) - -#### Source code - -GitLab automatically generates `zip`, `tar.gz`, `tar.bz2`, and `tar` -archived source code from the given Git tag. These are read-only assets. - -#### Links - -A link is any URL which can point to whatever you like: documentation, built -binaries, or other related materials. These can be both internal or external -links from your GitLab instance. -Each link as an asset has the following attributes: - -| Attribute | Description | Required | -| ---- | ----------- | --- | -| `name` | The name of the link. | Yes | -| `url` | The URL to download a file. | Yes | -| `filepath` | The redirect link to the `url`. See [this section](#permanent-links-to-release-assets) for more information. | No | -| `link_type` | The content kind of what users can download via `url`. See [this section](#link-types) for more information. | No | - -##### Permanent link to latest release - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. - -Latest release page is accessible through a permanent URL. -GitLab will redirect to the latest release page URL when it is visited. - -The format of the URL is: - -```plaintext -https://host/namespace/project/-/releases/permalink/latest -``` - -We also support, suffix path carry forward on the redirect to the latest release. -Example if release `v14.8.0-ee` is the latest release and has a readable link `https://host/namespace/project/-/releases/v14.8.0-ee#release` then it can be addressed as `https://host/namespace/project/-/releases/permalink/latest#release`. - -Refer [permanent links to latest release assets](#permanent-links-to-latest-release-assets) section to understand more about the suffix path carry forward usage. - -###### Sorting preferences - -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](https://gitlab.com/gitlab-org/gitlab/-/issues/352945). - -##### Permanent links to release assets - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27300) in GitLab 12.9. - -The assets associated with a release are accessible through a permanent URL. -GitLab always redirects this URL to the actual asset -location, so even if the assets move to a different location, you can continue -to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link) using the `filepath` API attribute. - -The format of the URL is: - -```plaintext -https://host/namespace/project/-/releases/:release/downloads/:filepath -``` - -If you have an asset for the `v11.9.0-rc2` release in the `gitlab-org` -namespace and `gitlab-runner` project on `gitlab.com`, for example: - -```json -{ - "name": "linux amd64", - "filepath": "/binaries/gitlab-runner-linux-amd64", - "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", - "link_type": "other" -} -``` - -This asset has a direct link of: - -```plaintext -https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v11.9.0-rc2/downloads/binaries/gitlab-runner-linux-amd64 -``` - -The physical location of the asset can change at any time and the direct link remains unchanged. - -##### Permanent links to latest release assets - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. - -The `filepath` from [permanent links to release assets](#permanent-links-to-release-assets) can be used in combination with [permanent link to the latest release](#permanent-link-to-latest-release). It is useful when we want to link a permanent URL to download an asset from the *latest release*. - -The format of the URL is: - -```plaintext -https://host/namespace/project/-/releases/permalink/latest/downloads/:filepath -``` - -If you have an asset with [`filepath`](../../../api/releases/links.md#create-a-link) for the `v11.9.0-rc2` latest release in the `gitlab-org` -namespace and `gitlab-runner` project on `gitlab.com`, for example: - -```json -{ - "name": "linux amd64", - "filepath": "/binaries/gitlab-runner-linux-amd64", - "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", - "link_type": "other" -} -``` - -This asset has a direct link of: - -```plaintext -https://gitlab.com/gitlab-org/gitlab-runner/-/releases/permalink/latest/downloads/binaries/gitlab-runner-linux-amd64 -``` - -##### Link Types - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207257) in GitLab 13.1. - -The four types of links are "Runbook," "Package," "Image," and "Other." -The `link_type` parameter accepts one of the following four values: - -- `runbook` -- `package` -- `image` -- `other` (default) - -This field has no effect on the URL and it's only used for visual purposes in the Releases page of your project. - -##### Use a generic package for attaching binaries - -You can use [generic packages](../../packages/generic_packages/index.md) -to store any artifacts from a release or tag pipeline, -that can also be used for attaching binary files to an individual release entry. -You basically need to: - -1. [Push the artifacts to the Generic Package Registry](../../packages/generic_packages/index.md#publish-a-package-file). -1. [Attach the package link to the release](#links). - -The following example generates release assets, publishes them -as a generic package, and then creates a release: - -```yaml -stages: - - build - - upload - - release - -variables: - # Package version can only contain numbers (0-9), and dots (.). - # Must be in the format of X.Y.Z, i.e. should match /\A\d+\.\d+\.\d+\z/ regular expresion. - # See https://docs.gitlab.com/ee/user/packages/generic_packages/#publish-a-package-file - PACKAGE_VERSION: "1.2.3" - DARWIN_AMD64_BINARY: "myawesomerelease-darwin-amd64-${PACKAGE_VERSION}" - LINUX_AMD64_BINARY: "myawesomerelease-linux-amd64-${PACKAGE_VERSION}" - PACKAGE_REGISTRY_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/myawesomerelease/${PACKAGE_VERSION}" - -build: - stage: build - image: alpine:latest - rules: - - if: $CI_COMMIT_TAG - script: - - mkdir bin - - echo "Mock binary for ${DARWIN_AMD64_BINARY}" > bin/${DARWIN_AMD64_BINARY} - - echo "Mock binary for ${LINUX_AMD64_BINARY}" > bin/${LINUX_AMD64_BINARY} - artifacts: - paths: - - bin/ - -upload: - stage: upload - image: curlimages/curl:latest - rules: - - if: $CI_COMMIT_TAG - script: - - | - curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${DARWIN_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}" - - | - curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${LINUX_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}" - -release: - # Caution, as of 2021-02-02 these assets links require a login, see: - # https://gitlab.com/gitlab-org/gitlab/-/issues/299384 - stage: release - image: registry.gitlab.com/gitlab-org/release-cli:latest - rules: - - if: $CI_COMMIT_TAG - script: - - | - release-cli create --name "Release $CI_COMMIT_TAG" --tag-name $CI_COMMIT_TAG \ - --assets-link "{\"name\":\"${DARWIN_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}\"}" \ - --assets-link "{\"name\":\"${LINUX_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}\"}" -``` - -PowerShell users may need to escape the double quote `"` inside a JSON -string with a `` ` `` (back tick) for `--assets-link` and `ConvertTo-Json` -before passing on to the `release-cli`. -For example: - -```yaml -release: - script: - - $env:asset = "{`"name`":`"MyFooAsset`",`"url`":`"https://gitlab.com/upack/artifacts/download/$env:UPACK_GROUP/$env:UPACK_NAME/$($env:GitVersion_SemVer)?contentOnly=zip`"}" - - $env:assetjson = $env:asset | ConvertTo-Json - - release-cli create --name $CI_COMMIT_TAG --description "Release $CI_COMMIT_TAG" --ref $CI_COMMIT_TAG --tag-name $CI_COMMIT_TAG --assets-link=$env:assetjson -``` - -NOTE: -Directly attaching [job artifacts](../../../ci/pipelines/job_artifacts.md) -links to a release is not recommended, because artifacts are ephemeral and -are used to pass data in the same pipeline. This means there's a risk that -they could either expire or someone might manually delete them. - -#### Number of new and total features **(FREE SAAS)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235618) in GitLab 13.5. - -On [GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/releases), you can view the number of new and total features in the project. - - - -The totals are displayed on [shields](https://shields.io/) and are generated per release by -[a Rake task in the `www-gitlab-com` repository](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/tasks/update_gitlab_project_releases_page.rake). - -| Item | Formula | -| ------ | ------ | -| `New features` | Total count of release posts across all tiers for a single release in the project. | -| `Total features` | Total count of release posts in reverse order for all releases in the project. | - -The counts are also shown by license tier. - -| Item | Formula | -| ------ | ------ | -| `New features` | Total count of release posts across a single tier for a single release in the project. | -| `Total features` | Total count of release posts across a single tier in reverse order for all releases in the project. | - ## Release evidence > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. @@ -828,10 +459,11 @@ keyword. Learn more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issue In the API: -- If you specify a future `released_at` date, the release becomes an **Upcoming Release** +- If you specify a future `released_at` date, the release becomes an **Upcoming release** and the evidence is collected on the date of the release. You cannot collect release evidence before then. -- If you use a past `released_at` date, no evidence is collected. +- If you specify a past `released_at` date, the release becomes an **Historical + release** and no evidence is collected. - If you do not specify a `released_at` date, release evidence is collected on the date the release is created. @@ -848,7 +480,7 @@ In the API: - Users with the Guest role have read and download access to the project releases. This includes associated Git-tag-names, release description, author information of the releases. - However, other repository-related information, such as [source code](#source-code), [release evidence](#release-evidence) are redacted. + However, other repository-related information, such as [source code](release_fields.md#source-code), [release evidence](#release-evidence) are redacted. ### Create, update, and delete a release and its assets @@ -862,19 +494,6 @@ users with at least the Maintainer role to create, update, and delete releases by protecting the tag with a wildcard (`*`), and set **Maintainer** in the **Allowed to create** column. -## Release Command Line - -> [Introduced](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/6) in GitLab 12.10. - -The Release CLI is a command-line tool for managing GitLab Releases from the command line or from -the GitLab CI/CD configuration file, `.gitlab-ci.yml`. - -With it, you can create, update, modify, and delete releases right through the -terminal. - -Read the [Release CLI documentation](https://gitlab.com/gitlab-org/release-cli/-/blob/master/docs/index.md) -for details. - ## Release Metrics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259703) in GitLab Premium 13.9. diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md new file mode 100644 index 00000000000..f1d3e55a707 --- /dev/null +++ b/doc/user/project/releases/release_cicd_examples.md @@ -0,0 +1,100 @@ +--- +stage: Release +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Release CI/CD examples + +GitLab release functionality is flexible, able to be configured to match your workflow. This page +features example CI/CD release jobs. Each example demonstrates a method of creating a release in a +CI/CD pipeline. + +## 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. + +```yaml +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. + +```yaml +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](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). + +## 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. + 1. A tag pipeline is triggered, and runs `release` job. + 1. 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. + 1. A release is created. + 1. A tag is created. + 1. 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](../../../ci/yaml/index.md#workflowrules) to determine if a release job should run in a tag pipeline: + +```yaml +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' +``` diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index b55f0b0a734..9e65ab4bc01 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -4,16 +4,38 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install the `release-cli` for the Shell executor **(FREE)** + +# GitLab Release CLI tool + +The [GitLab Release CLI (`release-cli`)](https://gitlab.com/gitlab-org/release-cli) tool +is a command-line tool for managing releases from the command line or from a CI/CD pipeline. +You can use the release CLI to create, update, modify, and delete releases. + +When you [use a CI/CD job to create a release](index.md#creating-a-release-by-using-a-cicd-job), +the `release` keyword entries are transformed into Bash commands and sent to the Docker +container containing the `release-cli` tool. The tool then creates the release. + +You can also call the `release-cli` tool directly from a [`script`](../../../ci/yaml/index.md#script). +For example: + +```shell +release-cli create --name "Release $CI_COMMIT_SHA" --description \ + "Created using the release-cli $EXTRA_DESCRIPTION" \ + --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" \ + --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" \ + --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"} +``` + +## Install the `release-cli` for the Shell executor **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8. -> - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/jaime/release-cli/-/packages). +> - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/gitlab-org/release-cli/-/packages). When you use a runner with the Shell executor, you can download and install the `release-cli` manually for your [supported OS and architecture](https://release-cli-downloads.s3.amazonaws.com/latest/index.html). Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is available to use in your CI/CD jobs. -## Install on Unix/Linux +### Install on Unix/Linux 1. Download the binary for your system from S3, in the following example for amd64 systems: @@ -41,7 +63,7 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av release-cli version 0.6.0 ``` -## Install on Windows PowerShell +### Install on Windows PowerShell 1. Create a folder somewhere in your system, for example `C:\GitLab\Release-CLI\bin` diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md new file mode 100644 index 00000000000..647cac9c38e --- /dev/null +++ b/doc/user/project/releases/release_fields.md @@ -0,0 +1,274 @@ +--- +stage: Release +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Release fields + +The following fields are available when you create or edit a release. + +## Title + +The release title can be customized using the **Release title** field when +creating or editing a release. If no title is provided, the release's tag name +is used instead. + +## Tag name + +The release tag name should include the release version. GitLab uses [Semantic Versioning](https://semver.org/) +for our releases, and we recommend you do too. Use `(Major).(Minor).(Patch)`, as detailed in the +[GitLab Policy for Versioning](../../../policy/maintenance.md#versioning). + +For example, for GitLab version `10.5.7`: + +- `10` represents the major version. The major release was `10.0.0`, but often referred to as `10.0`. +- `5` represents the minor version. The minor release was `10.5.0`, but often referred to as `10.5`. +- `7` represents the patch number. + +Any part of the version number can be multiple digits, for example, `13.10.11`. + +## Release notes description + +Every release has a description. You can add any text you like, but we recommend +including a changelog to describe the content of your release. This helps users +quickly scan the differences between each release you publish. + +[Git's tagging messages](https://git-scm.com/book/en/v2/Git-Basics-Tagging) can +be included in Release note descriptions by selecting **Include tag message in +the release notes**. + +Description supports [Markdown](../../markdown.md). + +## Release assets + +A release contains the following types of assets: + +- [Source code](#source-code) +- [Link](#links) + +### Source code + +GitLab automatically generates `zip`, `tar.gz`, `tar.bz2`, and `tar` +archived source code from the given Git tag. These are read-only assets. + +### Links + +A link is any URL which can point to whatever you like: documentation, built +binaries, or other related materials. These can be both internal or external +links from your GitLab instance. +Each link as an asset has the following attributes: + +| Attribute | Description | Required | +|-------------|--------------------------------------------------------------------------------------------------------------|----------| +| `name` | The name of the link. | Yes | +| `url` | The URL to download a file. | Yes | +| `filepath` | The redirect link to the `url`. See [this section](#permanent-links-to-release-assets) for more information. | No | +| `link_type` | The content kind of what users can download via `url`. See [this section](#link-types) for more information. | No | + +#### Permanent link to latest release + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. + +Latest release page is accessible through a permanent URL. +GitLab redirects to the latest release page URL when it is visited. + +The format of the URL is: + +```plaintext +https://host/namespace/project/-/releases/permalink/latest +``` + +We also support, suffix path carry forward on the redirect to the latest release. +Example if release `v14.8.0-ee` is the latest release and has a readable link `https://host/namespace/project/-/releases/v14.8.0-ee#release` then it can be addressed as `https://host/namespace/project/-/releases/permalink/latest#release`. + +Refer [permanent links to latest release assets](#permanent-links-to-latest-release-assets) section to understand more about the suffix path carry forward usage. + +##### Sorting preferences + +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](https://gitlab.com/gitlab-org/gitlab/-/issues/352945). + +#### Permanent links to release assets + +The assets associated with a release are accessible through a permanent URL. +GitLab always redirects this URL to the actual asset +location, so even if the assets move to a different location, you can continue +to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link) using the `filepath` API attribute. + +The format of the URL is: + +```plaintext +https://host/namespace/project/-/releases/:release/downloads/:filepath +``` + +If you have an asset for the `v11.9.0-rc2` release in the `gitlab-org` +namespace and `gitlab-runner` project on `gitlab.com`, for example: + +```json +{ + "name": "linux amd64", + "filepath": "/binaries/gitlab-runner-linux-amd64", + "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", + "link_type": "other" +} +``` + +This asset has a direct link of: + +```plaintext +https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v11.9.0-rc2/downloads/binaries/gitlab-runner-linux-amd64 +``` + +The physical location of the asset can change at any time and the direct link remains unchanged. + +#### Permanent links to latest release assets + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. + +The `filepath` from [permanent links to release assets](#permanent-links-to-release-assets) can be used in combination with [permanent link to the latest release](#permanent-link-to-latest-release). It is useful when we want to link a permanent URL to download an asset from the *latest release*. + +The format of the URL is: + +```plaintext +https://host/namespace/project/-/releases/permalink/latest/downloads/:filepath +``` + +If you have an asset with [`filepath`](../../../api/releases/links.md#create-a-link) for the `v11.9.0-rc2` latest release in the `gitlab-org` +namespace and `gitlab-runner` project on `gitlab.com`, for example: + +```json +{ + "name": "linux amd64", + "filepath": "/binaries/gitlab-runner-linux-amd64", + "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", + "link_type": "other" +} +``` + +This asset has a direct link of: + +```plaintext +https://gitlab.com/gitlab-org/gitlab-runner/-/releases/permalink/latest/downloads/binaries/gitlab-runner-linux-amd64 +``` + +#### Link Types + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207257) in GitLab 13.1. + +The four types of links are "Runbook," "Package," "Image," and "Other." +The `link_type` parameter accepts one of the following four values: + +- `runbook` +- `package` +- `image` +- `other` (default) + +This field has no effect on the URL and it's only used for visual purposes in the Releases page of your project. + +#### Use a generic package for attaching binaries + +You can use [generic packages](../../packages/generic_packages/index.md) +to store any artifacts from a release or tag pipeline, +that can also be used for attaching binary files to an individual release entry. +You basically need to: + +1. [Push the artifacts to the Generic Package Registry](../../packages/generic_packages/index.md#publish-a-package-file). +1. [Attach the package link to the release](#links). + +The following example generates release assets, publishes them +as a generic package, and then creates a release: + +```yaml +stages: + - build + - upload + - release + +variables: + # Package version can only contain numbers (0-9), and dots (.). + # Must be in the format of X.Y.Z, i.e. should match /\A\d+\.\d+\.\d+\z/ regular expresion. + # See https://docs.gitlab.com/ee/user/packages/generic_packages/#publish-a-package-file + PACKAGE_VERSION: "1.2.3" + DARWIN_AMD64_BINARY: "myawesomerelease-darwin-amd64-${PACKAGE_VERSION}" + LINUX_AMD64_BINARY: "myawesomerelease-linux-amd64-${PACKAGE_VERSION}" + PACKAGE_REGISTRY_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/myawesomerelease/${PACKAGE_VERSION}" + +build: + stage: build + image: alpine:latest + rules: + - if: $CI_COMMIT_TAG + script: + - mkdir bin + - echo "Mock binary for ${DARWIN_AMD64_BINARY}" > bin/${DARWIN_AMD64_BINARY} + - echo "Mock binary for ${LINUX_AMD64_BINARY}" > bin/${LINUX_AMD64_BINARY} + artifacts: + paths: + - bin/ + +upload: + stage: upload + image: curlimages/curl:latest + rules: + - if: $CI_COMMIT_TAG + script: + - | + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${DARWIN_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}" + - | + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${LINUX_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}" + +release: + # Caution, as of 2021-02-02 these assets links require a login, see: + # https://gitlab.com/gitlab-org/gitlab/-/issues/299384 + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + rules: + - if: $CI_COMMIT_TAG + script: + - | + release-cli create --name "Release $CI_COMMIT_TAG" --tag-name $CI_COMMIT_TAG \ + --assets-link "{\"name\":\"${DARWIN_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}\"}" \ + --assets-link "{\"name\":\"${LINUX_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}\"}" +``` + +PowerShell users may need to escape the double quote `"` inside a JSON +string with a `` ` `` (back tick) for `--assets-link` and `ConvertTo-Json` +before passing on to the `release-cli`. +For example: + +```yaml +release: + script: + - $env:asset = "{`"name`":`"MyFooAsset`",`"url`":`"https://gitlab.com/upack/artifacts/download/$env:UPACK_GROUP/$env:UPACK_NAME/$($env:GitVersion_SemVer)?contentOnly=zip`"}" + - $env:assetjson = $env:asset | ConvertTo-Json + - release-cli create --name $CI_COMMIT_TAG --description "Release $CI_COMMIT_TAG" --ref $CI_COMMIT_TAG --tag-name $CI_COMMIT_TAG --assets-link=$env:assetjson +``` + +NOTE: +Directly attaching [job artifacts](../../../ci/pipelines/job_artifacts.md) +links to a release is not recommended, because artifacts are ephemeral and +are used to pass data in the same pipeline. This means there's a risk that +they could either expire or someone might manually delete them. + +### Number of new and total features **(FREE SAAS)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235618) in GitLab 13.5. + +On [GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/releases), you can view the number of new and total features in the project. + + + +The totals are displayed on [shields](https://shields.io/) and are generated per release by +[a Rake task in the `www-gitlab-com` repository](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/tasks/update_gitlab_project_releases_page.rake). + +| Item | Formula | +|------------------|------------------------------------------------------------------------------------| +| `New features` | Total count of release posts across all tiers for a single release in the project. | +| `Total features` | Total count of release posts in reverse order for all releases in the project. | + +The counts are also shown by license tier. + +| Item | Formula | +|------------------|-----------------------------------------------------------------------------------------------------| +| `New features` | Total count of release posts across a single tier for a single release in the project. | +| `Total features` | Total count of release posts across a single tier in reverse order for all releases in the project. | |