diff options
Diffstat (limited to 'doc/ci/yaml/README.md')
-rw-r--r-- | doc/ci/yaml/README.md | 966 |
1 files changed, 717 insertions, 249 deletions
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 9329748e396..49daa2b17fb 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -92,19 +92,19 @@ These job keywords can be defined inside a `default:` section: - [`tags`](#tags) - [`timeout`](#timeout) -The following example sets the `ruby:2.5` image as the default for all jobs in the pipeline. -The `rspec 2.6` job does not use the default, because it overrides the default with +The following example sets the `ruby:3.0` image as the default for all jobs in the pipeline. +The `rspec 2.7` job does not use the default, because it overrides the default with a job-specific `image:` section: ```yaml default: - image: ruby:2.5 + image: ruby:3.0 rspec: script: bundle exec rspec -rspec 2.6: - image: ruby:2.6 +rspec 2.7: + image: ruby:2.7 script: bundle exec rspec ``` @@ -172,6 +172,7 @@ a preconfigured `workflow: rules` entry. - [`when`](#when): Specify what to do when the `if` rule evaluates to true. - To run a pipeline, set to `always`. - To prevent pipelines from running, set to `never`. +- [`variables`](#workflowrulesvariables): If not defined, uses the [variables defined elsewhere](#variables). When no rules evaluate to true, the pipeline does not run. @@ -222,6 +223,87 @@ request pipelines. If your rules match both branch pipelines and merge request pipelines, [duplicate pipelines](#avoid-duplicate-pipelines) can occur. +#### `workflow:rules:variables` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294232) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-workflowrulesvariables). **(CORE ONLY)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can use [`variables`](#variables) in `workflow:rules:` to define variables for specific pipeline conditions. + +For example: + +```yaml +variables: + DEPLOY_VARIABLE: "default-deploy" + +workflow: + rules: + - if: $CI_COMMIT_REF_NAME =~ /master/ + variables: + DEPLOY_VARIABLE: "deploy-production" # Override globally-defined DEPLOY_VARIABLE + - if: $CI_COMMIT_REF_NAME =~ /feature/ + variables: + IS_A_FEATURE: "true" # Define a new variable. + - when: always # Run the pipeline in other cases + +job1: + variables: + DEPLOY_VARIABLE: "job1-default-deploy" + rules: + - if: $CI_COMMIT_REF_NAME =~ /master/ + variables: # Override DEPLOY_VARIABLE defined + DEPLOY_VARIABLE: "job1-deploy-production" # at the job level. + - when: on_success # Run the job in other cases + script: + - echo "Run script with $DEPLOY_VARIABLE as an argument" + - echo "Run another script if $IS_A_FEATURE exists" + +job2: + script: + - echo "Run script with $DEPLOY_VARIABLE as an argument" + - echo "Run another script if $IS_A_FEATURE exists" +``` + +When the branch is `master`: + +- job1's `DEPLOY_VARIABLE` is `job1-deploy-production`. +- job2's `DEPLOY_VARIABLE` is `deploy-production`. + +When the branch is `feature`: + +- job1's `DEPLOY_VARIABLE` is `job1-default-deploy`, and `IS_A_FEATURE` is `true`. +- job2's `DEPLOY_VARIABLE` is `default-deploy`, and `IS_A_FEATURE` is `true`. + +When the branch is something else: + +- job1's `DEPLOY_VARIABLE` is `job1-default-deploy`. +- job2's `DEPLOY_VARIABLE` is `default-deploy`. + +##### Enable or disable workflow:rules:variables **(CORE ONLY)** + +rules:variables is under development and not ready for production use. +It is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:ci_workflow_rules_variables) +``` + +To disable it: + +```ruby +Feature.disable(:ci_workflow_rules_variables) +``` + #### `workflow:rules` templates > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0. @@ -395,6 +477,41 @@ include: '.gitlab-ci-production.yml' Use local includes instead of symbolic links. +##### `include:local` with wildcard file paths + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25921) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it. **(CORE ONLY)** + +You can use wildcard paths (`*`) with `include:local`. + +Example: + +```yaml +include: 'configs/*.yml' +``` + +When the pipeline runs, it adds all `.yml` files in the `configs` folder into the pipeline configuration. + +The wildcard file paths feature is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:ci_wildcard_file_paths) +``` + +To disable it: + +```ruby +Feature.disable(:ci_wildcard_file_paths) +``` + #### `include:file` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7. @@ -512,7 +629,7 @@ Use `image` to specify [a Docker image](../docker/using_docker_images.md#what-is For: -- Usage examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). +- Usage examples, see [Define `image` in the `.gitlab-ci.yml` file](../docker/using_docker_images.md#define-image-in-the-gitlab-ciyml-file). - Detailed usage information, refer to [Docker integration](../docker/index.md) documentation. #### `image:name` @@ -529,11 +646,11 @@ For more information, see [Available settings for `image`](../docker/using_docke #### `services` -Use `services` to specify a [service Docker image](../docker/using_docker_images.md#what-is-a-service), linked to a base image specified in [`image`](#image). +Use `services` to specify a [service Docker image](../services/index.md), linked to a base image specified in [`image`](#image). For: -- Usage examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). +- Usage examples, see [Define `services` in the `.gitlab-ci.yml` file](../services/index.md#define-services-in-the-gitlab-ciyml-file). - Detailed usage information, refer to [Docker integration](../docker/index.md) documentation. - Example services, see [GitLab CI/CD Services](../services/index.md). @@ -541,25 +658,25 @@ For: An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options). -For more information, see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services). +For more information, see [Available settings for `services`](../services/index.md#available-settings-for-services). ##### `services:alias` An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options). -For more information, see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services). +For more information, see [Available settings for `services`](../services/index.md#available-settings-for-services). ##### `services:entrypoint` An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options). -For more information, see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services). +For more information, see [Available settings for `services`](../services/index.md#available-settings-for-services). ##### `services:command` An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options). -For more information, see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services). +For more information, see [Available settings for `services`](../services/index.md#available-settings-for-services). ### `script` @@ -1069,8 +1186,8 @@ job: - when: on_success ``` -- If the pipeline is for a merge request, the job is **not** be added to the pipeline. -- If the pipeline is a scheduled pipeline, the job is **not** be added to the pipeline. +- If the pipeline is for a merge request, the job is **not** added to the pipeline. +- If the pipeline is a scheduled pipeline, the job is **not** added to the pipeline. - In **all other cases**, the job is added to the pipeline, with `when: on_success`. WARNING: @@ -1180,7 +1297,7 @@ expression string per rule, rather than an array of them. Any set of expressions evaluated can be [conjoined into a single expression](../variables/README.md#conjunction--disjunction) by using `&&` or `||`, and the [variable matching operators (`==`, `!=`, `=~` and `!~`)](../variables/README.md#syntax-of-cicd-variable-expressions). -Unlike variables in [`script`](../variables/README.md#syntax-of-cicd-variables-in-job-scripts) +Unlike variables in [`script`](../variables/README.md#use-cicd-variables-in-job-scripts) sections, variables in rules expressions are always formatted as `$VARIABLE`. `if:` clauses are evaluated based on the values of [predefined CI/CD variables](../variables/predefined_variables.md) @@ -1357,7 +1474,9 @@ job: Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly link outside it. -You can use glob patterns to match multiple files in any directory in the repository: +You can use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) +patterns to match multiple files in any directory +in the repository: ```yaml job: @@ -1794,7 +1913,8 @@ WARNING: If you use `only:changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds), you should [also use `only:merge_requests`](#use-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected. -You can also use glob patterns to match multiple files in either the root directory +You can also use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) +patterns to match multiple files in either the root directory of the repository, or in _any_ directory in the repository. However, they must be wrapped in double quotes or GitLab can't parse them: @@ -1983,6 +2103,10 @@ To disable directed acyclic graphs (DAG), set the limit to `0`. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.6. +When a job uses `needs`, it no longer downloads all artifacts from previous stages +by default, because jobs with `needs` can start before earlier stages complete. With +`needs` you can only download artifacts from the jobs listed in the `needs:` configuration. + Use `artifacts: true` (default) or `artifacts: false` to control when artifacts are downloaded in jobs that use `needs`. @@ -2145,10 +2269,11 @@ To download artifacts from a job in the current pipeline, use the basic form of #### Optional `needs` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30680) in GitLab 13.10. -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-optional-needs). **(FREE SELF)** +> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/323891) in GitLab 13.11. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-optional-needs). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -2187,10 +2312,10 @@ rspec: #### Enable or disable optional needs **(FREE SELF)** -Optional needs is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +Optional needs is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. +can opt to disable it. To enable it: @@ -2325,8 +2450,8 @@ The valid values of `when` are: 1. `delayed` - [Delay the execution of a job](#whendelayed) for a specified duration. Added in GitLab 11.14. 1. `never`: - - With [`rules`](#rules), don't execute job. - - With [`workflow`](#workflow), don't run pipeline. + - With job [`rules`](#rules), don't execute job. + - With [`workflow:rules`](#workflow), don't run pipeline. In the following example, the script: @@ -2579,9 +2704,9 @@ Use the `action` keyword to specify jobs that prepare, start, or stop environmen | **Value** | **Description** | |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| -| start | Default value. Indicates that job starts the environment. The deployment is created after the job starts. | -| prepare | Indicates that job is only preparing the environment. Does not affect deployments. [Read more about environments](../environments/index.md#prepare-an-environment) | -| stop | Indicates that job stops deployment. See the example below. | +| `start` | Default value. Indicates that job starts the environment. The deployment is created after the job starts. | +| `prepare` | Indicates that the job is only preparing the environment. It does not trigger deployments. [Read more about preparing environments](../environments/index.md#prepare-an-environment-without-creating-a-deployment). | +| `stop` | Indicates that job stops deployment. See the example below. | Take for instance: @@ -2614,7 +2739,7 @@ the GitLab UI to run. Also in the example, `GIT_STRATEGY` is set to `none`. If the `stop_review_app` job is [automatically triggered](../environments/index.md#stopping-an-environment), -the runner won’t try to check out the code after the branch is deleted. +the runner won't try to check out the code after the branch is deleted. The example also overwrites global variables. If your `stop` `environment` job depends on global variables, use [anchor variables](#yaml-anchors-for-variables) when you set the `GIT_STRATEGY` @@ -2630,8 +2755,8 @@ The `stop_review_app` job is **required** to have the following keywords defined - `environment:name` - `environment:action` -Additionally, both jobs should have matching [`rules`](../yaml/README.md#onlyexcept-basic) -or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. +Additionally, both jobs should have matching [`rules`](#onlyexcept-basic) +or [`only/except`](#onlyexcept-basic) configuration. In the examples above, if the configuration is not identical: @@ -2695,7 +2820,7 @@ To follow progress on support for GitLab-managed clusters, see the #### `environment:deployment_tier` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 13.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300741) in GitLab 13.10. Use the `deployment_tier` keyword to specify the tier of the deployment environment: @@ -2759,7 +2884,7 @@ patterns and: - In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match). - In GitLab Runner 12.10 and earlier, -[`filepath.Match`](https://pkg.go.dev/path/filepath/#Match). +[`filepath.Match`](https://pkg.go.dev/path/filepath#Match). Cache all files in `binaries` that end in `.apk` and the `.config` file: @@ -2831,13 +2956,11 @@ You can specify a [fallback cache key](#fallback-cache-key) to use if the specif ##### Multiple caches > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32814) in GitLab 13.10. -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-multiple-caches). **(FREE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/321877) in GitLab 13.11. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-multiple-caches). **(FREE SELF)** You can have a maximum of four caches: @@ -2866,10 +2989,10 @@ the fallback is fetched multiple times if multiple caches are not found. ##### Enable or disable multiple caches **(FREE SELF)** -The multiple caches feature is under development and not ready for production use. -It is deployed behind a feature flag that is **disabled by default**. +The multiple caches feature is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. +can opt to disable it. To enable it: @@ -3072,98 +3195,87 @@ The artifacts are sent to GitLab after the job finishes. They are available for download in the GitLab UI if the size is not larger than the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd). +By default, jobs in later stages automatically download all the artifacts created +by jobs in earlier stages. You can control artifact download behavior in jobs with +[`dependencies`](#dependencies). + +When using the [`needs`](#artifact-downloads-with-needs) keyword, jobs can only download +artifacts from the jobs defined in the `needs` configuration. + Job artifacts are only collected for successful jobs by default, and artifacts are restored after [caches](#cache). [Read more about artifacts](../pipelines/job_artifacts.md). -#### `artifacts:paths` - -Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly -link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) -patterns and: - -- In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, -[`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match). -- In GitLab Runner 12.10 and earlier, -[`filepath.Match`](https://pkg.go.dev/path/filepath/#Match). +#### `dependencies` -To restrict which jobs a specific job fetches artifacts from, see [dependencies](#dependencies). +By default, all `artifacts` from previous stages +are passed to each job. However, you can use the `dependencies` keyword to +define a limited list of jobs to fetch artifacts from. You can also set a job to download no artifacts at all. -Send all files in `binaries` and `.config`: +To use this feature, define `dependencies` in context of the job and pass +a list of all previous jobs the artifacts should be downloaded from. -```yaml -artifacts: - paths: - - binaries/ - - .config -``` +You can define jobs from stages that were executed before the current one. +An error occurs if you define jobs from the current or an upcoming stage. -To disable artifact passing, define the job with empty [dependencies](#dependencies): +To prevent a job from downloading artifacts, define an empty array. -```yaml -job: - stage: build - script: make build - dependencies: [] -``` +When you use `dependencies`, the status of the previous job is not considered. +If a job fails or it's a manual job that isn't triggered, no error occurs. -You may want to create artifacts only for tagged releases to avoid filling the -build server storage with temporary build artifacts. +The following example defines two jobs with artifacts: `build:osx` and +`build:linux`. When the `test:osx` is executed, the artifacts from `build:osx` +are downloaded and extracted in the context of the build. The same happens +for `test:linux` and artifacts from `build:linux`. -Create artifacts only for tags (`default-job` doesn't create artifacts): +The job `deploy` downloads artifacts from all previous jobs because of +the [stage](#stages) precedence: ```yaml -default-job: - script: - - mvn test -U - except: - - tags - -release-job: - script: - - mvn package -U +build:osx: + stage: build + script: make build:osx artifacts: paths: - - target/*.war - only: - - tags -``` - -You can use wildcards for directories too. For example, if you want to get all the files inside the directories that end with `xyz`: + - binaries/ -```yaml -job: +build:linux: + stage: build + script: make build:linux artifacts: paths: - - path/*xyz/* -``` + - binaries/ -#### `artifacts:public` +test:osx: + stage: test + script: make test:osx + dependencies: + - build:osx -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49775) in GitLab 13.8 -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. +test:linux: + stage: test + script: make test:linux + dependencies: + - build:linux -Use `artifacts:public` to determine whether the job artifacts should be -publicly available. +deploy: + stage: deploy + script: make deploy +``` -The default for `artifacts:public` is `true` which means that the artifacts in -public pipelines are available for download by anonymous and guest users: +##### When a dependent job fails -```yaml -artifacts: - public: true -``` +> Introduced in GitLab 10.3. -To deny read access for anonymous and guest users to artifacts in public -pipelines, set `artifacts:public` to `false`: +If the artifacts of the job that is set as a dependency are +[expired](#artifactsexpire_in) or +[deleted](../pipelines/job_artifacts.md#delete-job-artifacts), then +the dependent job fails. -```yaml -artifacts: - public: false -``` +You can ask your administrator to +[flip this switch](../../administration/job_artifacts.md#validation-for-dependencies) +and bring back the old behavior. #### `artifacts:exclude` @@ -3176,7 +3288,7 @@ archive. Similar to [`artifacts:paths`](#artifactspaths), `exclude` paths are relative to the project directory. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) or -[`filepath.Match`](https://golang.org/pkg/path/filepath/#Match) patterns. +[`doublestar.PathMatch`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#PathMatch) patterns. For example, to store all files in `binaries/`, but not `*.o` files located in subdirectories of `binaries/`: @@ -3189,9 +3301,68 @@ artifacts: - binaries/**/*.o ``` +Unlike [`artifacts:paths`](#artifactspaths), `exclude` paths are not recursive. To exclude all of the contents of a directory, you can match them explicitly rather than matching the directory itself. + +For example, to store all files in `binaries/` but nothing located in the `temp/` subdirectory: + +```yaml +artifacts: + paths: + - binaries/ + exclude: + - binaries/temp/**/* +``` + Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded using `artifacts:exclude` too. +#### `artifacts:expire_in` + +Use `expire_in` to specify how long artifacts are active before they +expire and are deleted. + +The expiration time period begins when the artifact is uploaded and +stored on GitLab. If the expiry time is not defined, it defaults to the +[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration) +(30 days by default). + +To override the expiration date and protect artifacts from being automatically deleted: + +- Use the **Keep** button on the job page. +- Set the value of `expire_in` to `never`. [Available](https://gitlab.com/gitlab-org/gitlab/-/issues/22761) + in GitLab 13.3 and later. + +After their expiry, artifacts are deleted hourly by default (via a cron job), +and are not accessible anymore. + +The value of `expire_in` is an elapsed time in seconds, unless a unit is +provided. Examples of valid values: + +- `'42'` +- `42 seconds` +- `3 mins 4 sec` +- `2 hrs 20 min` +- `2h20min` +- `6 mos 1 day` +- `47 yrs 6 mos and 4d` +- `3 weeks and 2 days` +- `never` + +To expire artifacts 1 week after being uploaded: + +```yaml +job: + artifacts: + expire_in: 1 week +``` + +The latest artifacts for refs are locked against deletion, and kept regardless of +the expiry time. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) +GitLab 13.0 behind a disabled feature flag, and [made the default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) +in GitLab 13.4. + +In [GitLab 13.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/241026), you can [disable this behavior at the project level in the CI/CD settings](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). In [GitLab 13.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/276583), you can [disable this behavior instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). + #### `artifacts:expose_as` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) in GitLab 12.5. @@ -3210,7 +3381,8 @@ test: ``` With this configuration, GitLab adds a link **artifact 1** to the relevant merge request -that points to `file1.txt`. +that points to `file1.txt`. To access the link, select **View exposed artifact** +below the pipeline graph in the merge request overview. An example that matches an entire directory: @@ -3227,7 +3399,7 @@ Note the following: - Artifacts do not display in the merge request UI when using variables to define the `artifacts:paths`. - A maximum of 10 job artifacts per merge request can be exposed. - Glob patterns are unsupported. -- If a directory is specified, the link is to the job [artifacts browser](../pipelines/job_artifacts.md#browsing-artifacts) if there is more than +- If a directory is specified, the link is to the job [artifacts browser](../pipelines/job_artifacts.md#download-job-artifacts) if there is more than one file in the directory. - For exposed single file artifacts with `.html`, `.htm`, `.txt`, `.json`, `.xml`, and `.log` extensions, if [GitLab Pages](../../administration/pages/index.md) is: @@ -3311,197 +3483,397 @@ job: - binaries/ ``` -#### `artifacts:untracked` +#### `artifacts:paths` -Use `artifacts:untracked` to add all Git untracked files as artifacts (along -with the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration -in the repository's `.gitignore` file. +Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly +link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) +patterns and: -Send all Git untracked files: +- In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, +[`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match). +- In GitLab Runner 12.10 and earlier, +[`filepath.Match`](https://pkg.go.dev/path/filepath#Match). -```yaml -artifacts: - untracked: true -``` +To restrict which jobs a specific job fetches artifacts from, see [dependencies](#dependencies). -Send all Git untracked files and files in `binaries`: +Send all files in `binaries` and `.config`: ```yaml artifacts: - untracked: true paths: - binaries/ + - .config ``` -Send all untracked files but [exclude](#artifactsexclude) `*.txt`: +To disable artifact passing, define the job with empty [dependencies](#dependencies): ```yaml -artifacts: - untracked: true - exclude: - - "*.txt" +job: + stage: build + script: make build + dependencies: [] ``` -#### `artifacts:when` +You may want to create artifacts only for tagged releases to avoid filling the +build server storage with temporary build artifacts. -Use `artifacts:when` to upload artifacts on job failure or despite the -failure. +Create artifacts only for tags (`default-job` doesn't create artifacts): -`artifacts:when` can be set to one of the following values: +```yaml +default-job: + script: + - mvn test -U + except: + - tags -1. `on_success` (default): Upload artifacts only when the job succeeds. -1. `on_failure`: Upload artifacts only when the job fails. -1. `always`: Always upload artifacts. +release-job: + script: + - mvn package -U + artifacts: + paths: + - target/*.war + only: + - tags +``` -For example, to upload artifacts only when a job fails: +You can use wildcards for directories too. For example, if you want to get all the files inside the directories that end with `xyz`: ```yaml job: artifacts: - when: on_failure + paths: + - path/*xyz/* ``` -#### `artifacts:expire_in` +#### `artifacts:public` -Use `expire_in` to specify how long artifacts are active before they -expire and are deleted. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49775) in GitLab 13.8 +> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. -The expiration time period begins when the artifact is uploaded and -stored on GitLab. If the expiry time is not defined, it defaults to the -[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration) -(30 days by default). +Use `artifacts:public` to determine whether the job artifacts should be +publicly available. -To override the expiration date and protect artifacts from being automatically deleted: +The default for `artifacts:public` is `true` which means that the artifacts in +public pipelines are available for download by anonymous and guest users: -- Use the **Keep** button on the job page. -- Set the value of `expire_in` to `never`. [Available](https://gitlab.com/gitlab-org/gitlab/-/issues/22761) - in GitLab 13.3 and later. +```yaml +artifacts: + public: true +``` -After their expiry, artifacts are deleted hourly by default (via a cron job), -and are not accessible anymore. +To deny read access for anonymous and guest users to artifacts in public +pipelines, set `artifacts:public` to `false`: -The value of `expire_in` is an elapsed time in seconds, unless a unit is -provided. Examples of valid values: +```yaml +artifacts: + public: false +``` -- `'42'` -- `42 seconds` -- `3 mins 4 sec` -- `2 hrs 20 min` -- `2h20min` -- `6 mos 1 day` -- `47 yrs 6 mos and 4d` -- `3 weeks and 2 days` -- `never` +#### `artifacts:reports` -To expire artifacts 1 week after being uploaded: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20390) in GitLab 11.2. +> - Requires GitLab Runner 11.2 and above. + +Use [`artifacts:reports`](#artifactsreports) +to collect test reports, code quality reports, and security reports from jobs. +It also exposes these reports in the GitLab UI (merge requests, pipeline views, and security dashboards). + +The test reports are collected regardless of the job results (success or failure). +You can use [`artifacts:expire_in`](#artifactsexpire_in) to set up an expiration +date for their artifacts. + +If you also want the ability to browse the report output files, include the +[`artifacts:paths`](#artifactspaths) keyword. + +##### `artifacts:reports:api_fuzzing` **(ULTIMATE)** + +> - Introduced in GitLab 13.4. +> - Requires GitLab Runner 13.4 or later. + +The `api_fuzzing` report collects [API Fuzzing bugs](../../user/application_security/api_fuzzing/index.md) +as artifacts. + +The collected API Fuzzing report uploads to GitLab as an artifact and is summarized in merge +requests and the pipeline view. It's also used to provide data for security dashboards. + +##### `artifacts:reports:cobertura` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. +> - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above. + +The `cobertura` report collects [Cobertura coverage XML files](../../user/project/merge_requests/test_coverage_visualization.md). +The collected Cobertura coverage reports upload to GitLab as an artifact +and display in merge requests. + +Cobertura was originally developed for Java, but there are many +third party ports for other languages like JavaScript, Python, Ruby, and so on. + +##### `artifacts:reports:codequality` + +> - Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5. +> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in GitLab 13.2. +> - Requires GitLab Runner 11.5 and above. + +The `codequality` report collects [Code Quality issues](../../user/project/merge_requests/code_quality.md) +as artifacts. + +The collected Code Quality report uploads to GitLab as an artifact and is summarized in merge requests. + +##### `artifacts:reports:container_scanning` **(ULTIMATE)** + +> - Introduced in GitLab 11.5. +> - Requires GitLab Runner 11.5 and above. + +The `container_scanning` report collects [Container Scanning vulnerabilities](../../user/application_security/container_scanning/index.md) +as artifacts. + +The collected Container Scanning report uploads to GitLab as an artifact and +is summarized in merge requests and the pipeline view. It's also used to provide data for security +dashboards. + +##### `artifacts:reports:coverage_fuzzing` **(ULTIMATE)** + +> - Introduced in GitLab 13.4. +> - Requires GitLab Runner 13.4 or later. + +The `coverage_fuzzing` report collects [coverage fuzzing bugs](../../user/application_security/coverage_fuzzing/index.md) +as artifacts. + +The collected coverage fuzzing report uploads to GitLab as an artifact and is summarized in merge +requests and the pipeline view. It's also used to provide data for security dashboards. + +##### `artifacts:reports:dast` **(ULTIMATE)** + +> - Introduced in GitLab 11.5. +> - Requires GitLab Runner 11.5 and above. + +The `dast` report collects [DAST vulnerabilities](../../user/application_security/dast/index.md) +as artifacts. + +The collected DAST report uploads to GitLab as an artifact and is summarized in merge requests and the pipeline view. It's also used to provide data for security +dashboards. + +##### `artifacts:reports:dependency_scanning` **(ULTIMATE)** + +> - Introduced in GitLab 11.5. +> - Requires GitLab Runner 11.5 and above. + +The `dependency_scanning` report collects [Dependency Scanning vulnerabilities](../../user/application_security/dependency_scanning/index.md) +as artifacts. + +The collected Dependency Scanning report uploads to GitLab as an artifact and is summarized in merge requests and the pipeline view. It's also used to provide data for security +dashboards. + +##### `artifacts:reports:dotenv` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) in GitLab 12.9. +> - Requires GitLab Runner 11.5 and later. + +The `dotenv` report collects a set of environment variables as artifacts. + +The collected variables are registered as runtime-created variables of the job, +which is useful to [set dynamic environment URLs after a job finishes](../environments/index.md#set-dynamic-environment-urls-after-a-job-finishes). + +There are a couple of exceptions to the [original dotenv rules](https://github.com/motdotla/dotenv#rules): + +- The variable key can contain only letters, digits, and underscores (`_`). +- The maximum size of the `.env` file is 5 KB. +- In GitLab 13.5 and older, the maximum number of inherited variables is 10. +- In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/247913), + the maximum number of inherited variables is 20. +- Variable substitution in the `.env` file is not supported. +- The `.env` file can't have empty lines or comments (starting with `#`). +- Key values in the `env` file cannot have spaces or newline characters (`\n`), including when using single or double quotes. +- Quote escaping during parsing (`key = 'value'` -> `{key: "value"}`) is not supported. + +##### `artifacts:reports:junit` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20390) in GitLab 11.2. +> - Requires GitLab Runner 11.2 and above. + +The `junit` report collects [JUnit report format XML files](https://www.ibm.com/support/knowledgecenter/en/SSQ2R2_14.1.0/com.ibm.rsar.analysis.codereview.cobol.doc/topics/cac_useresults_junit.html) +as artifacts. Although JUnit was originally developed in Java, there are many +third party ports for other +languages like JavaScript, Python, Ruby, and so on. + +See [Unit test reports](../unit_test_reports.md) for more details and examples. +Below is an example of collecting a JUnit report format XML file from Ruby's RSpec test tool: ```yaml -job: +rspec: + stage: test + script: + - bundle install + - rspec --format RspecJunitFormatter --out rspec.xml artifacts: - expire_in: 1 week + reports: + junit: rspec.xml ``` -The latest artifacts for refs are locked against deletion, and kept regardless of -the expiry time. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) -GitLab 13.0 behind a disabled feature flag, and [made the default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) -in GitLab 13.4. +The collected Unit test reports upload to GitLab as an artifact and display in merge requests. -In [GitLab 13.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/241026), you can [disable this behavior at the project level in the CI/CD settings](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). In [GitLab 13.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/276583), you can [disable this behavior instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). +If the JUnit tool you use exports to multiple XML files, specify +multiple test report paths within a single job to +concatenate them into a single file. Use a filename pattern (`junit: rspec-*.xml`), +an array of filenames (`junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]`), or a +combination thereof (`junit: [rspec.xml, test-results/TEST-*.xml]`). -#### `artifacts:reports` +##### `artifacts:reports:license_management` **(ULTIMATE)** -Use [`artifacts:reports`](../pipelines/job_artifacts.md#artifactsreports) -to collect test reports, code quality reports, and security reports from jobs. -It also exposes these reports in the GitLab UI (merge requests, pipeline views, and security dashboards). +> - Introduced in GitLab 11.5. +> - Requires GitLab Runner 11.5 and above. -These are the available report types: - -| Keyword | Description | -|-----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| -| [`artifacts:reports:cobertura`](../pipelines/job_artifacts.md#artifactsreportscobertura) | The `cobertura` report collects Cobertura coverage XML files. | -| [`artifacts:reports:codequality`](../pipelines/job_artifacts.md#artifactsreportscodequality) | The `codequality` report collects Code Quality issues. | -| [`artifacts:reports:container_scanning`](../pipelines/job_artifacts.md#artifactsreportscontainer_scanning) **(ULTIMATE)** | The `container_scanning` report collects Container Scanning vulnerabilities. | -| [`artifacts:reports:dast`](../pipelines/job_artifacts.md#artifactsreportsdast) **(ULTIMATE)** | The `dast` report collects Dynamic Application Security Testing vulnerabilities. | -| [`artifacts:reports:dependency_scanning`](../pipelines/job_artifacts.md#artifactsreportsdependency_scanning) **(ULTIMATE)** | The `dependency_scanning` report collects Dependency Scanning vulnerabilities. | -| [`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) | The `dotenv` report collects a set of environment variables. | -| [`artifacts:reports:junit`](../pipelines/job_artifacts.md#artifactsreportsjunit) | The `junit` report collects JUnit XML files. | -| [`artifacts:reports:license_management`](../pipelines/job_artifacts.md#artifactsreportslicense_management) **(ULTIMATE)** | The `license_management` report collects Licenses (*removed from GitLab 13.0*). | -| [`artifacts:reports:license_scanning`](../pipelines/job_artifacts.md#artifactsreportslicense_scanning) **(ULTIMATE)** | The `license_scanning` report collects Licenses. | -| [`artifacts:reports:load_performance`](../pipelines/job_artifacts.md#artifactsreportsload_performance) **(PREMIUM)** | The `load_performance` report collects load performance metrics. | -| [`artifacts:reports:metrics`](../pipelines/job_artifacts.md#artifactsreportsmetrics) **(PREMIUM)** | The `metrics` report collects Metrics. | -| [`artifacts:reports:performance`](../pipelines/job_artifacts.md#artifactsreportsperformance) **(PREMIUM)** | The `performance` report collects Browser Performance metrics. | -| [`artifacts:reports:sast`](../pipelines/job_artifacts.md#artifactsreportssast) | The `sast` report collects Static Application Security Testing vulnerabilities. | -| [`artifacts:reports:terraform`](../pipelines/job_artifacts.md#artifactsreportsterraform) | The `terraform` report collects Terraform `tfplan.json` files. | +WARNING: +This artifact is still valid but is **deprecated** in favor of the +[artifacts:reports:license_scanning](#artifactsreportslicense_scanning) +introduced in GitLab 12.8. -#### `dependencies` +The `license_management` report collects [Licenses](../../user/compliance/license_compliance/index.md) +as artifacts. -By default, all [`artifacts`](#artifacts) from previous [stages](#stages) -are passed to each job. However, you can use the `dependencies` keyword to -define a limited list of jobs to fetch artifacts from. You can also set a job to download no artifacts at all. +The collected License Compliance report uploads to GitLab as an artifact and is summarized in merge requests and the pipeline view. It's also used to provide data for security +dashboards. -To use this feature, define `dependencies` in context of the job and pass -a list of all previous jobs the artifacts should be downloaded from. +##### `artifacts:reports:license_scanning` **(ULTIMATE)** -You can define jobs from stages that were executed before the current one. -An error occurs if you define jobs from the current or an upcoming stage. +> - Introduced in GitLab 12.8. +> - Requires GitLab Runner 11.5 and above. -To prevent a job from downloading artifacts, define an empty array. +The `license_scanning` report collects [Licenses](../../user/compliance/license_compliance/index.md) +as artifacts. -When you use `dependencies`, the status of the previous job is not considered. -If a job fails or it's a manual job that isn't triggered, no error occurs. +The License Compliance report uploads to GitLab as an artifact and displays automatically in merge requests and the pipeline view, and provide data for security +dashboards. -The following example defines two jobs with artifacts: `build:osx` and -`build:linux`. When the `test:osx` is executed, the artifacts from `build:osx` -are downloaded and extracted in the context of the build. The same happens -for `test:linux` and artifacts from `build:linux`. +##### `artifacts:reports:load_performance` **(PREMIUM)** -The job `deploy` downloads artifacts from all previous jobs because of -the [stage](#stages) precedence: +> - Introduced in [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> - Requires GitLab Runner 11.5 and above. + +The `load_performance` report collects [Load Performance Testing metrics](../../user/project/merge_requests/load_performance_testing.md) +as artifacts. + +The report is uploaded to GitLab as an artifact and is +shown in merge requests automatically. + +##### `artifacts:reports:metrics` **(PREMIUM)** + +> Introduced in GitLab 11.10. + +The `metrics` report collects [Metrics](../metrics_reports.md) +as artifacts. + +The collected Metrics report uploads to GitLab as an artifact and displays in merge requests. + +##### `artifacts:reports:performance` **(PREMIUM)** + +> - Introduced in GitLab 11.5. +> - Requires GitLab Runner 11.5 and above. + +The `performance` report collects [Browser Performance Testing metrics](../../user/project/merge_requests/browser_performance_testing.md) +as artifacts. + +The collected Browser Performance report uploads to GitLab as an artifact and displays in merge requests. + +##### `artifacts:reports:requirements` **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in GitLab 13.1. +> - Requires GitLab Runner 11.5 and above. + +The `requirements` report collects `requirements.json` files as artifacts. + +The collected Requirements report uploads to GitLab as an artifact and +existing [requirements](../../user/project/requirements/index.md) are +marked as Satisfied. + +##### `artifacts:reports:sast` + +> - Introduced in GitLab 11.5. +> - Made [available in all tiers](https://gitlab.com/groups/gitlab-org/-/epics/2098) in GitLab 13.3. +> - Requires GitLab Runner 11.5 and above. + +The `sast` report collects [SAST vulnerabilities](../../user/application_security/sast/index.md) +as artifacts. + +The collected SAST report uploads to GitLab as an artifact and is summarized +in merge requests and the pipeline view. It's also used to provide data for security +dashboards. + +##### `artifacts:reports:secret_detection` + +> - Introduced in GitLab 13.1. +> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) in GitLab + 13.3. +> - Requires GitLab Runner 11.5 and above. + +The `secret-detection` report collects [detected secrets](../../user/application_security/secret_detection/index.md) +as artifacts. + +The collected Secret Detection report is uploaded to GitLab as an artifact and summarized +in the merge requests and pipeline view. It's also used to provide data for security +dashboards. + +##### `artifacts:reports:terraform` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207528) in GitLab 13.0. +> - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above. + +The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/mr_integration.md#setup). The collected Terraform +plan report uploads to GitLab as an artifact and displays +in merge requests. For more information, see +[Output `terraform plan` information into a merge request](../../user/infrastructure/mr_integration.md). + +#### `artifacts:untracked` + +Use `artifacts:untracked` to add all Git untracked files as artifacts (along +with the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration +in the repository's `.gitignore` file. + +Send all Git untracked files: ```yaml -build:osx: - stage: build - script: make build:osx - artifacts: - paths: - - binaries/ +artifacts: + untracked: true +``` -build:linux: - stage: build - script: make build:linux - artifacts: - paths: - - binaries/ +Send all Git untracked files and files in `binaries`: -test:osx: - stage: test - script: make test:osx - dependencies: - - build:osx +```yaml +artifacts: + untracked: true + paths: + - binaries/ +``` -test:linux: - stage: test - script: make test:linux - dependencies: - - build:linux +Send all untracked files but [exclude](#artifactsexclude) `*.txt`: -deploy: - stage: deploy - script: make deploy +```yaml +artifacts: + untracked: true + exclude: + - "*.txt" ``` -##### When a dependent job fails +#### `artifacts:when` -> Introduced in GitLab 10.3. +Use `artifacts:when` to upload artifacts on job failure or despite the +failure. -If the artifacts of the job that is set as a dependency are -[expired](#artifactsexpire_in) or -[erased](../pipelines/job_artifacts.md#erasing-artifacts), then -the dependent job fails. +`artifacts:when` can be set to one of the following values: -You can ask your administrator to -[flip this switch](../../administration/job_artifacts.md#validation-for-dependencies) -and bring back the old behavior. +1. `on_success` (default): Upload artifacts only when the job succeeds. +1. `on_failure`: Upload artifacts only when the job fails. +1. `always`: Always upload artifacts. + +For example, to upload artifacts only when a job fails: + +```yaml +job: + artifacts: + when: on_failure +``` ### `coverage` @@ -4089,6 +4461,8 @@ finishes. > [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/19298) in GitLab 13.2. Use `release` to create a [release](../../user/project/releases/index.md). +Requires the [`release-cli`](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs) +to be available in your GitLab Runner Docker or shell executor. These keywords are supported: @@ -4110,6 +4484,99 @@ You must specify the Docker image to use for the `release-cli`: image: registry.gitlab.com/gitlab-org/release-cli:latest ``` +#### `release-cli` for shell executors + +> [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8. + +For GitLab Runner shell executors, 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 should be available to you. + +**Install on Unix/Linux** + +1. Download the binary for your system, in the following example for amd64 systems: + + ```shell + curl --location --output /usr/local/bin/release-cli "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-linux-amd64" + ``` + +1. Give it permissions to execute: + + ```shell + sudo chmod +x /usr/local/bin/release-cli + ``` + +1. Verify `release-cli` is available: + + ```shell + $ release-cli -v + + release-cli version 0.6.0 + ``` + +**Install on Windows PowerShell** + +1. Create a folder somewhere in your system, for example `C:\GitLab\Release-CLI\bin` + + ```shell + New-Item -Path 'C:\GitLab\Release-CLI\bin' -ItemType Directory + ``` + +1. Download the executable file: + + ```shell + PS C:\> Invoke-WebRequest -Uri "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-windows-amd64.exe" -OutFile "C:\GitLab\Release-CLI\bin\release-cli.exe" + + Directory: C:\GitLab\Release-CLI + Mode LastWriteTime Length Name + ---- ------------- ------ ---- + d----- 3/16/2021 4:17 AM bin + + ``` + +1. Add the directory to your `$env:PATH`: + + ```shell + $env:PATH += ";C:\GitLab\Release-CLI\bin" + ``` + +1. Verify `release-cli` is available: + + ```shell + PS C:\> release-cli -v + + release-cli version 0.6.0 + ``` + +#### 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](https://tools.ietf.org/html/rfc7468#section-5.1) +or the `path/to/file` containing the certificate authority. +For example, to configure this value in the `.gitlab-ci.yml` file, use the following: + +```yaml +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](../variables/README.md#custom-cicd-variables), +either as a `file`, which requires the path to the certificate, or as a variable, +which requires the text representation of the certificate. + #### `script` All jobs except [trigger](#trigger) jobs must have the `script` keyword. A `release` @@ -4197,7 +4664,7 @@ job: #### `release:ref` -If the `release: tag_name` doesn’t exist yet, the release is created from `ref`. +If the `release: tag_name` doesn't exist yet, the release is created from `ref`. `ref` can be a commit SHA, another tag name, or a branch name. #### `release:milestones` @@ -4510,10 +4977,10 @@ meaning it applies to all jobs. If you define a variable in a job, it's availabl to that job only. If a variable of the same name is defined globally and for a specific job, the -[job-specific variable overrides the global variable](../variables/README.md#priority-of-cicd-variables). +[job-specific variable overrides the global variable](../variables/README.md#cicd-variable-precedence). All YAML-defined variables are also set to any linked -[Docker service containers](../docker/using_docker_images.md#what-is-a-service). +[Docker service containers](../services/index.md). You can use [YAML anchors for variables](#yaml-anchors-for-variables). @@ -4820,7 +5287,7 @@ reused in the `test` job: - !reference [.teardown, after_script] ``` -In the following example, `test-vars-1` reuses the all the variables in `.vars`, while `test-vars-2` +In the following example, `test-vars-1` reuses all the variables in `.vars`, while `test-vars-2` selects a specific variable and reuses it as a new `MY_VAR` variable. ```yaml @@ -4888,13 +5355,14 @@ Use [`default:`](#custom-default-keyword-values) instead. For example: ```yaml default: - image: ruby:2.5 + image: ruby:3.0 services: - docker:dind cache: paths: [vendor/] before_script: - - bundle install --path vendor/ + - bundle config set path vendor/bundle + - bundle install after_script: - rm -rf tmp/ ``` |