@@ -229,6 +229,15 @@ This functionality is only available:
- For users with at least the Developer role.
- 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
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24851) in GitLab 12.7.
-`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
...
...
@@ -1150,7 +1150,7 @@ The job is not added to the pipeline:
- If no rules match.
- 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.
#### `rules:if`
...
...
@@ -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 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.
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
All YAML-defined variables are also set to any linked
[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
...
...
@@ -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
[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
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
