diff options
Diffstat (limited to 'doc/user/project/releases')
| -rw-r--r-- | doc/user/project/releases/index.md | 22 | ||||
| -rw-r--r-- | doc/user/project/releases/release_cicd_examples.md | 73 | ||||
| -rw-r--r-- | doc/user/project/releases/release_cli.md | 2 |
3 files changed, 81 insertions, 16 deletions
diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index d3456e086ce..87ea95524fe 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -57,8 +57,6 @@ switch between ascending or descending order, select **Sort order**. ## Create a release -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32812) in GitLab 12.9. Releases can be created directly in the GitLab UI. - You can create a release: - [Using a job in your CI/CD pipeline](#creating-a-release-by-using-a-cicd-job). @@ -68,16 +66,16 @@ You can create a release: We recommend creating a release as one of the last steps in your CI/CD pipeline. +### Create a release in the Releases page + Prerequisites: - You must have at least the Developer role for a project. For more information, read [Release permissions](#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. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases** and select **New release**. 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 @@ -99,7 +97,7 @@ To create a release in the Tags page, add release notes to either an existing or To add release notes to a new Git tag: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Tags**. 1. Select **New tag**. 1. Optional. Enter a tag message in the **Message** text box. @@ -109,7 +107,7 @@ To add release notes to a new Git tag: To edit release notes of an existing Git tag: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Tags**. 1. Select **Edit release notes** (**{pencil}**). 1. In the **Release notes** text box, enter the release's description. @@ -124,8 +122,11 @@ 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. -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). +Methods for creating a release using a CI/CD job include: + +- [Create a release when a Git tag is created](release_cicd_examples.md#create-a-release-when-a-git-tag-is-created). +- [Create a release when a commit is merged to the default branch](release_cicd_examples.md#create-a-release-when-a-commit-is-merged-to-the-default-branch). +- [Create release metadata in a custom script](release_cicd_examples.md#create-release-metadata-in-a-custom-script). ### Use a custom SSL CA certificate authority @@ -232,7 +233,7 @@ Prerequisites: To delete a release in the UI: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases**. 1. In the top-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). 1. On the **Edit Release** page, select **Delete**. @@ -312,6 +313,7 @@ deploy_to_production: script: deploy_to_prod.sh rules: - if: $CI_DEPLOY_FREEZE == null + environment: production ``` To set a deploy freeze window in the UI, complete these steps: diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md index f1d3e55a707..bfd83a20caf 100644 --- a/doc/user/project/releases/release_cicd_examples.md +++ b/doc/user/project/releases/release_cicd_examples.md @@ -12,9 +12,13 @@ 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. +In this CI/CD example, the release is triggered by one of the following events: + +- Pushing a Git tag to the repository. +- Creating a Git tag in the UI. + +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 @@ -40,8 +44,8 @@ release_job: ## 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. +In this CI/CD example, the release is triggered when you merge a commit to the default branch. 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: @@ -69,16 +73,75 @@ Environment variables set in `before_script` or `script` are not available for e in the same job. Read more about [potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). +## Create release metadata in a custom script + +In this CI/CD example the release preparation is split into separate jobs for greater flexibility: + +- The `prepare_job` job generates the release metadata. Any image can be used to run the job, + including a custom image. The generated metadata is stored in the variable file `variables.env`. + This metadata is [passed to the downstream job](../../../ci/variables/index.md#pass-an-environment-variable-to-another-job). +- The `release_job` uses the content from the variables file to create a release, using the + metadata passed to it in the variables file. This job must use the + `registry.gitlab.com/gitlab-org/release-cli:latest` image because it contains the release CLI. + +```yaml +prepare_job: + stage: prepare # This stage must run before the release stage + 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 "EXTRA_DESCRIPTION=some message" >> variables.env # Generate the EXTRA_DESCRIPTION and TAG environment variables + - echo "TAG=v$(cat VERSION)" >> variables.env # and append to the variables.env file + artifacts: + reports: + dotenv: variables.env # Use artifacts:reports:dotenv to expose the variables to other jobs + +release_job: + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + needs: + - job: prepare_job + artifacts: true + 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: + name: 'Release $TAG' + description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the $TAG + tag_name: '$TAG' # variables must be defined elsewhere + ref: '$CI_COMMIT_SHA' # in the pipeline. For example, in the + milestones: # prepare_job + - 'm1' + - 'm2' + - 'm3' + released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. + assets: + links: + - name: 'asset1' + url: 'https://example.com/assets/1' + - name: 'asset2' + url: 'https://example.com/assets/2' + filepath: '/pretty/url/1' # optional + link_type: 'other' # optional +``` + ## 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. diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index 9e65ab4bc01..90363fca8b0 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -46,7 +46,7 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av Or from the GitLab Package Registry: ```shell - curl --location --output /usr/local/bin/release-cli "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-darwin-amd64" + curl --location --output /usr/local/bin/release-cli "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-linux-amd64" ``` 1. Give it permissions to execute: |