@@ -229,6 +229,15 @@ This functionality is only available:
...
@@ -229,6 +229,15 @@ This functionality is only available:
- For users with at least the Developer role.
- For users with at least the Developer role.
- If the stage contains [manual actions](#add-manual-interaction-to-your-pipeline).
- If the stage contains [manual actions](#add-manual-interaction-to-your-pipeline).
### Skip a pipeline
To push a commit without triggering a pipeline, add `[ci skip]` or `[skip ci]`, using any
capitalization, to your commit message.
Alternatively, if you are using Git 2.10 or later, use the `ci.skip`[Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd).
The `ci.skip` push option does not skip merge request
pipelines.
### Delete a pipeline
### Delete a pipeline
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24851) in GitLab 12.7.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24851) in GitLab 12.7.
-`script` does not merge, but `script: ['rake rspec']` overwrites
-`script` does not merge, but `script: ['rake rspec']` overwrites
`script: ['echo "Hello world!"']`. You can use [YAML anchors](#anchors) to merge arrays.
`script: ['echo "Hello world!"']`. You can use [YAML anchors](yaml_specific_features.md#anchors) to merge arrays.
#### Use `extends` and `include` together
#### Use `extends` and `include` together
...
@@ -1150,7 +1150,7 @@ The job is not added to the pipeline:
...
@@ -1150,7 +1150,7 @@ The job is not added to the pipeline:
- If no rules match.
- If no rules match.
- If a rule matches and has `when: never`.
- If a rule matches and has `when: never`.
You can use [`!reference` tags](#reference-tags) to [reuse `rules` configuration](../jobs/job_control.md#reuse-rules-in-different-jobs)
You can use [`!reference` tags](yaml_specific_features.md#reference-tags) to [reuse `rules` configuration](../jobs/job_control.md#reuse-rules-in-different-jobs)
in different jobs.
in different jobs.
#### `rules:if`
#### `rules:if`
...
@@ -2187,7 +2187,7 @@ Also in the example, `GIT_STRATEGY` is set to `none`. If the
...
@@ -2187,7 +2187,7 @@ Also in the example, `GIT_STRATEGY` is set to `none`. If the
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
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`
on global variables, use [anchor variables](yaml_specific_features.md#yaml-anchors-for-variables) when you set the `GIT_STRATEGY`
to change the job without overriding the global variables.
to change the job without overriding the global variables.
The `stop_review_app` job is **required** to have the following keywords defined:
The `stop_review_app` job is **required** to have the following keywords defined:
...
@@ -4551,7 +4551,7 @@ If a variable of the same name is defined globally and for a specific job, the
...
@@ -4551,7 +4551,7 @@ If a variable of the same name is defined globally and for a specific job, the
All YAML-defined variables are also set to any linked
All YAML-defined variables are also set to any linked
[Docker service containers](../services/index.md).
[Docker service containers](../services/index.md).
You can use [YAML anchors for variables](#yaml-anchors-for-variables).
You can use [YAML anchors for variables](yaml_specific_features.md#yaml-anchors-for-variables).
### Prefill variables in manual pipelines
### Prefill variables in manual pipelines
...
@@ -4587,311 +4587,6 @@ You can use [CI/CD variables](../variables/index.md) to configure how the runner
...
@@ -4587,311 +4587,6 @@ You can use [CI/CD variables](../variables/index.md) to configure how the runner
You can also use variables to configure how many times a runner
You can also use variables to configure how many times a runner
[attempts certain stages of job execution](../runners/configure_runners.md#job-stages-attempts).
[attempts certain stages of job execution](../runners/configure_runners.md#job-stages-attempts).
## YAML-specific features
In your `.gitlab-ci.yml` file, you can use YAML-specific features like anchors (`&`), aliases (`*`),
and map merging (`<<`). Use these features to reduce the complexity
of the code in the `.gitlab-ci.yml` file.
Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/).
In most cases, the [`extends` keyword](#extends) is more user friendly and you should
use it when possible.
You can use YAML anchors to merge YAML arrays.
### Anchors
YAML has a feature called 'anchors' that you can use to duplicate
content across your document.
Use anchors to duplicate or inherit properties. Use anchors with [hidden jobs](#hide-jobs)
to provide templates for your jobs. When there are duplicate keys, GitLab
performs a reverse deep merge based on the keys.
You can't use YAML anchors across multiple files when using the [`include`](#include)
keyword. Anchors are only valid in the file they were defined in. To reuse configuration
from different YAML files, use [`!reference` tags](#reference-tags) or the
[`extends` keyword](#extends).
The following example uses anchors and map merging. It creates two jobs,
`test1` and `test2`, that inherit the `.job_template` configuration, each
with their own custom `script` defined:
```yaml
.job_template:&job_configuration# Hidden yaml configuration that defines an anchor named 'job_configuration'
image:ruby:2.6
services:
-postgres
-redis
test1:
<<:*job_configuration# Merge the contents of the 'job_configuration' alias
script:
-test1 project
test2:
<<:*job_configuration# Merge the contents of the 'job_configuration' alias
script:
-test2 project
```
`&` sets up the name of the anchor (`job_configuration`), `<<` means "merge the
given hash into the current one," and `*` includes the named anchor
(`job_configuration` again). The expanded version of this example is:
```yaml
.job_template:
image:ruby:2.6
services:
-postgres
-redis
test1:
image:ruby:2.6
services:
-postgres
-redis
script:
-test1 project
test2:
image:ruby:2.6
services:
-postgres
-redis
script:
-test2 project
```
You can use anchors to define two sets of services. For example, `test:postgres`
and `test:mysql` share the `script` defined in `.job_template`, but use different
`services`, defined in `.postgres_services` and `.mysql_services`:
```yaml
.job_template:&job_configuration
script:
-test project
tags:
-dev
.postgres_services:
services:&postgres_configuration
-postgres
-ruby
.mysql_services:
services:&mysql_configuration
-mysql
-ruby
test:postgres:
<<:*job_configuration
services:*postgres_configuration
tags:
-postgres
test:mysql:
<<:*job_configuration
services:*mysql_configuration
```
The expanded version is:
```yaml
.job_template:
script:
-test project
tags:
-dev
.postgres_services:
services:
-postgres
-ruby
.mysql_services:
services:
-mysql
-ruby
test:postgres:
script:
-test project
services:
-postgres
-ruby
tags:
-postgres
test:mysql:
script:
-test project
services:
-mysql
-ruby
tags:
-dev
```
You can see that the hidden jobs are conveniently used as templates, and
`tags: [postgres]` overwrites `tags: [dev]`.
#### YAML anchors for scripts
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23005) in GitLab 12.5.
You can use [YAML anchors](#anchors) with [script](#script), [`before_script`](#before_script),
and [`after_script`](#after_script) to use predefined commands in multiple jobs:
```yaml
.some-script-before:&some-script-before
-echo "Execute this script first"
.some-script:&some-script
-echo "Execute this script second"
-echo "Execute this script too"
.some-script-after:&some-script-after
-echo "Execute this script last"
job1:
before_script:
-*some-script-before
script:
-*some-script
-echo "Execute something, for this job only"
after_script:
-*some-script-after
job2:
script:
-*some-script-before
-*some-script
-echo "Execute something else, for this job only"
-*some-script-after
```
#### YAML anchors for variables
Use [YAML anchors](#anchors) with `variables` to repeat assignment
of variables across multiple jobs. You can also use YAML anchors when a job
requires a specific `variables` block that would otherwise override the global variables.
The following example shows how override the `GIT_STRATEGY` variable without affecting
# a job that must set the GIT_STRATEGY variable, yet depend on global variables
job_no_git_strategy:
stage:cleanup
variables:
<<:*global-variables
GIT_STRATEGY:none
script:echo $SAMPLE_VARIABLE
```
### Hide jobs
If you want to temporarily disable a job, rather than commenting out all the
lines where the job is defined:
```yaml
# hidden_job:
# script:
# - run test
```
Instead, you can start its name with a dot (`.`) and it is not processed by
GitLab CI/CD. In the following example, `.hidden_job` is ignored:
```yaml
.hidden_job:
script:
-run test
```
Use this feature to ignore jobs, or use the
[YAML-specific features](#yaml-specific-features) and transform the hidden jobs
into templates.
### `!reference` tags
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/266173) in GitLab 13.9.
> - `rules` keyword support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322992) in GitLab 14.3.
Use the `!reference` custom YAML tag to select keyword configuration from other job
sections and reuse it in the current section. Unlike [YAML anchors](#anchors), you can
use `!reference` tags to reuse configuration from [included](#include) configuration
files as well.
In the following example, a `script` and an `after_script` from two different locations are
reused in the `test` job:
-`setup.yml`:
```yaml
.setup:
script:
-echo creating environment
```
-`.gitlab-ci.yml`:
```yaml
include:
-local:setup.yml
.teardown:
after_script:
-echo deleting environment
test:
script:
-!reference[.setup,script]
-echo running my own command
after_script:
-!reference[.teardown,after_script]
```
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
.vars:
variables:
URL:"http://my-url.internal"
IMPORTANT_VAR:"thedetails"
test-vars-1:
variables:!reference[.vars,variables]
script:
-printenv
test-vars-2:
variables:
MY_VAR:!reference[.vars,variables,IMPORTANT_VAR]
script:
-printenv
```
You can't reuse a section that already includes a `!reference` tag. Only one level
of nesting is supported.
## Skip Pipeline
To push a commit without triggering a pipeline, add `[ci skip]` or `[skip ci]`, using any
capitalization, to your commit message.
Alternatively, if you are using Git 2.10 or later, use the `ci.skip`[Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd).
The `ci.skip` push option does not skip merge request
pipelines.
## Processing Git pushes
## Processing Git pushes
GitLab creates at most four branch and tag pipelines when
GitLab creates at most four branch and tag pipelines when
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
type:reference
---
# YAML-specific features
In your `.gitlab-ci.yml` file, you can use YAML-specific features like anchors (`&`), aliases (`*`),
and map merging (`<<`). Use these features to reduce the complexity
of the code in the `.gitlab-ci.yml` file.
Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/).
In most cases, the [`extends` keyword](index.md#extends) is more user friendly and you should
use it when possible.
You can use YAML anchors to merge YAML arrays.
## Anchors
YAML has a feature called 'anchors' that you can use to duplicate
content across your document.
Use anchors to duplicate or inherit properties. Use anchors with [hidden jobs](../jobs/index.md#hide-jobs)
to provide templates for your jobs. When there are duplicate keys, GitLab
performs a reverse deep merge based on the keys.
You can't use YAML anchors across multiple files when using the [`include`](index.md#include)
keyword. Anchors are only valid in the file they were defined in. To reuse configuration
from different YAML files, use [`!reference` tags](#reference-tags) or the
[`extends` keyword](index.md#extends).
The following example uses anchors and map merging. It creates two jobs,
`test1` and `test2`, that inherit the `.job_template` configuration, each
with their own custom `script` defined:
```yaml
.job_template:&job_configuration# Hidden yaml configuration that defines an anchor named 'job_configuration'
image:ruby:2.6
services:
-postgres
-redis
test1:
<<:*job_configuration# Merge the contents of the 'job_configuration' alias
script:
-test1 project
test2:
<<:*job_configuration# Merge the contents of the 'job_configuration' alias
script:
-test2 project
```
`&` sets up the name of the anchor (`job_configuration`), `<<` means "merge the
given hash into the current one," and `*` includes the named anchor
(`job_configuration` again). The expanded version of this example is:
```yaml
.job_template:
image:ruby:2.6
services:
-postgres
-redis
test1:
image:ruby:2.6
services:
-postgres
-redis
script:
-test1 project
test2:
image:ruby:2.6
services:
-postgres
-redis
script:
-test2 project
```
You can use anchors to define two sets of services. For example, `test:postgres`
and `test:mysql` share the `script` defined in `.job_template`, but use different
`services`, defined in `.postgres_services` and `.mysql_services`:
```yaml
.job_template:&job_configuration
script:
-test project
tags:
-dev
.postgres_services:
services:&postgres_configuration
-postgres
-ruby
.mysql_services:
services:&mysql_configuration
-mysql
-ruby
test:postgres:
<<:*job_configuration
services:*postgres_configuration
tags:
-postgres
test:mysql:
<<:*job_configuration
services:*mysql_configuration
```
The expanded version is:
```yaml
.job_template:
script:
-test project
tags:
-dev
.postgres_services:
services:
-postgres
-ruby
.mysql_services:
services:
-mysql
-ruby
test:postgres:
script:
-test project
services:
-postgres
-ruby
tags:
-postgres
test:mysql:
script:
-test project
services:
-mysql
-ruby
tags:
-dev
```
You can see that the hidden jobs are conveniently used as templates, and
`tags: [postgres]` overwrites `tags: [dev]`.
### YAML anchors for scripts
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23005) in GitLab 12.5.
You can use [YAML anchors](#anchors) with [script](index.md#script), [`before_script`](index.md#before_script),
and [`after_script`](index.md#after_script) to use predefined commands in multiple jobs:
```yaml
.some-script-before:&some-script-before
-echo "Execute this script first"
.some-script:&some-script
-echo "Execute this script second"
-echo "Execute this script too"
.some-script-after:&some-script-after
-echo "Execute this script last"
job1:
before_script:
-*some-script-before
script:
-*some-script
-echo "Execute something, for this job only"
after_script:
-*some-script-after
job2:
script:
-*some-script-before
-*some-script
-echo "Execute something else, for this job only"
-*some-script-after
```
### YAML anchors for variables
Use [YAML anchors](#anchors) with `variables` to repeat assignment
of variables across multiple jobs. You can also use YAML anchors when a job
requires a specific `variables` block that would otherwise override the global variables.
The following example shows how override the `GIT_STRATEGY` variable without affecting
