README.md 158.3 KB
Newer Older
M
Marcia Ramos 已提交
1
---
2 3 4
stage: Verify
group: Continuous Integration
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/#designated-technical-writers
M
Marcia Ramos 已提交
5 6 7
type: reference
---

8
# GitLab CI/CD pipeline configuration reference
D
Douwe Maan 已提交
9

10
GitLab CI/CD [pipelines](../pipelines/index.md) are configured using a YAML file called `.gitlab-ci.yml` within each project.
11

E
Evan Read 已提交
12
The `.gitlab-ci.yml` file defines the structure and order of the pipelines and determines:
13

E
Evan Read 已提交
14 15 16 17 18 19 20 21 22 23
- What to execute using [GitLab Runner](https://docs.gitlab.com/runner/).
- What decisions to make when specific conditions are encountered. For example, when a process succeeds or fails.

This topic covers CI/CD pipeline configuration. For other CI/CD configuration information, see:

- [GitLab CI/CD Variables](../variables/README.md), for configuring the environment the pipelines run in.
- [GitLab Runner advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html), for configuring GitLab Runner.

We have complete examples of configuring pipelines:

24
- For a quick introduction to GitLab CI/CD, follow our [quick start guide](../quick_start/README.md).
E
Evan Read 已提交
25
- For a collection of examples, see [GitLab CI/CD Examples](../examples/README.md).
26
- To see a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml).
27

28 29 30 31 32 33 34
> For some additional information about GitLab CI/CD:
>
> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>&nbsp;Watch the [CI/CD Ease of configuration](https://www.youtube.com/embed/opdLqwz6tcE) video.
> - Watch the [Making the case for CI/CD in your organization](https://about.gitlab.com/compare/github-actions-alternative/)
>   webcast to learn the benefits of CI/CD and how to measure the results of CI/CD automation.
> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>&nbsp;Learn how [Verizon reduced rebuilds](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/)
>   from 30 days to under 8 hours with GitLab.
35

36
NOTE: **Note:**
37
If you have a [mirrored repository where GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter),
38 39 40
you may need to enable pipeline triggering in your project's
**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.

E
Evan Read 已提交
41 42 43
## Introduction

Pipeline configuration begins with jobs. Jobs are the most fundamental element of a `.gitlab-ci.yml` file.
44

E
Evan Read 已提交
45 46 47 48 49 50 51
Jobs are:

- Defined with constraints stating under what conditions they should be executed.
- Top-level elements with an arbitrary name and must contain at least the [`script`](#script) clause.
- Not limited in how many can be defined.

For example:
D
Douwe Maan 已提交
52 53 54 55 56 57 58 59 60

```yaml
job1:
  script: "execute-script-for-job1"

job2:
  script: "execute-script-for-job2"
```

61
The above example is the simplest possible CI/CD configuration with two separate
62 63 64
jobs, where each of the jobs executes a different command.
Of course a command can execute code directly (`./configure;make;make install`)
or run a script (`test.sh`) in the repository.
D
Douwe Maan 已提交
65

66 67 68
Jobs are picked up by [Runners](../runners/README.md) and executed within the
environment of the Runner. What is important, is that each job is run
independently from each other.
D
Douwe Maan 已提交
69

70
### Validate the `.gitlab-ci.yml`
E
Evan Read 已提交
71

72
Each instance of GitLab CI/CD has an embedded debug tool called Lint, which validates the
E
Evan Read 已提交
73
content of your `.gitlab-ci.yml` files. You can find the Lint under the page `ci/lint` of your
M
Marcel Amirault 已提交
74
project namespace. For example, `https://gitlab.example.com/gitlab-org/project-123/-/ci/lint`.
E
Evan Read 已提交
75 76 77

### Unavailable names for jobs

78
Each job must have a unique name, but there are a few **reserved `keywords` that
79
can't be used as job names**:
D
Douwe Maan 已提交
80

81 82 83 84 85 86 87 88
- `image`
- `services`
- `stages`
- `types`
- `before_script`
- `after_script`
- `variables`
- `cache`
89
- `include`
D
Douwe Maan 已提交
90

E
Evan Read 已提交
91 92 93 94 95 96 97 98 99 100 101 102 103
### Using reserved keywords

If you get validation error when using specific values (for example, `true` or `false`), try to:

- Quote them.
- Change them to a different form. For example, `/bin/true`.

## Configuration parameters

A job is defined as a list of parameters that define the job's behavior.

The following table lists available parameters for jobs:

104 105 106
| Keyword                                            | Description                                                                                                                                                                         |
|:---------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`script`](#script)                                | Shell script which is executed by Runner.                                                                                                                                           |
107 108
| [`image`](#image)                                  | Use Docker images. Also available: `image:name` and `image:entrypoint`.                                                                                                             |
| [`services`](#services)                            | Use Docker services images. Also available: `services:name`, `services:alias`, `services:entrypoint`, and `services:command`.                                                       |
109 110 111 112 113
| [`before_script`](#before_script-and-after_script) | Override a set of commands that are executed before job.                                                                                                                            |
| [`after_script`](#before_script-and-after_script)  | Override a set of commands that are executed after job.                                                                                                                             |
| [`stage`](#stage)                                  | Defines a job stage (default: `test`).                                                                                                                                              |
| [`only`](#onlyexcept-basic)                        | Limit when jobs are created. Also available: [`only:refs`, `only:kubernetes`, `only:variables`, and `only:changes`](#onlyexcept-advanced).                                          |
| [`except`](#onlyexcept-basic)                      | Limit when jobs are not created. Also available: [`except:refs`, `except:kubernetes`, `except:variables`, and `except:changes`](#onlyexcept-advanced).                              |
114
| [`rules`](#rules)                                  | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. May not be used alongside `only`/`except`.                             |
115
| [`tags`](#tags)                                    | List of tags which are used to select Runner.                                                                                                                                       |
116
| [`allow_failure`](#allow_failure)                  | Allow job to fail. Failed job does not contribute to commit status.                                                                                                                  |
117 118 119
| [`when`](#when)                                    | When to run job. Also available: `when:manual` and `when:delayed`.                                                                                                                  |
| [`environment`](#environment)                      | Name of an environment to which the job deploys. Also available: `environment:name`, `environment:url`, `environment:on_stop`, `environment:auto_stop_in` and `environment:action`. |
| [`cache`](#cache)                                  | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, and `cache:policy`.                                     |
120
| [`artifacts`](#artifacts)                          | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:exclude`, `artifacts:expose_as`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, `artifacts:reports`, `artifacts:reports:junit`, `artifacts:reports:cobertura`, and `artifacts:reports:terraform`.<br><br>In GitLab [Enterprise Edition](https://about.gitlab.com/pricing/), these are available: `artifacts:reports:codequality`, `artifacts:reports:sast`, `artifacts:reports:dependency_scanning`, `artifacts:reports:container_scanning`, `artifacts:reports:dast`, `artifacts:reports:license_scanning`, `artifacts:reports:license_management` (removed in GitLab 13.0), `artifacts:reports:performance`, `artifacts:reports:load_performance`, and `artifacts:reports:metrics`. |
121 122 123 124 125 126 127 128 129 130 131 132
| [`dependencies`](#dependencies)                    | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from.                                                                          |
| [`coverage`](#coverage)                            | Code coverage settings for a given job.                                                                                                                                             |
| [`retry`](#retry)                                  | When and how many times a job can be auto-retried in case of a failure.                                                                                                             |
| [`timeout`](#timeout)                              | Define a custom job-level timeout that takes precedence over the project-wide setting.                                                                                              |
| [`parallel`](#parallel)                            | How many instances of a job should be run in parallel.                                                                                                                              |
| [`trigger`](#trigger)                              | Defines a downstream pipeline trigger.                                                                                                                                              |
| [`include`](#include)                              | Allows this job to include external YAML files. Also available: `include:local`, `include:file`, `include:template`, and `include:remote`.                                          |
| [`extends`](#extends)                              | Configuration entries that this job is going to inherit from.                                                                                                                       |
| [`pages`](#pages)                                  | Upload the result of a job to use with GitLab Pages.                                                                                                                                |
| [`variables`](#variables)                          | Define job variables on a job level.                                                                                                                                                |
| [`interruptible`](#interruptible)                  | Defines if a job can be canceled when made redundant by a newer run.                                                                                                                |
| [`resource_group`](#resource_group)                | Limit job concurrency.                                                                                                                                                              |
133
| [`release`](#release) | Instructs the Runner to generate a [Release](../../user/project/releases/index.md) object. |
E
Evan Read 已提交
134 135 136 137

NOTE: **Note:**
Parameters `types` and `type` are [deprecated](#deprecated-parameters).

138 139 140 141 142
## Global parameters

Some parameters must be defined at a global level, affecting all jobs in the pipeline.

### Global defaults
K
Kamil Trzciński 已提交
143 144 145 146 147 148 149 150 151 152 153

Some parameters can be set globally as the default for all jobs using the
`default:` keyword. Default parameters can then be overridden by job-specific
configuration.

The following job parameters can be defined inside a `default:` block:

- [`image`](#image)
- [`services`](#services)
- [`before_script`](#before_script-and-after_script)
- [`after_script`](#before_script-and-after_script)
154
- [`tags`](#tags)
K
Kamil Trzciński 已提交
155
- [`cache`](#cache)
156
- [`artifacts`](#artifacts)
157
- [`retry`](#retry)
158
- [`timeout`](#timeout)
159
- [`interruptible`](#interruptible)
K
Kamil Trzciński 已提交
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175

In the following example, the `ruby:2.5` image is set as the default for all
jobs except the `rspec 2.6` job, which uses the `ruby:2.6` image:

```yaml
default:
  image: ruby:2.5

rspec:
  script: bundle exec rspec

rspec 2.6:
  image: ruby:2.6
  script: bundle exec rspec
```

176
#### `inherit`
177

178
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9.
179 180 181 182

You can disable inheritance of globally defined defaults
and variables with the `inherit:` parameter.

183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
To enable or disable the inheritance of all `variables:` or `default:` parameters, use the following format:

- `default: true` or `default: false`
- `variables: true` or `variables: false`

To inherit only a subset of `default:` parameters or `variables:`, specify what
you wish to inherit, and any not listed will **not** be inherited. Use
one of the following formats:

```yaml
inherit:
  default: [parameter1, parameter2]
  variables: [VARIABLE1, VARIABLE2]
```

Or:

```yaml
inherit:
  default:
    - parameter1
    - parameter2
  variables:
    - VARIABLE1
    - VARIABLE2
```

210 211
In the example below:

212 213 214 215
- `rubocop`:
  - **will** inherit: Nothing.
- `rspec`:
  - **will** inherit: the default `image` and the `WEBHOOK_URL` variable.
216
  - will **not** inherit: the default `before_script` and the `DOMAIN` variable.
217 218
- `capybara`:
  - **will** inherit: the default `before_script` and `image`.
219
  - will **not** inherit: the `DOMAIN` and `WEBHOOK_URL` variables.
220 221
- `karma`:
  - **will** inherit: the default `image` and `before_script`, and the `DOMAIN` variable.
222
  - will **not** inherit: `WEBHOOK_URL` variable.
223 224 225

```yaml
default:
226
  image: 'ruby:2.4'
227 228 229 230 231
  before_script:
    - echo Hello World

variables:
  DOMAIN: example.com
232
  WEBHOOK_URL: https://my-webhook.example.com
233 234

rubocop:
235 236 237
  inherit:
    default: false
    variables: false
238 239 240 241
  script: bundle exec rubocop

rspec:
  inherit:
242 243
    default: [image]
    variables: [WEBHOOK_URL]
244 245 246 247 248 249
  script: bundle exec rspec

capybara:
  inherit:
    variables: false
  script: bundle exec capybara
250 251 252 253 254 255

karma:
  inherit:
    default: true
    variables: [DOMAIN]
  script: karma
256 257
```

258
### `stages`
E
Evan Read 已提交
259

260 261
`stages` is used to define stages that contain jobs and is defined
globally for the pipeline.
E
Evan Read 已提交
262

263 264
The specification of `stages` allows for having flexible multi stage pipelines.
The ordering of elements in `stages` defines the ordering of jobs' execution:
E
Evan Read 已提交
265

266 267 268 269 270
1. Jobs of the same stage are run in parallel.
1. Jobs of the next stage are run after the jobs from the previous stage
   complete successfully.

Let's consider the following example, which defines 3 stages:
E
Evan Read 已提交
271 272

```yaml
273 274 275 276
stages:
  - build
  - test
  - deploy
E
Evan Read 已提交
277 278
```

279 280 281 282 283 284
1. First, all jobs of `build` are executed in parallel.
1. If all jobs of `build` succeed, the `test` jobs are executed in parallel.
1. If all jobs of `test` succeed, the `deploy` jobs are executed in parallel.
1. If all jobs of `deploy` succeed, the commit is marked as `passed`.
1. If any of the previous jobs fails, the commit is marked as `failed` and no
   jobs of further stage are executed.
285

286
There are also two edge cases worth mentioning:
E
Evan Read 已提交
287

288 289
1. If no `stages` are defined in `.gitlab-ci.yml`, then the `build`,
   `test` and `deploy` are allowed to be used as job's stage by default.
290
1. If a job does not specify a `stage`, the job is assigned the `test` stage.
E
Evan Read 已提交
291

292
### `workflow:rules`
E
Evan Read 已提交
293

294
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5
295

296 297 298 299
The top-level `workflow:` key applies to the entirety of a pipeline, and will
determine whether or not a pipeline is created. It currently accepts a single
`rules:` key that operates similarly to [`rules:` defined within jobs](#rules),
enabling dynamic configuration of the pipeline.
300

301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320
If you are new to GitLab CI/CD and `workflow: rules`, you may find the [`workflow:rules` templates](#workflowrules-templates) useful.

To define your own `workflow: rules`, the configuration options currently available are:

- [`if`](#rulesif): Define a rule.
- [`when`](#when): May be set to `always` or `never` only. If not provided, the default value is `always`​.

The list of `if` rules is evaluated until a single one is matched. If none
match, the last `when` will be used:

```yaml
workflow:
  rules:
    - if: $CI_COMMIT_REF_NAME =~ /-wip$/
      when: never
    - if: $CI_COMMIT_TAG
      when: never
    - when: always
```

321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357
#### `workflow:rules` templates

> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0.

We provide pre-made templates for use with your pipelines that set up `workflow: rules`
for common scenarios. Usage of these will make things easier and prevent duplicate pipelines from running.

The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml)
makes your pipelines run for branches and tags.

Branch pipeline status will be displayed within merge requests that use that branch
as a source, but this pipeline type does not support any features offered by
[Merge Request Pipelines](../merge_request_pipelines/) like
[Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results-premium)
or [Merge Trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/).
Use this template if you are intentionally avoiding those features.

It is [included](#include) as follows:

```yaml
include:
  - template: 'Workflows/Branch-Pipelines.gitlab-ci.yml'
```

The [`MergeRequest-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/MergeRequest-Pipelines.gitlab-ci.yml)
makes your pipelines run for the default branch (usually `master`), tags, and
all types of merge request pipelines. Use this template if you use any of the
the [Pipelines for Merge Requests features](../merge_request_pipelines/), as mentioned
above.

It is [included](#include) as follows:

```yaml
include:
  - template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'
```

358
### `include`
E
Evan Read 已提交
359

360 361
> - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5.
> - Available for Starter, Premium and Ultimate since 10.6.
362
> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Core in 11.4.
E
Evan Read 已提交
363

364 365
Using the `include` keyword allows the inclusion of external YAML files. This helps
to break down the CI/CD configuration into multiple files and increases readability for long configuration files.
366
It's also possible to have template files stored in a central repository and projects include their
367 368
configuration files. This helps avoid duplicated configuration, for example, global default variables for all projects.

369
`include` requires the external YAML file to have the extensions `.yml` or `.yaml`,
370
otherwise the external file won't be included.
E
Evan Read 已提交
371

372 373 374 375 376 377 378 379 380
`include` supports the following inclusion methods:

| Method                          | Description                                                       |
|:--------------------------------|:------------------------------------------------------------------|
| [`local`](#includelocal)        | Include a file from the local project repository.                 |
| [`file`](#includefile)          | Include a file from a different project repository.               |
| [`remote`](#includeremote)      | Include a file from a remote URL. Must be publicly accessible.    |
| [`template`](#includetemplate)  | Include templates which are provided by GitLab.                   |

381 382
The `include` methods do not support [variable expansion](../variables/where_variables_can_be_used.md#variables-usage).

383 384 385
NOTE: **Note:**
`.gitlab-ci.yml` configuration included by all methods is evaluated at pipeline creation.
The configuration is a snapshot in time and persisted in the database. Any changes to
386
referenced `.gitlab-ci.yml` configuration won't be reflected in GitLab until the next pipeline is created.
387

388
The files defined by `include` are:
E
Evan Read 已提交
389

390 391 392
- Deep merged with those in `.gitlab-ci.yml`.
- Always evaluated first and merged with the content of `.gitlab-ci.yml`,
  regardless of the position of the `include` keyword.
E
Evan Read 已提交
393

394 395
TIP: **Tip:**
Use merging to customize and override included CI/CD configurations with local
396
definitions. Local definitions in `.gitlab-ci.yml` will override included definitions.
E
Evan Read 已提交
397

398
NOTE: **Note:**
399 400
Using [YAML anchors](#anchors) across different YAML files sourced by `include` is not
supported. You must only refer to anchors in the same file. Instead
401
of using YAML anchors, you can use the [`extends` keyword](#extends).
E
Evan Read 已提交
402

403
#### `include:local`
E
Evan Read 已提交
404

405 406
`include:local` includes a file from the same repository as `.gitlab-ci.yml`.
It's referenced using full paths relative to the root directory (`/`).
E
Evan Read 已提交
407

408 409 410
You can only use files that are currently tracked by Git on the same branch
your configuration file is on. In other words, when using a `include:local`, make
sure that both `.gitlab-ci.yml` and the local file are on the same branch.
E
Evan Read 已提交
411

412
All [nested includes](#nested-includes) will be executed in the scope of the same project,
413
so it's possible to use local, project, remote, or template includes.
E
Evan Read 已提交
414

415 416
NOTE: **Note:**
Including local files through Git submodules paths is not supported.
E
Evan Read 已提交
417

418
Example:
E
Evan Read 已提交
419

420 421 422 423
```yaml
include:
  - local: '/templates/.gitlab-ci-template.yml'
```
E
Evan Read 已提交
424

425 426 427 428 429 430 431 432 433
TIP: **Tip:**
Local includes can be used as a replacement for symbolic links which are not followed.

This can be defined as a short local include:

```yaml
include: '.gitlab-ci-production.yml'
```

434
#### `include:file`
E
Evan Read 已提交
435

436
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7.
E
Evan Read 已提交
437

438 439 440
To include files from another private project under the same GitLab instance,
use `include:file`. This file is referenced using full paths relative to the
root directory (`/`). For example:
E
Evan Read 已提交
441

442 443 444 445 446
```yaml
include:
  - project: 'my-group/my-project'
    file: '/templates/.gitlab-ci-template.yml'
```
E
Evan Read 已提交
447

448
You can also specify `ref`, with the default being the `HEAD` of the project:
E
Evan Read 已提交
449

450 451 452 453 454
```yaml
include:
  - project: 'my-group/my-project'
    ref: master
    file: '/templates/.gitlab-ci-template.yml'
E
Evan Read 已提交
455

456 457 458
  - project: 'my-group/my-project'
    ref: v1.0.0
    file: '/templates/.gitlab-ci-template.yml'
K
Kamil Trzcinski 已提交
459

460 461 462 463
  - project: 'my-group/my-project'
    ref: 787123b47f14b552955ca2786bc9542ae66fee5b # Git SHA
    file: '/templates/.gitlab-ci-template.yml'
```
464

465
All [nested includes](#nested-includes) will be executed in the scope of the target project,
466
so it's possible to use local (relative to target project), project, remote
467
or template includes.
468

469 470 471 472 473 474 475 476 477 478 479 480 481 482 483
#### `include:remote`

`include:remote` can be used to include a file from a different location,
using HTTP/HTTPS, referenced by using the full URL. The remote file must be
publicly accessible through a simple GET request as authentication schemas
in the remote URL are not supported. For example:

```yaml
include:
  - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'
```

All [nested includes](#nested-includes) will be executed without context as public user, so only another remote
or public project, or template, is allowed.

484
#### `include:template`
485

486
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53445) in GitLab 11.7.
487

488 489
`include:template` can be used to include `.gitlab-ci.yml` templates that are
[shipped with GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates).
490

491
For example:
492

493
```yaml
494 495 496
# File sourced from GitLab's template collection
include:
  - template: Auto-DevOps.gitlab-ci.yml
497 498
```

499
Multiple `include:template` files:
D
Douwe Maan 已提交
500

501 502 503 504 505
```yaml
include:
  - template: Android-Fastlane.gitlab-ci.yml
  - template: Auto-DevOps.gitlab-ci.yml
```
506

507
All [nested includes](#nested-includes) will be executed only with the permission of the user,
508
so it's possible to use project, remote or template includes.
D
Douwe Maan 已提交
509

510
#### Nested includes
511

512
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56836) in GitLab 11.9.
513

514
Nested includes allow you to compose a set of includes.
515

516
A total of 100 includes is allowed, but duplicate includes are considered a configuration error.
517

518
Since [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/28212), the time limit
519
for resolving all files is 30 seconds.
520

521
#### Additional `includes` examples
522

523
There is a list of [additional `includes` examples](includes.md) available.
524

525
## Parameter details
526

527
The following are detailed explanations for parameters used to configure CI/CD pipelines.
528

529
### `image`
530

531
Used to specify [a Docker image](../docker/using_docker_images.md#what-is-an-image) to use for the job.
532

533
For:
534

535 536
- Simple definition examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml).
- Detailed usage information, refer to [Docker integration](../docker/README.md) documentation.
537

538
#### `image:name`
539

540
An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
541

542
For more information, see [Available settings for `image`](../docker/using_docker_images.md#available-settings-for-image).
543

544
#### `image:entrypoint`
545

546
An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
547

548
For more information, see [Available settings for `image`](../docker/using_docker_images.md#available-settings-for-image).
549

550
#### `services`
551

552
Used to specify a [service Docker image](../docker/using_docker_images.md#what-is-a-service), linked to a base image specified in [`image`](#image).
553

554
For:
555

556 557 558
- Simple definition examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml).
- Detailed usage information, refer to [Docker integration](../docker/README.md) documentation.
- For example services, see [GitLab CI/CD Services](../services/README.md).
559

560
##### `services:name`
561

562
An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
563

564
For more information, see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services).
565

566
##### `services:alias`
567

568
An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
569

570
For more information, see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services).
571

572
##### `services:entrypoint`
573

574
An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
575

576
For more information, see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services).
577

578
##### `services:command`
579

580
An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
581

582
For more information, see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services).
583

584 585 586 587
### `script`

`script` is the only required keyword that a job needs. It's a shell script
which is executed by the Runner. For example:
588 589

```yaml
590 591
job:
  script: "bundle exec rspec"
592 593
```

594 595 596
[YAML anchors for scripts](#yaml-anchors-for-script) are available.

This parameter can also contain several commands using an array:
597 598

```yaml
599 600 601 602
job:
  script:
    - uname -a
    - bundle exec rspec
603 604
```

605 606 607 608 609 610
NOTE: **Note:**
Sometimes, `script` commands will need to be wrapped in single or double quotes.
For example, commands that contain a colon (`:`) need to be wrapped in quotes so
that the YAML parser knows to interpret the whole thing as a string rather than
a "key: value" pair. Be careful when using special characters:
`:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.
611

612
If any of the script commands return an exit code different from zero, the job
613
will fail and further commands won't be executed. This behavior can be avoided by
614
storing the exit code in a variable:
615

616 617 618 619 620 621
```yaml
job:
  script:
    - false || exit_code=$?
    - if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi;
```
622

623
#### `before_script` and `after_script`
624

625
> Introduced in GitLab 8.7 and requires GitLab Runner v1.2.
626

627 628 629
`before_script` is used to define a command that should be run before each
job, including deploy jobs, but after the restoration of any [artifacts](#artifacts).
This must be an array.
630

631 632
Scripts specified in `before_script` are concatenated with any scripts specified
in the main [`script`](#script), and executed together in a single shell.
633

634 635
`after_script` is used to define the command that will be run after each
job, including failed ones. This must be an array.
636

637 638
Scripts specified in `after_script` are executed in a new shell, separate from any
`before_script` or `script` scripts. As a result, they:
639

640 641 642 643 644 645
- Have a current working directory set back to the default.
- Have no access to changes done by scripts defined in `before_script` or `script`, including:
  - Command aliases and variables exported in `script` scripts.
  - Changes outside of the working tree (depending on the Runner executor), like
    software installed by a `before_script` or `script` script.
- Have a separate timeout, which is hard coded to 5 minutes. See
646
  [related issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2716) for details.
647
- Don't affect the job's exit code. If the `script` section succeeds and the
648
  `after_script` times out or fails, the job will exit with code `0` (`Job Succeeded`).
649

650 651
It's possible to overwrite a globally defined `before_script` or `after_script`
if you set it per-job:
652 653

```yaml
654 655 656
default:
  before_script:
    - global before script
657

658 659 660 661 662 663 664
job:
  before_script:
    - execute this instead of global before script
  script:
    - my command
  after_script:
    - execute this after my script
665 666
```

667
[YAML anchors for `before_script` and `after_script`](#yaml-anchors-for-before_script-and-after_script) are available.
668

669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706
#### Coloring script output

Script output can be colored using [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors),
or by running commands or programs that output ANSI escape codes.

For example, using [Bash with color codes](https://misc.flogisoft.com/bash/tip_colors_and_formatting):

```yaml
job:
  script:
    - echo -e "\e[31mThis text is red,\e[0m but this text isn't\e[31m however this text is red again."
```

You can define the color codes in Shell variables, or even [custom environment variables](../variables/README.md#custom-environment-variables),
which makes the commands easier to read and reusable.

For example, using the same example as above and variables defined in a `before_script`:

```yaml
job:
  before_script:
    - TXT_RED="\e[31m" && TXT_CLEAR="\e[0m"
  script:
    - echo -e "${TXT_RED}This text is red,${TXT_CLEAR} but this part isn't${TXT_RED} however this part is again."
    - echo "This text is not colored"
```

Or with [PowerShell color codes](https://superuser.com/a/1259916):

```yaml
job:
  before_script:
    - $esc="$([char]27)"; $TXT_RED="$esc[31m"; $TXT_CLEAR="$esc[0m"
  script:
    - Write-Host $TXT_RED"This text is red,"$TXT_CLEAR" but this text isn't"$TXT_RED" however this text is red again."
    - Write-Host "This text is not colored"
```

707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801
#### Multiline commands

You can split long commands into multi-line commands to improve readability
using [`|` (literal) and `>` (folded) YAML multiline block scalar indicators](https://yaml-multiline.info/).

CAUTION: **Warning:**
If multiple commands are combined into one command string, only the last command's
failure or success will be reported,
[incorrectly ignoring failures from earlier commands due to a bug](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25394).
If the success of the job depends on the success or failure of these commands,
you can run the commands as separate `script:` items, or add `exit 1` commands
as appropriate to the command string where needed.

You can use the `|` (literal) YAML multiline block scalar indicator to write
commands over multiple lines in the `script` section of a job description.
Each line is treated as a separate command.
Only the first command is repeated in the job log, but additional
commands are still executed:

```yaml
job:
  script:
    - |
      echo "First command line."
      echo "Second command line."
      echo "Third command line."
```

The example above renders in the job log as:

```shell
$ echo First command line # collapsed multi-line command
First command line
Second command line.
Third command line.
```

The `>` (folded) YAML multiline block scalar indicator treats empty lines between
sections as the start of a new command:

```yaml
job:
  script:
    - >
      echo "First command line
      is split over two lines."

      echo "Second command line."
```

This behaves similarly to writing multiline commands without the `>` or `|` block
scalar indicators:

```yaml
job:
  script:
    - echo "First command line
      is split over two lines."

      echo "Second command line."
```

Both examples above render in the job log as:

```shell
$ echo First command line is split over two lines. # collapsed multi-line command
First command line is split over two lines.
Second command line.
```

When the `>` or `|` block scalar indicators are omitted, GitLab will form the command
by concatenating non-empty lines, so make sure the lines can run when concatenated.

Shell [here documents](https://en.wikipedia.org/wiki/Here_document) work with the
`|` and `>` operators as well. The example below transliterates the lower case letters
to upper case:

```yaml
job:
  script:
    - |
      tr a-z A-Z << END_TEXT
        one two three
        four five six
      END_TEXT
```

Results in:

```shell
$ tr a-z A-Z << END_TEXT # collapsed multi-line command
  ONE TWO THREE
  FOUR FIVE SIX
```

802
### `stage`
803

804 805 806
`stage` is defined per-job and relies on [`stages`](#stages) which is defined
globally. It allows to group jobs into different stages, and jobs of the same
`stage` are executed in parallel (subject to [certain conditions](#using-your-own-runners)). For example:
807

808 809 810 811 812
```yaml
stages:
  - build
  - test
  - deploy
813

814 815 816
job 0:
  stage: .pre
  script: make something useful before build stage
817

818 819 820
job 1:
  stage: build
  script: make build dependencies
821

822 823 824
job 2:
  stage: build
  script: make build artifacts
825

826 827 828
job 3:
  stage: test
  script: make test
829

830 831 832
job 4:
  stage: deploy
  script: make deploy
833

834 835 836
job 5:
  stage: .post
  script: make something useful at the end of pipeline
837 838
```

839
#### Using your own Runners
840

841 842 843
When using your own Runners, GitLab Runner runs only one job at a time by default (see the
`concurrent` flag in [Runner global settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section)
for more information).
844

845
Jobs will run on your own Runners in parallel only if:
846

847 848
- Run on different Runners.
- The Runner's `concurrent` setting has been changed.
849

850
#### `.pre` and `.post`
851

852
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) in GitLab 12.4.
853

854
The following stages are available to every pipeline:
855

856 857
- `.pre`, which is guaranteed to always be the first stage in a pipeline.
- `.post`, which is guaranteed to always be the last stage in a pipeline.
858

859
User-defined stages are executed after `.pre` and before `.post`.
E
Evan Read 已提交
860

861
The order of `.pre` and `.post` can't be changed, even if defined out of order in `.gitlab-ci.yml`.
862
For example, the following are equivalent configuration:
863

864
- Configured in order:
865

866
  ```yaml
867 868 869 870 871 872
  stages:
    - .pre
    - a
    - b
    - .post
  ```
873

874
- Configured out of order:
875

876
  ```yaml
877 878 879 880 881 882
  stages:
    - a
    - .pre
    - b
    - .post
  ```
883

884
- Not explicitly configured:
E
Evan Read 已提交
885

886
  ```yaml
887 888 889 890
  stages:
    - a
    - b
  ```
891

892
NOTE: **Note:**
893
A pipeline won't be created if it only contains jobs in `.pre` or `.post` stages.
894

895
### `extends`
896

897
> Introduced in GitLab 11.3.
898

899 900
`extends` defines entry names that a job that uses `extends` is going to
inherit from.
901

902
It's an alternative to using [YAML anchors](#anchors) and is a little
903
more flexible and readable:
904

905 906 907 908 909 910 911
```yaml
.tests:
  script: rake test
  stage: test
  only:
    refs:
      - branches
912

913 914 915 916 917 918 919
rspec:
  extends: .tests
  script: rake rspec
  only:
    variables:
      - $RSPEC
```
E
Evan Read 已提交
920

921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944
In the example above, the `rspec` job inherits from the `.tests` template job.
GitLab will perform a reverse deep merge based on the keys. GitLab will:

- Merge the `rspec` contents into `.tests` recursively.
- Not merge the values of the keys.

This results in the following `rspec` job:

```yaml
rspec:
  script: rake rspec
  stage: test
  only:
    refs:
      - branches
    variables:
      - $RSPEC
```

NOTE: **Note:**
Note that `script: rake test` has been overwritten by `script: rake rspec`.

If you do want to include the `rake test`, see [`before_script` and `after_script`](#before_script-and-after_script).

945
`.tests` in this example is a [hidden job](#hide-jobs), but it's
946 947
possible to inherit from regular jobs as well.

948
`extends` supports multi-level inheritance, however it's not recommended to
949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976
use more than three levels. The maximum nesting level that is supported is 10.
The following example has two levels of inheritance:

```yaml
.tests:
  only:
    - pushes

.rspec:
  extends: .tests
  script: rake rspec

rspec 1:
  variables:
    RSPEC_SUITE: '1'
  extends: .rspec

rspec 2:
  variables:
    RSPEC_SUITE: '2'
  extends: .rspec

spinach:
  extends: .tests
  script: rake spinach
```

In GitLab 12.0 and later, it's also possible to use multiple parents for
977 978 979 980 981 982 983
`extends`.

#### Merge details

`extends` is able to merge hashes but not arrays.
The algorithm used for merge is "closest scope wins", so
keys from the last member will always override anything defined on other
984 985 986 987
levels. For example:

```yaml
.only-important:
988 989 990
  variables:
    URL: "http://my-url.internal"
    IMPORTANT_VAR: "the details"
991 992 993 994 995
  only:
    - master
    - stable
  tags:
    - production
996 997
  script:
    - echo "Hello world!"
998 999

.in-docker:
1000 1001
  variables:
    URL: "http://docker-url.internal"
1002 1003 1004 1005 1006
  tags:
    - docker
  image: alpine

rspec:
1007 1008
  variables:
    GITLAB: "is-awesome"
1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019
  extends:
    - .only-important
    - .in-docker
  script:
    - rake rspec
```

This results in the following `rspec` job:

```yaml
rspec:
1020 1021 1022 1023
  variables:
    URL: "http://docker-url.internal"
    IMPORTANT_VAR: "the details"
    GITLAB: "is-awesome"
1024 1025 1026 1027 1028 1029 1030 1031 1032 1033
  only:
    - master
    - stable
  tags:
    - docker
  image: alpine
  script:
    - rake rspec
```

1034 1035 1036 1037 1038 1039 1040 1041 1042
Note that in the example above:

- `variables` sections have been merged but that `URL: "http://my-url.internal"`
has been overwritten by `URL: "http://docker-url.internal"`.
- `tags: ['production']` has been overwritten by `tags: ['docker']`.
- `script` has not been merged but rather `script: ['echo "Hello world!"']` has
  been overwritten by `script: ['rake rspec']`. Arrays can be
  merged using [YAML anchors](#anchors).

1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069
#### Using `extends` and `include` together

`extends` works across configuration files combined with `include`.

For example, if you have a local `included.yml` file:

```yaml
.template:
  script:
    - echo Hello!
```

Then, in `.gitlab-ci.yml` you can use it like this:

```yaml
include: included.yml

useTemplate:
  image: alpine
  extends: .template
```

This will run a job called `useTemplate` that runs `echo Hello!` as defined in
the `.template` job, and uses the `alpine` Docker image as defined in the local job.

### `rules`

1070
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3.
1071

1072 1073 1074 1075 1076 1077 1078
The `rules` keyword is a way to set job policies that determine whether or not jobs
are added to pipelines.

A list of individual rule clauses are evaluated *in order*, until one matches. When
matched, the job is either included or excluded from the pipeline, depending
on the configuration. If included, the job also has [certain attributes](#rules-attributes)
added to it.
1079 1080

CAUTION: **Caution:**
1081 1082
`rules` can't be used in combination with [`only/except`](#onlyexcept-basic) because it is a replacement for
that functionality. If you attempt to do this, the linter returns a
1083 1084
`key may not be used with rules` error.

1085
#### Rules attributes
1086

1087
The job attributes allowed by `rules` are:
1088

1089 1090 1091 1092
- [`when`](#when): If not defined, defaults to `when: on_success`.
  - If used as `when: delayed`, `start_in` is also required.
- [`allow_failure`](#allow_failure): If not defined, defaults to `allow_failure: false`.

1093
If a rule evaluates to true, and `when` has any value except `never`, the job is included in the pipeline.
1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112

For example:

```yaml
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: '$CI_COMMIT_BRANCH == "master"'
      when: delayed
      start_in: '3 hours'
      allow_failure: true
```

Additional job configuration may be added to rules in the future. If something
useful is not available, please [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues).

#### Rules clauses

Available rule clauses are:
1113

1114 1115 1116 1117 1118
| Clause                     | Description                                                                                                                        |
|----------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| [`if`](#rulesif)           | Add or exclude jobs from a pipeline by evaluating an `if` statement. Similar to [`only:variables`](#onlyvariablesexceptvariables). |
| [`changes`](#ruleschanges) | Add or exclude jobs from a pipeline based on what files are changed. Same as [`only:changes`](#onlychangesexceptchanges).          |
| [`exists`](#rulesexists)   | Add or exclude jobs from a pipeline based on the presence of specific files.                                                       |
1119

1120 1121 1122
Rules are evaluated in order until a match is found. If a match is found, the attributes
are checked to see if the job should be added to the pipeline. If no attributes are defined,
the defaults are:
1123

1124 1125
- `when: on_success`
- `allow_failure: false`
1126

1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139
The job is added to the pipeline:

- If a rule matches and has `when: on_success`, `when: delayed` or `when: always`.
- If no rules match, but the last clause is `when: on_success`, `when: delayed`
  or `when: always` (with no rule).

The job is not added to the pipeline:

- If no rules match, and there is no standalone `when: on_success`, `when: delayed` or
  `when: always`.
- If a rule matches, and has `when: never` as the attribute.

For example, using `if` clauses to strictly limit when jobs run:
1140 1141 1142 1143 1144

```yaml
job:
  script: "echo Hello, Rules!"
  rules:
1145
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
1146
      when: manual
1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177
      allow_failure: true
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
```

In this example:

- If the pipeline is for a merge request, the first rule matches, and the job
  is added to the [merge request pipeline](../merge_request_pipelines/index.md)
  with attributes of:
  - `when: manual` (manual job)
  - `allow_failure: true` (allows the pipeline to continue running even if the manual job is not run)
- If the pipeline is **not** for a merge request, the first rule doesn't match, and the
  second rule is evaluated.
- If the pipeline is a scheduled pipeline, the second rule matches, and the job
  is added to the scheduled pipeline. Since no attributes were defined, it is added
  with:
  - `when: on_success` (default)
  - `allow_failure: false` (default)
- In **all other cases**, no rules match, so the job is **not** added to any other pipeline.

Alternatively, you can define a set of rules to exclude jobs in a few cases, but
run them in all other cases:

```yaml
job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: never
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: never
1178 1179 1180
    - when: on_success
```

1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193
- 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.
- In **all other cases**, the job is added to the pipeline, with `when: on_success`.

CAUTION: **Caution**
If you use `when: on_success`, `always`, or `delayed` as the final rule, two
simultaneous pipelines may start. Both push pipelines and merge request pipelines can
be triggered by the same event (a push to the source branch for an open merge request).
See the [important differences between `rules` and `only`/`except`](#differences-between-rules-and-onlyexcept)
for more details.

#### Differences between `rules` and `only`/`except`

1194 1195 1196 1197 1198
Jobs defined with `only/except` do not trigger merge request pipelines by default.
You must explicitly add `only: merge_requests`.

Jobs defined with `rules` can trigger all types of pipelines.
You do not have to explicitly configure each type.
1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215

For example:

```yaml
job:
  script: "echo This creates double pipelines!"
  rules:
    - if: '$CUSTOM_VARIABLE == "false"'
      when: never
    - when: always
```

This job does not run when `$CUSTOM_VARIABLE` is false, but it *does* run in **all**
other pipelines, including **both** push (branch) and merge request pipelines. With
this configuration, every push to an open merge request's source branch
causes duplicated pipelines. Explicitly allowing both push and merge request pipelines
in the same job could have the same effect.
1216

1217 1218 1219 1220
We recommend using [`workflow: rules`](#workflowrules) to limit which types of pipelines
are permitted. Allowing only merge request pipelines, or only branch pipelines,
eliminates duplicated pipelines. Alternatively, you can rewrite the rules to be
stricter, or avoid using a final `when` (`always`, `on_success` or `delayed`).
1221

1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233
Also, we don't recommend mixing `only/except` jobs with `rules` jobs in the same pipeline.
It may not cause YAML errors, but debugging the exact execution behavior can be complex
due to the different default behaviors of `only/except` and `rules`.

##### `rules:if`

`rules:if` clauses determine whether or not jobs are added to a pipeline by evaluating
a simple `if` statement. If the `if` statement is true, the job is either included
or excluded from a pipeline. In plain English, `if` rules can be interpreted as one of:

- "If this rule evaluates to true, add the job" (default).
- "If this rule evaluates to true, do not add the job" (by adding `when: never`).
1234 1235

`rules:if` differs slightly from `only:variables` by accepting only a single
1236 1237
expression string per rule, rather than an array of them. Any set of expressions to be
evaluated can be conjoined into a single expression by using `&&` or `||`, and use
1238
the [variable matching syntax](../variables/README.md#syntax-of-environment-variable-expressions).
1239

1240 1241 1242
`if:` clauses are evaluated based on the values of [predefined environment variables](../variables/predefined_variables.md)
or [custom environment variables](../variables/README.md#custom-environment-variables).

1243 1244 1245 1246 1247 1248
For example:

```yaml
job:
  script: "echo Hello, Rules!"
  rules:
1249
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'
1250
      when: always
1251
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/'
1252
      when: manual
1253 1254
      allow_failure: true
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # Checking for the presence of a variable is possible
1255 1256
```

1257 1258
Some details regarding the logic that determines the `when` for the job:

1259
- If none of the provided rules match, the job is set to `when: never` and is
1260 1261 1262
  not included in the pipeline.
- A rule without any conditional clause, such as a `when` or `allow_failure`
  rule without `if` or `changes`, always matches, and is always used if reached.
1263
- If a rule matches and has no `when` defined, the rule uses the `when`
1264
  defined for the job, which defaults to `on_success` if not defined.
1265 1266
- You can define `when` once per rule, or once at the job-level, which applies to
  all rules. You can't mix `when` at the job-level with `when` in rules.
1267

1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327
For behavior similar to the [`only`/`except` keywords](#onlyexcept-basic), you can
check the value of the `$CI_PIPELINE_SOURCE` variable.

| Value                         | Description                                                                                                                                                                                                                                                                                                                                           |
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `push`                        | For pipelines triggered by a `git push` event, including for branches and tags.                                                                                                                                                                                                                                                                       |
| `web`                         | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section.                                                                                                                                                                                                                            |
| `trigger`                     | For pipelines created by using a trigger token.                                                                                                                                                                                                                                                                                                       |
| `schedule`                    | For [scheduled pipelines](../pipelines/schedules.md).                                                                                                                                                                                                                                                                                                 |
| `api`                         | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline).                                                                                                                                                                                                                                                         |
| `external`                    | When using CI services other than GitLab.                                                                                                                                                                                                                                                                                                             |
| `pipelines`                   | For multi-project pipelines created by [using the API with `CI_JOB_TOKEN`](../triggers/README.md#when-used-with-multi-project-pipelines).                                                                                                                                                                                                             |
| `chat`                        | For pipelines created by using a [GitLab ChatOps](../chatops/README.md) command.                                                                                                                                                                                                                                                                      |
| `webide`                      | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md).                                                                                                                                                                                                                                                                     |
| `merge_request_event`         | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). |
| `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests).                                                                                                                                                                 |
| `parent_pipeline`             | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`, use this in the child pipeline configuration so that it can be triggered by the parent pipeline.                                                                                                                                                     |

For example:

```yaml
job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: manual
      allow_failure: true
    - if: '$CI_PIPELINE_SOURCE == "push"'
```

This example runs the job as a manual job in scheduled pipelines or in push
pipelines (to branches or tags), with `when: on_success` (default). It does not
add the job to any other pipeline type.

Another example:

```yaml
job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
```

This example runs the job as a `when: on_success` job in [merge request pipelines](../merge_request_pipelines/index.md)
and scheduled pipelines. It does not run in any other pipeline type.

Other commonly used variables for `if` clauses:

- `if: $CI_COMMIT_TAG`: If changes are pushed for a tag.
- `if: $CI_COMMIT_BRANCH`: If changes are pushed to any branch.
- `if: '$CI_COMMIT_BRANCH == "master"'`: If changes are pushed to `master`.
- `if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'`: If changes are pushed to the default
  branch (usually `master`). Useful if reusing the same configuration in multiple
  projects with potentially different default branches.
- `if: '$CI_COMMIT_BRANCH =~ /regex-expression/'`: If the commit branch matches a regular expression.
- `if: '$CUSTOM_VARIABLE !~ /regex-expression/'`: If the [custom variable](../variables/README.md#custom-environment-variables)
  `CUSTOM_VARIABLE` does **not** match a regular expression.
- `if: '$CUSTOM_VARIABLE == "value1"'`: If the custom variable `CUSTOM_VARIABLE` is
  exactly `value1`.
1328

1329 1330 1331 1332 1333 1334 1335 1336
##### `rules:changes`

To determine if jobs should be added to a pipeline, `rules: changes` clauses check
the files changed by Git push events.

`rules: changes` works exactly the same way as [`only: changes` and `except: changes`](#onlychangesexceptchanges),
accepting an array of paths. Similarly, it always returns true if there is no
Git push event. It should only be used for branch pipelines or merge request pipelines.
1337 1338

For example:
1339 1340

```yaml
1341 1342 1343 1344
workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

1345 1346 1347
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
1348
    - changes:
1349
        - Dockerfile
1350
      when: manual
1351
      allow_failure: true
1352 1353
```

1354
In this example:
E
Evan Read 已提交
1355

1356 1357 1358 1359
- [`workflow: rules`](#workflowrules) allows only pipelines for merge requests for all jobs.
- If `Dockerfile` has changed, add the job to the pipeline as a manual job, and allow the pipeline
  to continue running even if the job is not triggered (`allow_failure: true`).
- If `Dockerfile` has not changed, do not add job to any pipeline (same as `when: never`).
E
Evan Read 已提交
1360

1361
##### `rules:exists`
1362

1363
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4.
1364

1365 1366 1367 1368 1369 1370 1371 1372 1373 1374
`exists` accepts an array of paths and will match if any of these paths exist
as files in the repository.

For example:

```yaml
job:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - exists:
1375
        - Dockerfile
1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387
```

You can also use glob patterns to match multiple files in any directory within
the repository.

For example:

```yaml
job:
  script: bundle exec rspec
  rules:
    - exists:
1388
        - spec/**.rb
1389 1390 1391 1392 1393 1394
```

NOTE: **Note:**
For performance reasons, using `exists` with patterns is limited to 10000
checks. After the 10000th check, rules with patterned globs will always match.

1395
##### `rules:allow_failure`
1396

1397
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8.
1398 1399 1400 1401 1402

You can use [`allow_failure: true`](#allow_failure) within `rules:` to allow a job to fail, or a manual job to
wait for action, without stopping the pipeline itself. All jobs using `rules:` default to `allow_failure: false`
if `allow_failure:` is not defined.

1403 1404 1405 1406
The rule-level `rules:allow_failure` option overrides the job-level
[`allow_failure`](#allow_failure) option, and is only applied when the job is
triggered by the particular rule.

1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417
```yaml
job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'
      when: manual
      allow_failure: true
```

In this example, if the first rule matches, then the job will have `when: manual` and `allow_failure: true`.

E
Evan Read 已提交
1418
#### Complex rule clauses
1419

1420 1421
To conjoin `if`, `changes`, and `exists` clauses with an AND, use them in the
same rule.
E
Evan Read 已提交
1422 1423 1424 1425 1426

In the following example:

- We run the job manually if `Dockerfile` or any file in `docker/scripts/`
  has changed AND `$VAR == "string value"`.
1427
- Otherwise, the job won't be included in the pipeline.
1428 1429 1430 1431 1432 1433 1434

```yaml
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: '$VAR == "string value"'
      changes: # Will include the job and set to when:manual if any of the follow paths match a modified file.
1435 1436
        - Dockerfile
        - docker/scripts/*
1437 1438 1439 1440
      when: manual
  # - when: never would be redundant here, this is implied any time rules are listed.
```

E
Evan Read 已提交
1441 1442
Keywords such as `branches` or `refs` that are currently available for
`only`/`except` are not yet available in `rules` as they are being individually
1443 1444 1445
considered for their usage and behavior in this context. Future keyword improvements
are being discussed in our [epic for improving `rules`](https://gitlab.com/groups/gitlab-org/-/epics/2783),
where anyone can add suggestions or requests.
1446

1447
### `only`/`except` (basic)
1448

1449
NOTE: **Note:**
1450 1451 1452
The [`rules`](#rules) syntax is an improved, more powerful solution for defining
when jobs should run or not. Consider using `rules` instead of `only/except` to get
the most out of your pipelines.
1453

1454 1455
`only` and `except` are two parameters that set a job policy to limit when
jobs are created:
1456

1457 1458 1459
1. `only` defines the names of branches and tags for which the job will run.
1. `except` defines the names of branches and tags for which the job will
    **not** run.
1460

1461
There are a few rules that apply to the usage of job policy:
1462

1463 1464 1465 1466 1467
- `only` and `except` are inclusive. If both `only` and `except` are defined
   in a job specification, the ref is filtered by `only` and `except`.
- `only` and `except` allow the use of regular expressions ([supported regexp syntax](#supported-onlyexcept-regexp-syntax)).
- `only` and `except` allow to specify a repository path to filter jobs for
   forks.
D
Douwe Maan 已提交
1468

1469
In addition, `only` and `except` allow the use of special keywords:
D
Douwe Maan 已提交
1470

1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484
| **Value**                | **Description**                                                                                                                                                                        |
|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `branches`               | When the Git reference for a pipeline is a branch.                                                                                                                                        |
| `tags`                   | When the Git reference for a pipeline is a tag.                                                                                                                                           |
| `api`                    | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline).                                                                                                         |
| `external`               | When using CI services other than GitLab.                                                                                                                                              |
| `pipelines`              | For multi-project pipelines created by using the API with `CI_JOB_TOKEN`.                                                                                                              |
| `pushes`                 | For pipelines triggered by a `git push` event, including for branches and tags.                                                                                                        |
| `schedules`              | For [scheduled pipelines](../pipelines/schedules.md).                                                                                                                                  |
| `triggers`               | For pipelines created by using a trigger token.                                                                                                                                        |
| `web`                    | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section.                                                             |
| `merge_requests`         | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md).                                                                  |
| `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). |
| `chat`                   | For pipelines created by using a [GitLab ChatOps](../chatops/README.md) command.                                                                                                       |
1485

1486 1487
In the example below, `job` will run only for refs that start with `issue-`,
whereas all branches will be skipped:
1488 1489

```yaml
D
Douwe Maan 已提交
1490
job:
1491 1492 1493 1494 1495 1496 1497
  # use regexp
  only:
    - /^issue-.*$/
  # use special keyword
  except:
    - branches
```
D
Douwe Maan 已提交
1498

1499 1500
Pattern matching is case-sensitive by default. Use `i` flag modifier, like
`/pattern/i` to make a pattern case-insensitive:
1501 1502

```yaml
1503 1504 1505 1506 1507 1508 1509
job:
  # use regexp
  only:
    - /^issue-.*$/i
  # use special keyword
  except:
    - branches
1510 1511
```

1512 1513
In this example, `job` will run only for refs that are tagged, or if a build is
explicitly requested via an API trigger or a [Pipeline Schedule](../pipelines/schedules.md):
1514 1515

```yaml
1516 1517 1518 1519 1520 1521
job:
  # use special keywords
  only:
    - tags
    - triggers
    - schedules
1522 1523
```

1524 1525
The repository path can be used to have jobs executed only for the parent
repository and not forks:
1526 1527

```yaml
1528 1529 1530 1531 1532 1533
job:
  only:
    - branches@gitlab-org/gitlab
  except:
    - master@gitlab-org/gitlab
    - /^release/.*$/@gitlab-org/gitlab
1534 1535
```

1536 1537
The above example will run `job` for all branches on `gitlab-org/gitlab`,
except `master` and those with names prefixed with `release/`.
W
Winnie Hellmann 已提交
1538

1539
If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by
1540
default. If it does not have an `except` rule, it's empty.
W
Winnie Hellmann 已提交
1541

1542
For example,
W
Winnie Hellmann 已提交
1543

1544 1545 1546 1547
```yaml
job:
  script: echo 'test'
```
W
Winnie Hellmann 已提交
1548

1549
is translated to:
W
Winnie Hellmann 已提交
1550 1551

```yaml
1552 1553 1554
job:
  script: echo 'test'
  only: ['branches', 'tags']
W
Winnie Hellmann 已提交
1555 1556
```

1557
#### Regular expressions
W
Winnie Hellmann 已提交
1558

1559 1560 1561
Because `@` is used to denote the beginning of a ref's repository path,
matching a ref name containing the `@` character in a regular expression
requires the use of the hex character code match `\x40`.
W
Winnie Hellmann 已提交
1562

1563 1564
Only the tag or branch name can be matched by a regular expression.
The repository path, if given, is always matched literally.
1565

1566 1567 1568 1569 1570 1571
If a regular expression shall be used to match the tag or branch name,
the entire ref name part of the pattern has to be a regular expression,
and must be surrounded by `/`.
(With regular expression flags appended after the closing `/`.)
So `issue-/.*/` won't work to match all tag names or branch names
that begin with `issue-`.
1572

1573 1574 1575 1576 1577
TIP: **Tip**
Use anchors `^` and `$` to avoid the regular expression
matching only a substring of the tag name or branch name.
For example, `/^issue-.*$/` is equivalent to `/^issue-/`,
while just `/issue/` would also match a branch called `severe-issues`.
1578

1579
#### Supported `only`/`except` regexp syntax
1580

1581 1582
CAUTION: **Warning:**
This is a breaking change that was introduced with GitLab 11.9.4.
1583

1584 1585
In GitLab 11.9.4, GitLab begun internally converting regexp used
in `only` and `except` parameters to [RE2](https://github.com/google/re2/wiki/Syntax).
1586

1587 1588 1589 1590
This means that only subset of features provided by [Ruby Regexp](https://ruby-doc.org/core/Regexp.html)
is supported. [RE2](https://github.com/google/re2/wiki/Syntax) limits the set of features
provided due to computational complexity, which means some features became unavailable in GitLab 11.9.4.
For example, negative lookaheads.
1591

1592 1593 1594
For GitLab versions from 11.9.7 and up to GitLab 12.0, GitLab provides a feature flag that can be
enabled by administrators that allows users to use unsafe regexp syntax. This brings compatibility
with previously allowed syntax version and allows users to gracefully migrate to the new syntax.
1595

1596 1597 1598
```ruby
Feature.enable(:allow_unsafe_ruby_regexp)
```
1599

1600
### `only`/`except` (advanced)
1601

1602
CAUTION: **Warning:**
1603
This is an _alpha_ feature, and is subject to change at any time without
1604
prior notice!
1605

1606 1607
GitLab supports both simple and complex strategies, so it's possible to use an
array and a hash configuration scheme.
1608

1609
Four keys are available:
1610

1611 1612 1613 1614
- `refs`
- `variables`
- `changes`
- `kubernetes`
1615

1616 1617
If you use multiple keys under `only` or `except`, the keys will be evaluated as a
single conjoined expression. That is:
1618

1619 1620
- `only:` means "include this job if all of the conditions match".
- `except:` means "exclude this job if any of the conditions match".
1621

1622
With `only`, individual keys are logically joined by an AND:
1623

1624 1625 1626
> (any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active)

In the example below, the `test` job will `only` be created when **all** of the following are true:
1627

1628 1629 1630
- The pipeline has been [scheduled](../../user/project/pipelines/schedules.md) **or** runs for `master`.
- The `variables` keyword matches.
- The `kubernetes` service is active on the project.
1631

1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642
```yaml
test:
  script: npm run test
  only:
    refs:
      - master
      - schedules
    variables:
      - $CI_COMMIT_MESSAGE =~ /run-end-to-end-tests/
    kubernetes: active
```
1643

1644
`except` is implemented as a negation of this complete expression:
1645

1646
> NOT((any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active))
1647

1648
This means the keys are treated as if joined by an OR. This relationship could be described as:
1649

1650
> (any of refs) OR (any of variables) OR (any of changes) OR (if Kubernetes is active)
1651

1652
In the example below, the `test` job will **not** be created when **any** of the following are true:
1653

1654
- The pipeline runs for the `master`.
1655
- There are changes to the `README.md` file in the root directory of the repository.
1656 1657

```yaml
1658 1659 1660 1661 1662 1663 1664
test:
  script: npm run test
  except:
    refs:
      - master
    changes:
      - "README.md"
1665 1666
```

1667
#### `only:refs`/`except:refs`
1668

1669
> `refs` policy introduced in GitLab 10.0.
1670

1671 1672
The `refs` strategy can take the same values as the
[simplified only/except configuration](#onlyexcept-basic).
1673

1674 1675
In the example below, the `deploy` job is going to be created only when the
pipeline has been [scheduled](../pipelines/schedules.md) or runs for the `master` branch:
1676

1677 1678 1679 1680 1681 1682 1683
```yaml
deploy:
  only:
    refs:
      - master
      - schedules
```
1684

1685
#### `only:kubernetes`/`except:kubernetes`
1686

1687
> `kubernetes` policy introduced in GitLab 10.0.
1688

1689
The `kubernetes` strategy accepts only the `active` keyword.
1690

1691 1692
In the example below, the `deploy` job is going to be created only when the
Kubernetes service is active in the project:
1693 1694

```yaml
1695 1696 1697
deploy:
  only:
    kubernetes: active
1698 1699
```

1700
#### `only:variables`/`except:variables`
1701

1702
> `variables` policy introduced in GitLab 10.7.
1703

1704 1705 1706 1707
The `variables` keyword is used to define variables expressions. In other words,
you can use predefined variables / project / group or
environment-scoped variables to define an expression GitLab is going to
evaluate in order to decide whether a job should be created or not.
1708

1709
Examples of using variables expressions:
1710

1711 1712 1713 1714 1715 1716 1717 1718 1719 1720
```yaml
deploy:
  script: cap staging deploy
  only:
    refs:
      - branches
    variables:
      - $RELEASE == "staging"
      - $STAGING
```
1721

1722
Another use case is excluding jobs depending on a commit message:
1723 1724

```yaml
1725 1726 1727 1728 1729
end-to-end:
  script: rake test:end-to-end
  except:
    variables:
      - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/
1730 1731
```

1732
Learn more about [variables expressions](../variables/README.md#environment-variables-expressions).
1733

1734
#### `only:changes`/`except:changes`
1735

1736
> `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19232) in GitLab 11.4.
1737

1738 1739
Using the `changes` keyword with `only` or `except` makes it possible to define if
a job should be created based on files modified by a Git push event.
1740

1741
This means the `only:changes` policy is useful for pipelines where:
1742

1743 1744 1745 1746 1747
- `$CI_PIPELINE_SOURCE == 'push'`
- `$CI_PIPELINE_SOURCE == 'merge_request_event'`
- `$CI_PIPELINE_SOURCE == 'external_pull_request_event'`

If there is no Git push event, such as for pipelines with
1748
[sources other than the three above](../variables/predefined_variables.md),
1749
`changes` can't determine if a given file is new or old, and will always
1750 1751 1752
return true.

A basic example of using `only: changes`:
1753 1754

```yaml
1755 1756 1757 1758 1759 1760 1761 1762
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  only:
    changes:
      - Dockerfile
      - docker/scripts/*
      - dockerfiles/**/*
      - more_scripts/*.{rb,py,sh}
1763 1764
```

1765 1766 1767
In the scenario above, when pushing commits to an existing branch in GitLab,
it creates and triggers the `docker build` job, provided that one of the
commits contains changes to any of the following:
1768

1769 1770 1771 1772
- The `Dockerfile` file.
- Any of the files inside `docker/scripts/` directory.
- Any of the files and subdirectories inside the `dockerfiles` directory.
- Any of the files with `rb`, `py`, `sh` extensions inside the `more_scripts` directory.
1773

1774 1775
CAUTION: **Warning:**
If using `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),
1776
undesired behavior could result if you don't [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests).
1777

1778
You can also use glob patterns to match multiple files in either the root directory
1779
of the repository, or in _any_ directory within the repository, but they must be wrapped
1780
in double quotes or GitLab will fail to parse the `.gitlab-ci.yml`. For example:
1781

1782 1783 1784 1785 1786 1787 1788 1789
```yaml
test:
  script: npm run test
  only:
    changes:
      - "*.json"
      - "**/*.sql"
```
1790

1791
The following example will skip the `build` job if a change is detected in any file
1792
in the root directory of the repository with a `.md` extension:
1793

1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808
```yaml
build:
  script: npm run build
  except:
    changes:
      - "*.md"
```

CAUTION: **Warning:**
There are some points to be aware of when
[using this feature with new branches or tags *without* pipelines for merge requests](#using-onlychanges-without-pipelines-for-merge-requests).

CAUTION: **Warning:**
There are some points to be aware of when
[using this feature with scheduled pipelines](#using-onlychanges-with-scheduled-pipelines).
1809

1810
##### Using `only:changes` with pipelines for merge requests
1811

1812
With [pipelines for merge requests](../merge_request_pipelines/index.md),
1813
it's possible to define a job to be created based on files modified
1814
in a merge request.
1815

1816 1817 1818 1819
In order to deduce the correct base SHA of the source branch, we recommend combining
this keyword with `only: [merge_requests]`. This way, file differences are correctly
calculated from any further commits, thus all changes in the merge requests are properly
tested in pipelines.
1820

1821
For example:
1822 1823

```yaml
1824 1825 1826 1827 1828 1829 1830 1831
docker build service one:
  script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG .
  only:
    refs:
      - merge_requests
    changes:
      - Dockerfile
      - service-one/**/*
1832 1833
```

1834 1835 1836
In the scenario above, if a merge request is created or updated that changes
either files in `service-one` directory or the `Dockerfile`, GitLab creates
and triggers the `docker build service one` job.
1837

1838 1839 1840
Note that if [pipelines for merge requests](../merge_request_pipelines/index.md) is
combined with `only: [change]`, but `only: [merge_requests]` is omitted, there could be
unwanted behavior.
1841

1842 1843 1844 1845 1846 1847 1848 1849 1850
For example:

```yaml
docker build service one:
  script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG .
  only:
    changes:
      - Dockerfile
      - service-one/**/*
1851 1852
```

1853 1854
In the example above, a pipeline could fail due to changes to a file in `service-one/**/*`.
A later commit could then be pushed that does not include any changes to this file,
1855
but includes changes to the `Dockerfile`, and this pipeline could pass because it's only
1856 1857 1858
testing the changes to the `Dockerfile`. GitLab checks the **most recent pipeline**,
that **passed**, and will show the merge request as mergeable, despite the earlier
failed pipeline caused by a change that was not yet corrected.
1859

1860 1861
With this configuration, care must be taken to check that the most recent pipeline
properly corrected any failures from previous pipelines.
1862

1863
##### Using `only:changes` without pipelines for merge requests
1864

1865 1866 1867 1868
Without [pipelines for merge requests](../merge_request_pipelines/index.md), pipelines
run on branches or tags that don't have an explicit association with a merge request.
In this case, a previous SHA is used to calculate the diff, which equivalent to `git diff HEAD~`.
This could result in some unexpected behavior, including:
1869

1870 1871 1872
- When pushing a new branch or a new tag to GitLab, the policy always evaluates to true.
- When pushing a new commit, the changed files are calculated using the previous commit
  as the base SHA.
1873

1874
##### Using `only:changes` with scheduled pipelines
1875

1876 1877 1878
`only:changes` always evaluates as "true" in [Scheduled pipelines](../pipelines/schedules.md).
All files are considered to have "changed" when a scheduled pipeline
runs.
1879

1880
### `needs`
1881

1882
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47063) in GitLab 12.2.
1883
> - In GitLab 12.3, maximum number of jobs in `needs` array raised from five to 50.
1884
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30631) in GitLab 12.8, `needs: []` lets jobs start immediately.
1885

1886 1887 1888 1889 1890 1891 1892
The `needs:` keyword enables executing jobs out-of-order, allowing you to implement
a [directed acyclic graph](../directed_acyclic_graph/index.md) in your `.gitlab-ci.yml`.

This lets you run some jobs without waiting for other ones, disregarding stage ordering
so you can have multiple stages running concurrently.

Let's consider the following example:
1893 1894

```yaml
1895 1896
linux:build:
  stage: build
1897

1898 1899
mac:build:
  stage: build
1900

1901 1902 1903
lint:
  stage: test
  needs: []
1904

1905 1906 1907
linux:rspec:
  stage: test
  needs: ["linux:build"]
1908

1909 1910 1911
linux:rubocop:
  stage: test
  needs: ["linux:build"]
1912

1913 1914 1915
mac:rspec:
  stage: test
  needs: ["mac:build"]
1916

1917 1918 1919
mac:rubocop:
  stage: test
  needs: ["mac:build"]
1920

1921 1922 1923
production:
  stage: deploy
```
1924

1925
This example creates four paths of execution:
1926

1927
- Linter: the `lint` job will run immediately without waiting for the `build` stage to complete because it has no needs (`needs: []`).
1928

1929 1930
- Linux path: the `linux:rspec` and `linux:rubocop` jobs will be run as soon
  as the `linux:build` job finishes without waiting for `mac:build` to finish.
1931

1932 1933
- macOS path: the `mac:rspec` and `mac:rubocop` jobs will be run as soon
  as the `mac:build` job finishes, without waiting for `linux:build` to finish.
1934

1935 1936 1937
- The `production` job will be executed as soon as all previous jobs
  finish; in this case: `linux:build`, `linux:rspec`, `linux:rubocop`,
  `mac:build`, `mac:rspec`, `mac:rubocop`.
1938

1939
#### Requirements and limitations
1940

1941 1942 1943
- If `needs:` is set to point to a job that is not instantiated
  because of `only/except` rules or otherwise does not exist, the
  pipeline will be created with YAML error.
1944
- The maximum number of jobs that a single job can need in the `needs:` array is limited:
1945
  - For GitLab.com, the limit is ten. For more information, see our
1946
    [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541).
1947 1948 1949 1950 1951 1952
  - For self-managed instances, the limit is:
    - 10, if the `ci_dag_limit_needs` feature flag is enabled (default).
    - 50, if the `ci_dag_limit_needs` feature flag is disabled.
- If `needs:` refers to a job that is marked as `parallel:`.
  the current job will depend on all parallel jobs created.
- `needs:` is similar to `dependencies:` in that it needs to use jobs from prior stages,
1953
  meaning it's impossible to create circular dependencies. Depending on jobs in the
1954
  current stage is not possible either, but support [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/30632).
1955 1956
- Related to the above, stages must be explicitly defined for all jobs
  that have the keyword `needs:` or are referred to by one.
1957

1958
##### Changing the `needs:` job limit
1959

1960 1961 1962 1963
The maximum number of jobs that can be defined within `needs:` defaults to 10, but
can be changed to 50 via a feature flag. To change the limit to 50,
[start a Rails console session](../../administration/troubleshooting/debug.md#starting-a-rails-console-session)
and run:
1964

1965 1966
```ruby
Feature::disable(:ci_dag_limit_needs)
1967 1968
```

1969
To set it back to 10, run the opposite command:
1970

1971 1972
```ruby
Feature::enable(:ci_dag_limit_needs)
1973 1974
```

1975
#### Artifact downloads with `needs`
1976

1977
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.6.
1978

1979
When using `needs`, artifact downloads are controlled with `artifacts: true` (default) or `artifacts: false`.
1980 1981 1982 1983

Since GitLab 12.6, you can't combine the [`dependencies`](#dependencies) keyword
with `needs` to control artifact downloads in jobs. `dependencies` is still valid
in jobs that do not use `needs`.
1984

1985
In the example below, the `rspec` job will download the `build_job` artifacts, while the
1986
`rubocop` job won't:
1987

1988
```yaml
1989 1990 1991
build_job:
  stage: build
  artifacts:
1992
    paths:
1993
      - binaries/
1994

1995 1996
rspec:
  stage: test
1997 1998 1999
  needs:
    - job: build_job
      artifacts: true
2000

2001 2002 2003 2004 2005 2006
rubocop:
  stage: test
  needs:
    - job: build_job
      artifacts: false
```
2007

2008 2009 2010
Additionally, in the three syntax examples below, the `rspec` job will download the artifacts
from all three `build_jobs`, as `artifacts` is true for `build_job_1`, and will
**default** to true for both `build_job_2` and `build_job_3`.
K
Kamil Trzcinski 已提交
2011

2012 2013 2014 2015 2016 2017 2018 2019
```yaml
rspec:
  needs:
    - job: build_job_1
      artifacts: true
    - job: build_job_2
    - build_job_3
```
2020

2021
#### Cross project artifact downloads with `needs` **(PREMIUM)**
2022

2023
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.7.
2024

2025 2026 2027
`needs` can be used to download artifacts from up to five jobs in pipelines on
[other refs in the same project](#artifact-downloads-between-pipelines-in-the-same-project),
or pipelines in different projects:
2028

2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039
```yaml
build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: group/project-name
      job: build-1
      ref: master
      artifacts: true
```
2040

2041 2042
`build_job` will download the artifacts from the latest successful `build-1` job
on the `master` branch in the `group/project-name` project.
2043

2044
##### Artifact downloads between pipelines in the same project
2045

2046 2047 2048 2049
`needs` can be used to download artifacts from different pipelines in the current project
by setting the `project` keyword as the current project's name, and specifying a ref.
In the example below, `build_job` will download the artifacts for the latest successful
`build-1` job with the `other-ref` ref:
K
Kamil Trzcinski 已提交
2050

2051
```yaml
2052 2053 2054 2055 2056 2057 2058 2059 2060
build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: group/same-project-name
      job: build-1
      ref: other-ref
      artifacts: true
2061
```
K
Kamil Trzcinski 已提交
2062

2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075
NOTE: **Note:**
Downloading artifacts from jobs that are run in [`parallel:`](#parallel) is not supported.

### `tags`

`tags` is used to select specific Runners from the list of all Runners that are
allowed to run this project.

During the registration of a Runner, you can specify the Runner's tags, for
example `ruby`, `postgres`, `development`.

`tags` allow you to run jobs with Runners that have the specified tags
assigned to them:
2076 2077 2078

```yaml
job:
2079 2080 2081
  tags:
    - ruby
    - postgres
2082 2083
```

2084 2085
The specification above, will make sure that `job` is built by a Runner that
has both `ruby` AND `postgres` tags defined.
2086

2087 2088 2089
Tags are also a great way to run different jobs on different platforms, for
example, given an OS X Runner with tag `osx` and Windows Runner with tag
`windows`, the following jobs run on respective platforms:
2090 2091

```yaml
2092 2093 2094 2095 2096
windows job:
  stage:
    - build
  tags:
    - windows
2097
  script:
2098
    - echo Hello, %USERNAME%!
2099

2100 2101 2102 2103 2104
osx job:
  stage:
    - build
  tags:
    - osx
2105
  script:
2106
    - echo "Hello, $USER!"
2107 2108
```

2109
### `allow_failure`
2110

2111 2112 2113 2114 2115
`allow_failure` allows a job to fail without impacting the rest of the CI
suite.
The default value is `false`, except for [manual](#whenmanual) jobs using the
`when: manual` syntax, unless using [`rules:`](#rules) syntax, where all jobs
default to false, *including* `when: manual` jobs.
2116

2117 2118 2119
When enabled and the job fails, the job will show an orange warning in the UI.
However, the logical flow of the pipeline will consider the job a
success/passed, and is not blocked.
2120

2121 2122 2123
Assuming all other jobs are successful, the job's stage and its pipeline will
show the same orange warning. However, the associated commit will be marked
"passed", without warnings.
2124

2125
In the example below, `job1` and `job2` will run in parallel, but if `job1`
2126
fails, it won't stop the next stage from running, since it's marked with
2127
`allow_failure: true`:
2128

2129 2130 2131 2132 2133 2134
```yaml
job1:
  stage: test
  script:
    - execute_script_that_will_fail
  allow_failure: true
2135

2136 2137 2138 2139 2140 2141 2142 2143 2144
job2:
  stage: test
  script:
    - execute_script_that_will_succeed

job3:
  stage: deploy
  script:
    - deploy_to_staging
2145 2146
```

2147
### `when`
2148

2149 2150
`when` is used to implement jobs that are run in case of failure or despite the
failure.
2151

2152
`when` can be set to one of the following values:
2153

2154 2155 2156 2157 2158 2159 2160 2161 2162 2163
1. `on_success` - execute job only when all jobs from prior stages
    succeed (or are considered succeeding because they are marked
    `allow_failure`). This is the default.
1. `on_failure` - execute job only when at least one job from prior stages
    fails.
1. `always` - execute job regardless of the status of jobs from prior stages.
1. `manual` - execute job manually (added in GitLab 8.10). Read about
    [manual actions](#whenmanual) below.
1. `delayed` - execute job after a certain period (added in GitLab 11.14).
    Read about [delayed actions](#whendelayed) below.
2164

2165
For example:
2166

2167 2168 2169 2170 2171 2172 2173
```yaml
stages:
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup
2174

2175 2176 2177 2178
build_job:
  stage: build
  script:
    - make build
2179

2180 2181 2182 2183 2184
cleanup_build_job:
  stage: cleanup_build
  script:
    - cleanup build when failed
  when: on_failure
2185

2186 2187 2188 2189
test_job:
  stage: test
  script:
    - make test
2190

2191 2192 2193 2194 2195
deploy_job:
  stage: deploy
  script:
    - make deploy
  when: manual
2196

2197 2198 2199 2200 2201
cleanup_job:
  stage: cleanup
  script:
    - cleanup after jobs
  when: always
2202 2203
```

2204
The above script will:
2205

2206 2207 2208 2209
1. Execute `cleanup_build_job` only when `build_job` fails.
1. Always execute `cleanup_job` as the last step in pipeline regardless of
   success or failure.
1. Allow you to manually execute `deploy_job` from GitLab's UI.
2210

2211
#### `when:manual`
2212

2213 2214 2215
> - Introduced in GitLab 8.10.
> - Blocking manual actions were introduced in GitLab 9.0.
> - Protected actions were introduced in GitLab 9.2.
2216

2217 2218 2219 2220
Manual actions are a special type of job that are not executed automatically,
they need to be explicitly started by a user. An example usage of manual actions
would be a deployment to a production environment. Manual actions can be started
from the pipeline, job, environment, and deployment views. Read more at the
2221
[environments documentation](../environments/index.md#configuring-manual-deployments).
2222

2223 2224 2225 2226
Manual actions can be either optional or blocking. Blocking manual actions will
block the execution of the pipeline at the stage this action is defined in. It's
possible to resume execution of the pipeline when someone executes a blocking
manual action by clicking a _play_ button.
2227

2228
When a pipeline is blocked, it won't be merged if Merge When Pipeline Succeeds
2229 2230
is set. Blocked pipelines also do have a special status, called _manual_.
When the `when:manual` syntax is used, manual actions are non-blocking by
2231
default. If you want to make manual action blocking, it's necessary to add
2232
`allow_failure: false` to the job's definition in `.gitlab-ci.yml`.
A
Achilleas Pipinellis 已提交
2233

2234
Optional manual actions have `allow_failure: true` set by default and their
2235
Statuses don't contribute to the overall pipeline status. So, if a manual
2236
action fails, the pipeline will eventually succeed.
2237

2238 2239
NOTE: **Note:**
When using [`rules:`](#rules), `allow_failure` defaults to `false`, including for manual jobs.
2240

2241 2242 2243 2244
Manual actions are considered to be write actions, so permissions for
[protected branches](../../user/project/protected_branches.md) are used when
a user wants to trigger an action. In other words, in order to trigger a manual
action assigned to a branch that the pipeline is running for, the user needs to
2245
have the ability to merge to this branch. It's possible to use protected environments
2246 2247
to more strictly [protect manual deployments](#protecting-manual-jobs-premium) from being
run by unauthorized users.
2248

2249 2250 2251 2252
NOTE: **Note:**
Using `when:manual` and `trigger` together results in the error `jobs:#{job-name} when
should be on_success, on_failure or always`, because `when:manual` prevents triggers
being used.
2253

2254
##### Protecting manual jobs **(PREMIUM)**
2255

2256 2257
It's possible to use [protected environments](../environments/protected_environments.md)
to define a precise list of users authorized to run a manual job. By allowing only
2258
users associated with a protected environment to trigger manual jobs, it's possible
2259
to implement some special use cases, such as:
2260

2261 2262
- More precisely limiting who can deploy to an environment.
- Enabling a pipeline to be blocked until an approved user "approves" it.
2263

2264
To do this, you must:
2265

2266
1. Add an `environment` to the job. For example:
2267

2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279
   ```yaml
   deploy_prod:
     stage: deploy
     script:
       - echo "Deploy to production server"
     environment:
       name: production
       url: https://example.com
     when: manual
     only:
       - master
   ```
2280

2281 2282 2283 2284 2285
1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments),
   select the environment (`production` in the example above) and add the users, roles or groups
   that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in
   this list will be able to trigger this manual job, as well as GitLab administrators
   who are always able to use protected environments.
2286

2287
Additionally, if a manual job is defined as blocking by adding `allow_failure: false`,
2288
the next stages of the pipeline won't run until the manual job is triggered. This
2289 2290
can be used as a way to have a defined list of users allowed to "approve" later pipeline
stages by triggering the blocking manual job.
2291

2292
#### `when:delayed`
2293

2294
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51352) in GitLab 11.4.
2295

2296 2297
Delayed job are for executing scripts after a certain period.
This is useful if you want to avoid jobs entering `pending` state immediately.
2298

2299 2300
You can set the period with `start_in` key. The value of `start_in` key is an elapsed time in seconds, unless a unit is
provided. `start_in` key must be less than or equal to one week. Examples of valid values include:
2301

2302 2303 2304 2305 2306
- `'5'`
- `10 seconds`
- `30 minutes`
- `1 day`
- `1 week`
2307

2308
When there is a delayed job in a stage, the pipeline won't progress until the delayed job has finished.
2309
This means this keyword can also be used for inserting delays between different stages.
2310

2311
The timer of a delayed job starts immediately after the previous stage has completed.
2312
Similar to other types of jobs, a delayed job's timer won't start unless the previous stage passed.
2313

2314
The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage has completed:
2315

2316 2317 2318 2319 2320 2321 2322
```yaml
timed rollout 10%:
  stage: deploy
  script: echo 'Rolling out 10% ...'
  when: delayed
  start_in: 30 minutes
```
2323

2324
You can stop the active timer of a delayed job by clicking the **{time-out}** (**Unschedule**) button.
2325
This job will never be executed in the future unless you execute the job manually.
2326

2327 2328
You can start a delayed job immediately by clicking the **Play** button.
GitLab Runner will pick your job soon and start the job.
2329

2330
### `environment`
2331

2332 2333
> - Introduced in GitLab 8.9.
> - You can read more about environments and find more examples in the
2334
>   [documentation about environments](../environments/index.md).
2335

2336 2337 2338 2339 2340
`environment` is used to define that a job deploys to a specific environment.
If `environment` is specified and no environment under that name exists, a new
one will be created automatically.

In its simplest form, the `environment` keyword can be defined like:
2341 2342

```yaml
2343 2344 2345 2346
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment: production
2347 2348
```

2349 2350
In the above example, the `deploy to production` job will be marked as doing a
deployment to the `production` environment.
2351

2352
#### `environment:name`
2353

2354 2355 2356 2357 2358 2359
> - Introduced in GitLab 8.11.
> - Before GitLab 8.11, the name of an environment could be defined as a string like
>   `environment: production`. The recommended way now is to define it under the
>   `name` keyword.
> - The `name` parameter can use any of the defined CI variables,
>   including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
2360
>   You however can't use variables defined under `script`.
B
Ben Bodenmiller 已提交
2361

2362
The `environment` name can contain:
2363

2364 2365 2366 2367 2368 2369 2370 2371 2372
- letters
- digits
- spaces
- `-`
- `_`
- `/`
- `$`
- `{`
- `}`
2373

2374 2375
Common names are `qa`, `staging`, and `production`, but you can use whatever
name works with your workflow.
2376

2377
Instead of defining the name of the environment right after the `environment`
2378
keyword, it's also possible to define it as a separate value. For that, use
2379
the `name` keyword under `environment`:
2380 2381

```yaml
2382 2383 2384 2385 2386
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
2387 2388
```

2389
#### `environment:url`
2390

2391 2392 2393 2394 2395
> - Introduced in GitLab 8.11.
> - Before GitLab 8.11, the URL could be added only in GitLab's UI. The
>   recommended way now is to define it in `.gitlab-ci.yml`.
> - The `url` parameter can use any of the defined CI variables,
>   including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
2396
>   You however can't use variables defined under `script`.
2397

2398 2399
This is an optional value that when set, it exposes buttons in various places
in GitLab which when clicked take you to the defined URL.
2400

2401 2402 2403
In the example below, if the job finishes successfully, it will create buttons
in the merge requests and in the environments/deployments pages which will point
to `https://prod.example.com`.
2404

2405 2406 2407 2408 2409 2410 2411 2412
```yaml
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
    url: https://prod.example.com
```
2413

2414
#### `environment:on_stop`
2415

2416
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22191) in GitLab 8.13.
2417 2418 2419
> - Starting with GitLab 8.14, when you have an environment that has a stop action
>   defined, GitLab will automatically trigger a stop action when the associated
>   branch is deleted.
2420

2421 2422 2423
Closing (stopping) environments can be achieved with the `on_stop` keyword defined under
`environment`. It declares a different job that runs in order to close
the environment.
2424

2425
Read the `environment:action` section for an example.
2426

2427
#### `environment:action`
O
Olivier Gonzalez 已提交
2428

2429
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22191) in GitLab 8.13.
O
Olivier Gonzalez 已提交
2430

2431 2432
The `action` keyword is to be used in conjunction with `on_stop` and is defined
in the job that is called to close the environment.
O
Olivier Gonzalez 已提交
2433

2434
Take for instance:
O
Olivier Gonzalez 已提交
2435

2436 2437 2438 2439 2440
```yaml
review_app:
  stage: deploy
  script: make deploy-app
  environment:
2441 2442
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com
2443
    on_stop: stop_review_app
O
Olivier Gonzalez 已提交
2444

2445 2446 2447 2448 2449 2450 2451
stop_review_app:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script: make delete-app
  when: manual
  environment:
2452
    name: review/$CI_COMMIT_REF_NAME
2453 2454
    action: stop
```
O
Olivier Gonzalez 已提交
2455

2456 2457 2458 2459 2460 2461
In the above example we set up the `review_app` job to deploy to the `review`
environment, and we also defined a new `stop_review_app` job under `on_stop`.
Once the `review_app` job is successfully finished, it will trigger the
`stop_review_app` job based on what is defined under `when`. In this case we
set it up to `manual` so it will need a [manual action](#whenmanual) via
GitLab's web interface in order to run.
O
Olivier Gonzalez 已提交
2462

2463 2464
Also in the example, `GIT_STRATEGY` is set to `none` so that GitLab Runner won’t
try to check out the code after the branch is deleted when the `stop_review_app`
2465
job is [automatically triggered](../environments/index.md#automatically-stopping-an-environment).
O
Olivier Gonzalez 已提交
2466

2467 2468 2469 2470
NOTE: **Note:**
The above example overwrites global variables. If your stop environment job depends
on global variables, you can use [anchor variables](#yaml-anchors-for-variables) when setting the `GIT_STRATEGY`
to change it without overriding the global variables.
O
Olivier Gonzalez 已提交
2471

2472
The `stop_review_app` job is **required** to have the following keywords defined:
O
Olivier Gonzalez 已提交
2473

2474 2475 2476
- `when` - [reference](#when)
- `environment:name`
- `environment:action`
O
Olivier Gonzalez 已提交
2477

2478 2479 2480 2481 2482 2483
Additionally, both jobs should have matching [`rules`](../yaml/README.md#onlyexcept-basic)
or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. In the example
above, if the configuration is not identical, the `stop_review_app` job might not be
included in all pipelines that include the `review_app` job, and it will not be
possible to trigger the `action: stop` to stop the environment automatically.

2484
#### `environment:auto_stop_in`
O
Olivier Gonzalez 已提交
2485

2486
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8.
O
Olivier Gonzalez 已提交
2487

2488 2489
The `auto_stop_in` keyword is for specifying life period of the environment,
that when expired, GitLab automatically stops them.
O
Olivier Gonzalez 已提交
2490

2491
For example,
O
Olivier Gonzalez 已提交
2492

2493 2494 2495 2496 2497 2498 2499
```yaml
review_app:
  script: deploy-review-app
  environment:
    name: review/$CI_COMMIT_REF_NAME
    auto_stop_in: 1 day
```
O
Olivier Gonzalez 已提交
2500

2501 2502
When `review_app` job is executed and a review app is created, a life period of
the environment is set to `1 day`.
O
Olivier Gonzalez 已提交
2503

2504
For more information, see
2505
[the environments auto-stop documentation](../environments/index.md#environments-auto-stop)
O
Olivier Gonzalez 已提交
2506

2507
#### `environment:kubernetes`
O
Olivier Gonzalez 已提交
2508

2509
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6.
O
Olivier Gonzalez 已提交
2510

2511 2512
The `kubernetes` block is used to configure deployments to a
[Kubernetes cluster](../../user/project/clusters/index.md) that is associated with your project.
O
Olivier Gonzalez 已提交
2513

2514
For example:
2515

2516 2517 2518 2519 2520 2521 2522 2523 2524
```yaml
deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      namespace: production
```
O
Olivier Gonzalez 已提交
2525

2526 2527 2528
This will set up the `deploy` job to deploy to the `production`
environment, using the `production`
[Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).
O
Olivier Gonzalez 已提交
2529

2530
For more information, see
2531
[Available settings for `kubernetes`](../environments/index.md#configuring-kubernetes-deployments).
O
Olivier Gonzalez 已提交
2532

2533 2534 2535 2536
NOTE: **Note:**
Kubernetes configuration is not supported for Kubernetes clusters
that are [managed by GitLab](../../user/project/clusters/index.md#gitlab-managed-clusters).
To follow progress on support for GitLab-managed clusters, see the
2537
[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/38054).
2538

2539
#### Dynamic environments
2540

2541 2542
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21971) in GitLab 8.12 and GitLab Runner 1.6.
> - The `$CI_ENVIRONMENT_SLUG` was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22864) in GitLab 8.15.
2543 2544
> - The `name` and `url` parameters can use any of the defined CI variables,
>   including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
2545
>   You however can't use variables defined under `script`.
2546

2547
For example:
2548

2549 2550 2551 2552 2553 2554 2555 2556
```yaml
deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com/
```
O
Olivier Gonzalez 已提交
2557

2558 2559 2560 2561 2562 2563 2564
The `deploy as review app` job will be marked as deployment to dynamically
create the `review/$CI_COMMIT_REF_NAME` environment, where `$CI_COMMIT_REF_NAME`
is an [environment variable](../variables/README.md) set by the Runner. The
`$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable
for inclusion in URLs. In this case, if the `deploy as review app` job was run
in a branch named `pow`, this environment would be accessible with an URL like
`https://review-pow.example.com/`.
O
Olivier Gonzalez 已提交
2565

2566 2567
This of course implies that the underlying server which hosts the application
is properly configured.
O
Olivier Gonzalez 已提交
2568

2569 2570 2571
The common use case is to create dynamic environments for branches and use them
as Review Apps. You can see a simple example using Review Apps at
<https://gitlab.com/gitlab-examples/review-apps-nginx/>.
O
Olivier Gonzalez 已提交
2572

2573
### `cache`
M
Marcel Amirault 已提交
2574

2575 2576 2577 2578 2579
> - Introduced in GitLab Runner v0.7.0.
> - `cache` can be set globally and per-job.
> - From GitLab 9.0, caching is enabled and shared between pipelines and jobs
>   by default.
> - From GitLab 9.2, caches are restored before [artifacts](#artifacts).
2580

2581 2582 2583
TIP: **Learn more:**
Read how caching works and find out some good practices in the
[caching dependencies documentation](../caching/index.md).
M
Marcel Amirault 已提交
2584

2585 2586 2587
`cache` is used to specify a list of files and directories which should be
cached between jobs. You can only use paths that are within the local working
copy.
M
Marcel Amirault 已提交
2588

2589
If `cache` is defined outside the scope of jobs, it means it's set
2590
globally and all jobs will use that definition.
2591

2592
#### `cache:paths`
2593

2594
Use the `paths` directive to choose which files or directories will be cached. Paths
2595
are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly link outside it.
2596
Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming))
2597 2598 2599 2600 2601 2602
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).
2603

2604
Cache all files in `binaries` that end in `.apk` and the `.config` file:
2605

2606 2607 2608 2609 2610 2611 2612 2613
```yaml
rspec:
  script: test
  cache:
    paths:
      - binaries/*.apk
      - .config
```
2614

2615 2616
Locally defined cache overrides globally defined options. The following `rspec`
job will cache only `binaries/`:
2617

2618
```yaml
2619 2620 2621
cache:
  paths:
    - my/files
2622

2623 2624 2625 2626
rspec:
  script: test
  cache:
    key: rspec
2627
    paths:
P
pityonline 已提交
2628
      - binaries/
2629
```
2630

2631 2632 2633
Note that since cache is shared between jobs, if you're using different
paths for different jobs, you should also set a different **cache:key**
otherwise cache content can be overwritten.
2634

2635
#### `cache:key`
2636

2637
> Introduced in GitLab Runner v1.0.0.
2638

2639 2640 2641
Since the cache is shared between jobs, if you're using different
paths for different jobs, you should also set a different `cache:key`
otherwise cache content can be overwritten.
2642

2643 2644 2645 2646
The `key` directive allows you to define the affinity of caching between jobs,
allowing to have a single cache for all jobs, cache per-job, cache per-branch
or any other way that fits your workflow. This way, you can fine tune caching,
allowing you to cache data between different jobs or even different branches.
S
Shinya Maeda 已提交
2647

2648 2649 2650 2651
The `cache:key` variable can use any of the
[predefined variables](../variables/README.md), and the default key, if not
set, is just literal `default` which means everything is shared between
pipelines and jobs by default, starting from GitLab 9.0.
S
Shinya Maeda 已提交
2652

2653
NOTE: **Note:**
2654
The `cache:key` variable can't contain the `/` character, or the equivalent
2655
URI-encoded `%2F`; a value made only of dots (`.`, `%2E`) is also forbidden.
2656

2657
For example, to enable per-branch caching:
2658

2659 2660 2661 2662 2663 2664
```yaml
cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - binaries/
```
2665

2666 2667
If you use **Windows Batch** to run your shell scripts you need to replace
`$` with `%`:
2668 2669

```yaml
2670 2671 2672 2673 2674
cache:
  key: "%CI_COMMIT_REF_SLUG%"
  paths:
    - binaries/
```
2675

2676
##### `cache:key:files`
2677

2678
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5.
2679

2680 2681 2682
The `cache:key:files` keyword extends the `cache:key` functionality by making it easier
to reuse some caches, and rebuild them less often, which will speed up subsequent pipeline
runs.
2683

2684 2685 2686 2687
When you include `cache:key:files`, you must also list the project files that will be used to generate the key, up to a maximum of two files.
The cache `key` will be a SHA checksum computed from the most recent commits (up to two, if two files are listed)
that changed the given files. If neither file was changed in any commits,
the fallback key will be `default`.
2688

2689 2690 2691 2692 2693 2694 2695 2696 2697 2698
```yaml
cache:
  key:
    files:
      - Gemfile.lock
      - package.json
  paths:
    - vendor/ruby
    - node_modules
```
2699

2700
In this example we're creating a cache for Ruby and Node.js dependencies that
2701 2702 2703 2704
is tied to current versions of the `Gemfile.lock` and `package.json` files. Whenever one of
these files changes, a new cache key is computed and a new cache is created. Any future
job runs using the same `Gemfile.lock` and `package.json`  with `cache:key:files` will
use the new cache, instead of rebuilding the dependencies.
2705

2706
##### `cache:key:prefix`
2707

2708
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5.
2709

2710 2711 2712 2713 2714
The `prefix` parameter adds extra functionality to `key:files` by allowing the key to
be composed of the given `prefix` combined with the SHA computed for `cache:key:files`.
For example, adding a `prefix` of `test`, will cause keys to look like: `test-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`.
If neither file was changed in any commits, the prefix is added to `default`, so the
key in the example would be `test-default`.
2715

2716 2717
Like `cache:key`, `prefix` can use any of the [predefined variables](../variables/README.md),
but the following are not allowed:
2718

2719 2720
- the `/` character (or the equivalent URI-encoded `%2F`)
- a value made only of `.` (or the equivalent URI-encoded `%2E`)
2721

2722 2723 2724 2725 2726 2727 2728 2729
```yaml
cache:
  key:
    files:
      - Gemfile.lock
    prefix: ${CI_JOB_NAME}
  paths:
    - vendor/ruby
2730

2731 2732 2733 2734
rspec:
  script:
    - bundle exec rspec
```
2735

2736 2737 2738 2739 2740 2741 2742
For example, adding a `prefix` of `$CI_JOB_NAME` will
cause the key to look like: `rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5` and
the job cache is shared across different branches. If a branch changes
`Gemfile.lock`, that branch will have a new SHA checksum for `cache:key:files`. A new cache key
will be generated, and a new cache will be created for that key.
If `Gemfile.lock` is not found, the prefix is added to
`default`, so the key in the example would be `rspec-default`.
2743

2744
#### `cache:untracked`
2745

2746 2747
Set `untracked: true` to cache all files that are untracked in your Git
repository:
2748

2749 2750 2751 2752 2753
```yaml
rspec:
  script: test
  cache:
    untracked: true
2754 2755
```

2756
Cache all Git untracked files and files in `binaries`:
2757

2758 2759 2760 2761 2762 2763 2764
```yaml
rspec:
  script: test
  cache:
    untracked: true
    paths:
      - binaries/
2765 2766
```

2767
#### `cache:policy`
2768

2769
> Introduced in GitLab 9.4.
2770

2771
The default behavior of a caching job is to download the files at the start of
2772 2773 2774
execution, and to re-upload them at the end. This allows any changes made by the
job to be persisted for future runs, and is known as the `pull-push` cache
policy.
2775

2776
If you know the job does not alter the cached files, you can skip the upload step
2777 2778 2779
by setting `policy: pull` in the job specification. Typically, this would be
twinned with an ordinary cache job at an earlier stage to ensure the cache
is updated from time to time:
2780 2781

```yaml
2782 2783 2784 2785 2786 2787 2788 2789
stages:
  - setup
  - test

prepare:
  stage: setup
  cache:
    key: gems
2790
    paths:
2791 2792 2793
      - vendor/bundle
  script:
    - bundle install --deployment
2794 2795 2796

rspec:
  stage: test
2797 2798 2799 2800 2801 2802 2803
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - bundle exec rspec ...
2804 2805
```

2806 2807 2808
This helps to speed up job execution and reduce load on the cache server,
especially when you have a large number of cache-using jobs executing in
parallel.
2809

2810 2811 2812
Additionally, if you have a job that unconditionally recreates the cache without
reference to its previous contents, you can use `policy: push` in that job to
skip the download step.
2813

2814
### `artifacts`
2815

2816 2817 2818 2819 2820
> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
> - Windows support was added in GitLab Runner v.1.0.0.
> - From GitLab 9.2, caches are restored before artifacts.
> - Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart).
> - Job artifacts are only collected for successful jobs by default.
2821

2822 2823
`artifacts` is used to specify a list of files and directories which should be
attached to the job when it [succeeds, fails, or always](#artifactswhen).
2824

2825 2826
The artifacts will be sent to GitLab after the job finishes and will
be available for download in the GitLab UI.
2827

2828
[Read more about artifacts](../pipelines/job_artifacts.md).
2829

2830
#### `artifacts:paths`
2831

2832
Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly
2833 2834 2835 2836 2837 2838
link outside it. Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming))
patterns and [`filepath.Match`](https://golang.org/pkg/path/filepath/#Match).

To restrict which jobs a specific job will fetch artifacts from, see [dependencies](#dependencies).

Send all files in `binaries` and `.config`:
2839 2840

```yaml
2841 2842 2843 2844
artifacts:
  paths:
    - binaries/
    - .config
2845 2846
```

2847
To disable artifact passing, define the job with empty [dependencies](#dependencies):
2848

2849 2850 2851 2852 2853 2854
```yaml
job:
  stage: build
  script: make build
  dependencies: []
```
2855

2856 2857
You may want to create artifacts only for tagged releases to avoid filling the
build server storage with temporary build artifacts.
2858

2859
Create artifacts only for tags (`default-job` won't create artifacts):
2860

2861 2862 2863 2864 2865 2866
```yaml
default-job:
  script:
    - mvn test -U
  except:
    - tags
2867

2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878
release-job:
  script:
    - mvn package -U
  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`:
2879 2880

```yaml
2881 2882 2883 2884
job:
  artifacts:
    paths:
      - path/*xyz/*
2885 2886
```

2887 2888
#### `artifacts:exclude`

2889
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15122) in GitLab 13.1
2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913
> - Requires GitLab Runner 13.1

`exclude` makes it possible to prevent files from being added to an artifacts
archive.

Similar to [`artifacts:paths`](#artifactspaths), `exclude` paths are relative
to the project directory. Wildcards can be used that follow the
[glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and
[`filepath.Match`](https://golang.org/pkg/path/filepath/#Match).

For example, to store all files in `binaries/`, but not `*.o` files located in
subdirectories of `binaries/`:

```yaml
artifacts:
  paths:
    - binaries/
  exclude:
    - binaries/**/*.o
```

Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded using
`artifacts:exclude` too.

2914
#### `artifacts:expose_as`
2915

2916
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) in GitLab 12.5.
2917

2918 2919
The `expose_as` keyword can be used to expose [job artifacts](../pipelines/job_artifacts.md)
in the [merge request](../../user/project/merge_requests/index.md) UI.
2920

2921
For example, to match a single file:
2922

2923
```yaml
2924
test:
2925
  script: [ "echo 'test' > file.txt" ]
2926 2927
  artifacts:
    expose_as: 'artifact 1'
2928
    paths: ['file.txt']
2929
```
2930

2931 2932
With this configuration, GitLab will add a link **artifact 1** to the relevant merge request
that points to `file1.txt`.
2933

2934 2935
An example that will match an entire directory:

2936
```yaml
2937
test:
2938
  script: [ "mkdir test && echo 'test' > test/file.txt" ]
2939 2940
  artifacts:
    expose_as: 'artifact 1'
2941
    paths: ['test/']
2942 2943
```

2944 2945
Note the following:

2946
- Artifacts do not display in the merge request UI when using variables to define the `artifacts:paths`.
2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967
- A maximum of 10 job artifacts per merge request can be exposed.
- Glob patterns are unsupported.
- If a directory is specified, the link will be to the job [artifacts browser](../pipelines/job_artifacts.md#browsing-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:
  - Enabled, GitLab will automatically render the artifact.
  - Not enabled, you will see the file in the artifacts browser.

#### `artifacts:name`

> Introduced in GitLab 8.6 and GitLab Runner v1.1.0.

The `name` directive allows you to define the name of the created artifacts
archive. That way, you can have a unique name for every archive which could be
useful when you'd like to download the archive from GitLab. The `artifacts:name`
variable can make use of any of the [predefined variables](../variables/README.md).
The default name is `artifacts`, which becomes `artifacts.zip` when downloaded.

NOTE: **Note:**
If your branch-name contains forward slashes
2968
(for example `feature/my-feature`) it's advised to use `$CI_COMMIT_REF_SLUG`
2969 2970 2971
instead of `$CI_COMMIT_REF_NAME` for proper naming of the artifact.

To create an archive with a name of the current job:
M
Markus Doits 已提交
2972

2973 2974 2975 2976 2977 2978 2979
```yaml
job:
  artifacts:
    name: "$CI_JOB_NAME"
    paths:
      - binaries/
```
2980

2981 2982
To create an archive with a name of the current branch or tag including only
the binaries directory:
2983 2984

```yaml
2985 2986 2987 2988 2989
job:
  artifacts:
    name: "$CI_COMMIT_REF_NAME"
    paths:
      - binaries/
2990 2991
```

2992 2993
To create an archive with a name of the current job and the current branch or
tag including only the binaries directory:
2994 2995

```yaml
2996 2997 2998 2999 3000
job:
  artifacts:
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    paths:
      - binaries/
3001 3002
```

3003
To create an archive with a name of the current [stage](#stages) and branch name:
3004

3005 3006 3007 3008 3009 3010 3011
```yaml
job:
  artifacts:
    name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
    paths:
      - binaries/
```
3012

3013
---
3014

3015 3016
If you use **Windows Batch** to run your shell scripts you need to replace
`$` with `%`:
3017

3018 3019 3020 3021 3022 3023 3024
```yaml
job:
  artifacts:
    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
    paths:
      - binaries/
```
3025

3026 3027
If you use **Windows PowerShell** to run your shell scripts you need to replace
`$` with `$env:`:
3028 3029

```yaml
3030 3031 3032 3033 3034
job:
  artifacts:
    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
    paths:
      - binaries/
3035 3036
```

3037
#### `artifacts:untracked`
M
Matija Čupić 已提交
3038

3039 3040
`artifacts:untracked` is used to add all Git untracked files as artifacts (along
to the paths defined in `artifacts:paths`).
M
Matija Čupić 已提交
3041

3042 3043
NOTE: **Note:**
`artifacts:untracked` ignores configuration in the repository's `.gitignore` file.
M
Matija Čupić 已提交
3044

3045
Send all Git untracked files:
M
Matija Čupić 已提交
3046

3047 3048 3049 3050
```yaml
artifacts:
  untracked: true
```
M
Matija Čupić 已提交
3051

3052
Send all Git untracked files and files in `binaries`:
M
Matija Čupić 已提交
3053

3054
```yaml
3055 3056 3057 3058
artifacts:
  untracked: true
  paths:
    - binaries/
M
Matija Čupić 已提交
3059
```
3060

3061 3062 3063 3064 3065 3066 3067 3068 3069
Send all untracked files but [exclude](#artifactsexclude) `*.txt`:

```yaml
artifacts:
  untracked: true
  exclude:
    - *.txt
```

3070
#### `artifacts:when`
3071

3072
> Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
3073

3074 3075
`artifacts:when` is used to upload artifacts on job failure or despite the
failure.
3076

3077
`artifacts:when` can be set to one of the following values:
3078

3079 3080 3081
1. `on_success` - upload artifacts only when the job succeeds. This is the default.
1. `on_failure` - upload artifacts only when the job fails.
1. `always` - upload artifacts regardless of the job status.
3082

3083
To upload artifacts only when job fails:
3084

3085 3086 3087 3088 3089
```yaml
job:
  artifacts:
    when: on_failure
```
3090

3091
#### `artifacts:expire_in`
E
Evan Read 已提交
3092

3093
> Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
E
Evan Read 已提交
3094

3095 3096 3097 3098
`expire_in` allows you to specify how long artifacts should live before they
expire and are therefore deleted, counting from the time they are 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-core-only)
3099
(30 days by default).
E
Evan Read 已提交
3100

3101 3102
You can use the **Keep** button on the job page to override expiration and
keep artifacts forever.
3103

3104 3105
After their expiry, artifacts are deleted hourly by default (via a cron job),
and are not accessible anymore.
E
Evan Read 已提交
3106

3107
The value of `expire_in` is an elapsed time in seconds, unless a unit is
3108
provided. Examples of valid values:
3109

3110 3111 3112 3113 3114 3115 3116
- `42`
- `3 mins 4 sec`
- `2 hrs 20 min`
- `2h20min`
- `6 mos 1 day`
- `47 yrs 6 mos and 4d`
- `3 weeks and 2 days`
E
Evan Read 已提交
3117

3118
To expire artifacts 1 week after being uploaded:
E
Evan Read 已提交
3119 3120

```yaml
3121 3122 3123
job:
  artifacts:
    expire_in: 1 week
E
Evan Read 已提交
3124 3125
```

3126
NOTE: **Note:**
3127
For artifacts created in [GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/16267)
3128 3129
and later, the latest artifact for a ref is always kept, regardless of the expiry time.

3130
#### `artifacts:reports`
E
Evan Read 已提交
3131

3132 3133
The [`artifacts:reports` keyword](../pipelines/job_artifacts.md#artifactsreports)
is used for collecting test reports, code quality reports, and security reports from jobs.
3134
It also exposes these reports in GitLab's UI (merge requests, pipeline views, and security dashboards).
3135

3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148
These are the available report types:

| Parameter                                                                                                                            | Description |
|--------------------------------------------------------------------------------------------------------------------------------------|-------------|
| [`artifacts:reports:junit`](../pipelines/job_artifacts.md#artifactsreportsjunit)                                                     | The `junit` report collects JUnit XML files.                                     |
| [`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv)                                                   | The `dotenv` report collects a set of environment variables.                     |
| [`artifacts:reports:cobertura`](../pipelines/job_artifacts.md#artifactsreportscobertura)                                             | The `cobertura` report collects Cobertura coverage XML files.                    |
| [`artifacts:reports:terraform`](../pipelines/job_artifacts.md#artifactsreportsterraform)                                             | The `terraform` report collects Terraform `tfplan.json` files.                   |
| [`artifacts:reports:codequality`](../pipelines/job_artifacts.md#artifactsreportscodequality-starter) **(STARTER)**                   | The `codequality` report collects CodeQuality issues.                            |
| [`artifacts:reports:sast`](../pipelines/job_artifacts.md#artifactsreportssast-ultimate) **(ULTIMATE)**                               | The `sast` report collects Static Application Security Testing vulnerabilities.  |
| [`artifacts:reports:dependency_scanning`](../pipelines/job_artifacts.md#artifactsreportsdependency_scanning-ultimate) **(ULTIMATE)** | The `dependency_scanning` report collects Dependency Scanning vulnerabilities.   |
| [`artifacts:reports:container_scanning`](../pipelines/job_artifacts.md#artifactsreportscontainer_scanning-ultimate) **(ULTIMATE)**   | The `container_scanning` report collects Container Scanning vulnerabilities.     |
| [`artifacts:reports:dast`](../pipelines/job_artifacts.md#artifactsreportsdast-ultimate) **(ULTIMATE)**                               | The `dast` report collects Dynamic Application Security Testing vulnerabilities. |
3149
| [`artifacts:reports:license_management`](../pipelines/job_artifacts.md#artifactsreportslicense_management-ultimate) **(ULTIMATE)**   | The `license_management` report collects Licenses (*removed from GitLab 13.0*).  |
3150
| [`artifacts:reports:license_scanning`](../pipelines/job_artifacts.md#artifactsreportslicense_scanning-ultimate) **(ULTIMATE)**       | The `license_scanning` report collects Licenses.                                 |
3151 3152
| [`artifacts:reports:performance`](../pipelines/job_artifacts.md#artifactsreportsperformance-premium) **(PREMIUM)**                   | The `performance` report collects Browser Performance metrics.                   |
| [`artifacts:reports:load_performance`](../pipelines/job_artifacts.md#artifactsreportsload_performance-premium) **(PREMIUM)**         | The `load_performance` report collects load performance metrics.                 |
3153
| [`artifacts:reports:metrics`](../pipelines/job_artifacts.md#artifactsreportsmetrics-premium) **(PREMIUM)**                           | The `metrics` report collects Metrics.                                           |
E
Evan Read 已提交
3154

3155
#### `dependencies`
3156

3157
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
3158

3159 3160 3161
By default, all [`artifacts`](#artifacts) from all previous [stages](#stages)
are passed, but you can use the `dependencies` parameter to define a limited
list of jobs (or no jobs) to fetch artifacts from.
3162

3163 3164 3165 3166 3167 3168
To use this feature, define `dependencies` in context of the job and pass
a list of all previous jobs from which the artifacts should be downloaded.
You can only define jobs from stages that are executed before the current one.
An error will be shown if you define jobs from the current stage or next ones.
Defining an empty array will skip downloading any artifacts for that job.
The status of the previous job is not considered when using `dependencies`, so
3169
if it failed or it's a manual job that was not run, no error occurs.
3170

3171 3172 3173 3174
In the following example, we define two jobs with artifacts, `build:osx` and
`build:linux`. When the `test:osx` is executed, the artifacts from `build:osx`
will be downloaded and extracted in the context of the build. The same happens
for `test:linux` and artifacts from `build:linux`.
3175

3176 3177
The job `deploy` will download artifacts from all previous jobs because of
the [stage](#stages) precedence:
K
Kamil Trzciński 已提交
3178

3179
```yaml
3180 3181 3182 3183 3184 3185
build:osx:
  stage: build
  script: make build:osx
  artifacts:
    paths:
      - binaries/
K
Kamil Trzciński 已提交
3186

3187 3188 3189 3190 3191 3192
build:linux:
  stage: build
  script: make build:linux
  artifacts:
    paths:
      - binaries/
3193

3194 3195 3196 3197 3198
test:osx:
  stage: test
  script: make test:osx
  dependencies:
    - build:osx
3199

3200 3201 3202 3203 3204
test:linux:
  stage: test
  script: make test:linux
  dependencies:
    - build:linux
3205

3206 3207 3208
deploy:
  stage: deploy
  script: make deploy
3209 3210
```

3211
##### When a dependent job will fail
K
Kamil Trzciński 已提交
3212

3213
> Introduced in GitLab 10.3.
3214

3215 3216 3217 3218
If the artifacts of the job that is set as a dependency have been
[expired](#artifactsexpire_in) or
[erased](../pipelines/job_artifacts.md#erasing-artifacts), then
the dependent job will fail.
3219

3220 3221 3222 3223
NOTE: **Note:**
You can ask your administrator to
[flip this switch](../../administration/job_artifacts.md#validation-for-dependencies)
and bring back the old behavior.
K
Kamil Trzciński 已提交
3224

3225
### `coverage`
3226

3227
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20428) in GitLab 8.17.
3228

3229 3230
`coverage` allows you to configure how code coverage will be extracted from the
job output.
3231

3232 3233 3234 3235
Regular expressions are the only valid kind of value expected here. So, using
surrounding `/` is mandatory in order to consistently and explicitly represent
a regular expression string. You must escape special characters if you want to
match them literally.
3236

3237
A simple example:
K
Kamil Trzciński 已提交
3238

3239
```yaml
3240 3241 3242
job1:
  script: rspec
  coverage: '/Code coverage: \d+\.\d+/'
K
Kamil Trzciński 已提交
3243 3244
```

3245
### `retry`
3246

3247 3248
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3442) in GitLab 9.5.
> - [Behavior expanded](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3515) in GitLab 11.5 to control on which failures to retry.
3249

3250 3251
`retry` allows you to configure how many times a job is going to be retried in
case of a failure.
3252

3253
When a job fails and has `retry` configured, it's going to be processed again
3254
up to the amount of times specified by the `retry` keyword.
3255

3256 3257 3258 3259 3260
If `retry` is set to 2, and a job succeeds in a second run (first retry), it won't be retried
again. `retry` value has to be a positive integer, equal or larger than 0, but
lower or equal to 2 (two retries maximum, three runs in total).

A simple example to retry in all failure cases:
3261

3262
```yaml
3263 3264 3265
test:
  script: rspec
  retry: 2
3266
```
3267

3268 3269
By default, a job will be retried on all failure cases. To have a better control
on which failures to retry, `retry` can be a hash with the following keys:
3270

3271 3272
- `max`: The maximum number of retries.
- `when`: The failure cases to retry.
3273

3274
To retry only runner system failures at maximum two times:
3275

3276 3277 3278 3279 3280 3281 3282
```yaml
test:
  script: rspec
  retry:
    max: 2
    when: runner_system_failure
```
3283

3284 3285
If there is another failure, other than a runner system failure, the job will
not be retried.
3286

3287
To retry on multiple failure cases, `when` can also be an array of failures:
3288

3289 3290 3291 3292 3293 3294 3295 3296 3297
```yaml
test:
  script: rspec
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
```
K
Kamil Trzciński 已提交
3298

3299
Possible values for `when` are:
K
Kamil Trzciński 已提交
3300

3301 3302 3303 3304
<!--
  Please make sure to update `RETRY_WHEN_IN_DOCUMENTATION` array in
  `spec/lib/gitlab/ci/config/entry/retry_spec.rb` if you change any of
  the documented values below. The test there makes sure that all documented
3305
  values are really valid as a configuration option and therefore should always
3306 3307
  stay in sync with this documentation.
 -->
3308

3309 3310 3311 3312 3313
- `always`: Retry on any failure (default).
- `unknown_failure`: Retry when the failure reason is unknown.
- `script_failure`: Retry when the script failed.
- `api_failure`: Retry on API failure.
- `stuck_or_timeout_failure`: Retry when the job got stuck or timed out.
3314
- `runner_system_failure`: Retry if there was a runner system failure (for example, job setup failed).
3315 3316 3317 3318
- `missing_dependency_failure`: Retry if a dependency was missing.
- `runner_unsupported`: Retry if the runner was unsupported.
- `stale_schedule`: Retry if a delayed job could not be executed.
- `job_execution_timeout`: Retry if the script exceeded the maximum execution time set for the job.
3319
- `archived_failure`: Retry if the job is archived and can't be run.
3320 3321 3322
- `unmet_prerequisites`: Retry if the job failed to complete prerequisite tasks.
- `scheduler_failure`: Retry if the scheduler failed to assign the job to a runner.
- `data_integrity_failure`: Retry if there was a structural integrity problem detected.
3323

3324 3325
You can specify the number of [retry attempts for certain stages of job execution](#job-stages-attempts) using variables.

3326
### `timeout`
3327

3328
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) in GitLab 12.3.
3329

3330
`timeout` allows you to configure a timeout for a specific job. For example:
3331

3332
```yaml
3333 3334 3335 3336 3337 3338 3339
build:
  script: build.sh
  timeout: 3 hours 30 minutes

test:
  script: rspec
  timeout: 3h 30m
3340 3341
```

3342
The job-level timeout can exceed the
3343
[project-level timeout](../pipelines/settings.md#timeout) but can't
3344
exceed the Runner-specific timeout.
3345

3346
### `parallel`
3347

3348
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) in GitLab 11.5.
3349

3350 3351
`parallel` allows you to configure how many instances of a job to run in
parallel. This value has to be greater than or equal to two (2) and less than or equal to 50.
3352

3353
This creates N instances of the same job that run in parallel. They are named
3354
sequentially from `job_name 1/N` to `job_name N/N`.
3355

3356
For every job, `CI_NODE_INDEX` and `CI_NODE_TOTAL` [environment variables](../variables/README.md#predefined-environment-variables) are set.
K
Kamil Trzciński 已提交
3357

3358 3359
Marking a job to be run in parallel requires adding `parallel` to your configuration
file. For example:
K
Kamil Trzciński 已提交
3360

3361
```yaml
3362 3363 3364
test:
  script: rspec
  parallel: 5
3365
```
3366

3367 3368 3369
TIP: **Tip:**
Parallelize tests suites across parallel jobs.
Different languages have different tools to facilitate this.
K
Kamil Trzciński 已提交
3370

3371
A simple example using [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters) and RSpec to run some Ruby tests:
K
Kamil Trzciński 已提交
3372

3373 3374 3375
```ruby
# Gemfile
source 'https://rubygems.org'
K
Kamil Trzciński 已提交
3376

3377 3378 3379
gem 'rspec'
gem 'semaphore_test_boosters'
```
3380

3381
```yaml
3382 3383
test:
  parallel: 3
3384
  script:
3385 3386
    - bundle
    - bundle exec rspec_booster --job $CI_NODE_INDEX/$CI_NODE_TOTAL
3387
```
3388

3389 3390
CAUTION: **Caution:**
Please be aware that semaphore_test_boosters reports usages statistics to the author.
3391

3392 3393
You can then navigate to the **Jobs** tab of a new pipeline build and see your RSpec
job split into three separate jobs.
3394

3395
### `trigger`
3396

3397 3398
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Core in 12.8.
3399

3400 3401 3402
`trigger` allows you to define downstream pipeline trigger. When a job created
from `trigger` definition is started by GitLab, a downstream pipeline gets
created.
3403

3404
This keyword allows the creation of two different types of downstream pipelines:
3405

3406 3407
- [Multi-project pipelines](../multi_project_pipelines.md#creating-multi-project-pipelines-from-gitlab-ciyml)
- [Child pipelines](../parent_child_pipelines.md)
3408

3409 3410 3411 3412
NOTE: **Note:**
Using a `trigger` with `when:manual` together results in the error `jobs:#{job-name}
when should be on_success, on_failure or always`, because `when:manual` prevents
triggers being used.
3413

3414
#### Simple `trigger` syntax for multi-project pipelines
3415

3416 3417
The simplest way to configure a downstream trigger is to use `trigger` keyword
with a full path to a downstream project:
3418

3419 3420 3421 3422
```yaml
rspec:
  stage: test
  script: bundle exec rspec
3423

3424 3425 3426 3427
staging:
  stage: deploy
  trigger: my/deployment
```
3428

3429
#### Complex `trigger` syntax for multi-project pipelines
3430

3431
It's possible to configure a branch name that GitLab will use to create
3432
a downstream pipeline with:
3433

3434
```yaml
3435 3436 3437 3438 3439 3440 3441 3442 3443
rspec:
  stage: test
  script: bundle exec rspec

staging:
  stage: deploy
  trigger:
    project: my/deployment
    branch: stable
3444 3445
```

3446
It's possible to mirror the status from a triggered pipeline:
3447

3448
```yaml
3449 3450 3451 3452 3453
trigger_job:
  trigger:
    project: my/project
    strategy: depend
```
3454

3455
It's possible to mirror the status from an upstream pipeline:
3456

3457 3458 3459 3460 3461
```yaml
upstream_bridge:
  stage: test
  needs:
    pipeline: other/project
3462 3463
```

3464
#### `trigger` syntax for child pipeline
3465

3466
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16094) in GitLab 12.7.
3467

3468 3469
To create a [child pipeline](../parent_child_pipelines.md), specify the path to the
YAML file containing the CI config of the child pipeline:
3470 3471

```yaml
3472 3473 3474
trigger_job:
  trigger:
    include: path/to/child-pipeline.yml
3475 3476
```

3477
Similar to [multi-project pipelines](../multi_project_pipelines.md#mirroring-status-from-triggered-pipeline),
3478
it's possible to mirror the status from a triggered pipeline:
3479 3480

```yaml
3481 3482 3483 3484 3485
trigger_job:
  trigger:
    include:
      - local: path/to/child-pipeline.yml
    strategy: depend
3486 3487
```

3488
##### Trigger child pipeline with generated configuration file
3489

3490
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) in GitLab 12.9.
3491

3492
You can also trigger a child pipeline from a [dynamically generated configuration file](../parent_child_pipelines.md#dynamic-child-pipelines):
3493 3494

```yaml
3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507
generate-config:
  stage: build
  script: generate-ci-config > generated-config.yml
  artifacts:
    paths:
      - generated-config.yml

child-pipeline:
  stage: test
  trigger:
    include:
      - artifact: generated-config.yml
        job: generate-config
3508 3509
```

3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521
The `generated-config.yml` is extracted from the artifacts and used as the configuration
for triggering the child pipeline.

#### Linking pipelines with `trigger:strategy`

By default, the `trigger` job completes with the `success` status
as soon as the downstream pipeline is created.

To force the `trigger` job to wait for the downstream (multi-project or child) pipeline to complete, use
`strategy: depend`. This will make the trigger job wait with a "running" status until the triggered
pipeline completes. At that point, the `trigger` job will complete and display the same status as
the downstream job.
3522 3523

```yaml
3524 3525 3526 3527
trigger_job:
  trigger:
    include: path/to/child-pipeline.yml
    strategy: depend
3528 3529
```

3530 3531 3532
This can help keep your pipeline execution linear. In the example above, jobs from
subsequent stages will wait for the triggered pipeline to successfully complete before
starting, at the cost of reduced parallelization.
3533

3534
#### Trigger a pipeline by API call
3535

3536 3537
Triggers can be used to force a rebuild of a specific branch, tag or commit,
with an API call when a pipeline gets created using a trigger token.
3538

3539
Not to be confused with the [`trigger`](#trigger) parameter.
3540

3541
[Read more in the triggers documentation.](../triggers/README.md)
3542

3543
### `interruptible`
3544

3545
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3.
3546

3547 3548 3549
`interruptible` is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Defaults to `false`.
This value will only be used if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-pending-pipelines)
is enabled.
3550

3551
When enabled, a pipeline on the same branch will be canceled when:
3552

3553 3554
- it's made redundant by a newer pipeline run.
- Either all jobs are set as interruptible, or any uninterruptible jobs haven't started.
3555

3556
Pending jobs are always considered interruptible.
3557

3558 3559
TIP: **Tip:**
Set jobs as interruptible that can be safely canceled once started (for instance, a build job).
3560

3561
Here is a simple example:
3562 3563

```yaml
3564 3565 3566 3567
stages:
  - stage1
  - stage2
  - stage3
3568

3569 3570 3571 3572 3573
step-1:
  stage: stage1
  script:
    - echo "Can be canceled."
  interruptible: true
3574

3575 3576 3577 3578
step-2:
  stage: stage2
  script:
    - echo "Can not be canceled."
3579

3580 3581 3582 3583 3584
step-3:
  stage: stage3
  script:
    - echo "Because step-2 can not be canceled, this step will never be canceled, even though set as interruptible."
  interruptible: true
3585 3586
```

3587
In the example above, a new pipeline run will cause an existing running pipeline to be:
W
Wolphin 已提交
3588

3589 3590
- Canceled, if only `step-1` is running or pending.
- Not canceled, once `step-2` starts running.
W
Wolphin 已提交
3591

3592 3593
NOTE: **Note:**
Once an uninterruptible job is running, the pipeline will never be canceled, regardless of the final job's state.
W
Wolphin 已提交
3594

3595
### `resource_group`
W
Wolphin 已提交
3596

3597
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7.
W
Wolphin 已提交
3598

3599 3600
Sometimes running multiples jobs or pipelines at the same time in an environment
can lead to errors during the deployment.
W
Wolphin 已提交
3601

3602
To avoid these errors, the `resource_group` attribute can be used to ensure that
3603
the Runner won't run certain jobs simultaneously.
3604

3605 3606 3607 3608 3609
When the `resource_group` key is defined for a job in `.gitlab-ci.yml`,
job executions are mutually exclusive across different pipelines for the same project.
If multiple jobs belonging to the same resource group are enqueued simultaneously,
only one of the jobs will be picked by the Runner, and the other jobs will wait until the
`resource_group` is free.
3610

3611
Here is a simple example:
3612 3613

```yaml
3614 3615 3616
deploy-to-production:
  script: deploy
  resource_group: production
3617 3618
```

3619
In this case, if a `deploy-to-production` job is running in a pipeline, and a new
3620
`deploy-to-production` job is created in a different pipeline, it won't run until
3621 3622
the currently running/pending `deploy-to-production` job is finished. As a result,
you can ensure that concurrent deployments will never happen to the production environment.
3623

3624 3625 3626
There can be multiple `resource_group`s defined per environment. A good use case for this
is when deploying to physical devices. You may have more than one physical device, and each
one can be deployed to, but there can be only one deployment per device at any given time.
3627

3628
NOTE: **Note:**
3629 3630
This key can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces.
It can't start or end with `/`.
3631

3632 3633
For more information, see [Deployments Safety](../environments/deployment_safety.md).

3634 3635 3636 3637
### `release`

> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/19298) in GitLab 13.2.

3638 3639
`release` indicates that the job creates a [Release](../../user/project/releases/index.md),
and optionally includes URLs for Release assets.
3640 3641 3642 3643

These methods are supported:

- [`tag_name`](#releasetag_name)
3644 3645 3646 3647 3648
- [`name`](#releasename) (optional)
- [`description`](#releasedescription) (optional)
- [`ref`](#releaseref) (optional)
- [`milestones`](#releasemilestones) (optional)
- [`released_at`](#releasereleased_at) (optional)
3649 3650 3651 3652 3653 3654 3655 3656 3657

The Release is created only if the job processes without error. If the Rails API
returns an error during Release creation, the `release` job fails.

#### `release-cli` Docker image

The Docker image to use for the `release-cli` must be specified, using the following directive:

```yaml
3658
image: registry.gitlab.com/gitlab-org/release-cli:latest
3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676
```

#### Script

All jobs require a `script` tag at a minimum. A `:release` job can use the output of a
`:script` tag, but if this is not necessary, a placeholder script can be used, for example:

```yaml
script:
  - echo 'release job'
```

An [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/223856) exists to remove this requirement in an upcoming version of GitLab.

A pipeline can have multiple `release` jobs, for example:

```yaml
ios-release:
3677 3678
  script:
    - echo 'iOS release job'
3679 3680
  release:
     tag_name: v1.0.0-ios
3681
     description: 'iOS release v1.0.0'
3682 3683

android-release:
3684 3685
  script:
    - echo 'Android release job'
3686 3687
  release:
     tag_name: v1.0.0-android
3688
     description: 'Android release v1.0.0'
3689 3690 3691 3692 3693 3694
```

#### `release:tag_name`

The `tag_name` must be specified. It can refer to an existing Git tag or can be specified by the user.

3695
When the specified tag doesn't exist in the repository, a new tag is created from the associated SHA of the pipeline.
3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721

For example, when creating a Release from a Git tag:

```yaml
job:
  release:
    tag_name: $CI_COMMIT_TAG
    description: changelog.txt
```

It is also possible to create any unique tag, in which case `only: tags` is not mandatory.
A semantic versioning example:

```yaml
job:
  release:
    tag_name: ${MAJOR}_${MINOR}_${REVISION}
    description: changelog.txt
```

- The Release is created only if the job's main script succeeds.
- If the Release already exists, it is not updated and the job with the `release` keyword fails.
- The `release` section executes after the `script` tag and before the `after_script`.

#### `release:name`

3722
The Release name. If omitted, it is populated with the value of `release: tag_name`.
3723 3724 3725

#### `release:description`

3726
Specifies the longer description of the Release.
3727 3728 3729

#### `release:ref`

3730 3731
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.
3732 3733 3734 3735 3736 3737 3738

#### `release:milestones`

The title of each milestone the release is associated with.

#### `release:released_at`

3739 3740
The date and time when the release is ready. Defaults to the current date and time if not
defined. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
3741 3742 3743

#### Complete example for `release`

3744 3745 3746
Combining the individual examples given above for `release` results in the following
code snippets. There are two options, depending on how you generate the
tags. These options cannot be used together, so choose one:
3747

3748 3749
- To create a release when you push a Git tag, or when you add a Git tag
  in the UI by going to **Repository > Tags**:
3750

3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796
  ```yaml
  release_job:
    stage: release
    image: registry.gitlab.com/gitlab-org/release-cli:latest
    rules:
      - if: $CI_COMMIT_TAG                  # Run this job when a tag is created manually
    script:
      - echo 'running release_job'
    release:
       name: 'Release $CI_COMMIT_TAG'
       description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined
       tag_name: '$CI_COMMIT_TAG'                                      # elsewhere in the pipeline.
       ref: '$CI_COMMIT_TAG'
       milestones:
         - 'm1'
         - 'm2'
         - 'm3'
       released_at: '2020-07-15T08:00:00Z'  # Optional, will auto generate if not defined,
                                            # or can use a variable.
  ```

- To create a release automatically when changes are pushed to the default branch,
  using a new Git tag that is defined with variables:

  ```yaml
  release_job:
    stage: release
    image: registry.gitlab.com/gitlab-org/release-cli:latest
    rules:
      - if: $CI_COMMIT_TAG
        when: never                                 # Do not run this job when a tag is created manually
      - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when the default branch changes
    script:
      - echo 'running release_job'
    release:
       name: 'Release $CI_COMMIT_SHA'
       description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the tag_name
       tag_name: 'v${MAJOR}.${MINOR}.${REVISION}'                      # variables must be defined elsewhere
       ref: '$CI_COMMIT_SHA'                                           # in the pipeline.
       milestones:
         - 'm1'
         - 'm2'
         - 'm3'
       released_at: '2020-07-15T08:00:00Z'          # Optional, will auto generate if not defined,
                                                    # or can use a variable.
  ```
3797 3798 3799 3800 3801 3802 3803

#### `releaser-cli` command line

The entries under the `:release` node are transformed into a `bash` command line and sent
to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli).
You can also call the `release-cli` directly from a `script` entry.

3804
The YAML described above would be translated into a CLI command like this:
3805 3806

```shell
3807
release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3"
3808 3809
```

E
Evan Read 已提交
3810
### `pages`
3811 3812 3813 3814 3815 3816 3817 3818 3819

`pages` is a special job that is used to upload static content to GitLab that
can be used to serve your website. It has a special syntax, so the two
requirements below must be met:

- Any static content must be placed under a `public/` directory.
- `artifacts` with a path to the `public/` directory must be defined.

The example below simply moves all files from the root of the project to the
3820
`public/` directory. The `.public` workaround is so `cp` does not also copy
3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837
`public/` to itself in an infinite loop:

```yaml
pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  only:
    - master
```

Read more on [GitLab Pages user documentation](../../user/project/pages/index.md).
3838

3839
## `variables`
3840 3841 3842 3843 3844

> Introduced in GitLab Runner v0.5.0.

NOTE: **Note:**
Integers (as well as strings) are legal both for variable's name and value.
3845
Floats are not legal and can't be used.
3846 3847 3848

GitLab CI/CD allows you to define variables inside `.gitlab-ci.yml` that are
then passed in the job environment. They can be set globally and per-job.
3849 3850
When the `variables` keyword is used on a job level, it will override the global
YAML variables and predefined ones of the same name.
3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864

They are stored in the Git repository and are meant to store non-sensitive
project configuration, for example:

```yaml
variables:
  DATABASE_URL: "postgres://postgres@postgres/my_database"
```

These variables can be later used in all executed commands and scripts.
The YAML-defined variables are also set to all created service containers,
thus allowing to fine tune them.

Except for the user defined variables, there are also the ones [set up by the
E
Evan Read 已提交
3865
Runner itself](../variables/README.md#predefined-environment-variables).
3866 3867 3868
One example would be `CI_COMMIT_REF_NAME` which has the value of
the branch or tag name for which project is built. Apart from the variables
you can set in `.gitlab-ci.yml`, there are also the so called
3869
[Variables](../variables/README.md#gitlab-cicd-environment-variables)
3870 3871
which can be set in GitLab's UI.

3872
[YAML anchors for variables](#yaml-anchors-for-variables) are available.
3873

3874
Learn more about [variables and their priority](../variables/README.md).
3875

3876
### Git strategy
M
Mark Pundsack 已提交
3877

3878 3879 3880 3881 3882
> - Introduced in GitLab 8.9 as an experimental feature.
> - `GIT_STRATEGY=none` requires GitLab Runner v1.7+.

CAUTION: **Caution:**
May change or be removed completely in future releases.
N
Nick Thomas 已提交
3883 3884

You can set the `GIT_STRATEGY` used for getting recent application code, either
3885 3886
globally or per-job in the [`variables`](#variables) section. If left
unspecified, the default from project settings will be used.
M
Mark Pundsack 已提交
3887

N
Nick Thomas 已提交
3888 3889 3890
There are three possible values: `clone`, `fetch`, and `none`.

`clone` is the slowest option. It clones the repository from scratch for every
3891
job, ensuring that the local working copy is always pristine.
M
Mark Pundsack 已提交
3892

3893
```yaml
M
Mark Pundsack 已提交
3894 3895 3896 3897
variables:
  GIT_STRATEGY: clone
```

3898
`fetch` is faster as it re-uses the local working copy (falling back to `clone`
3899
if it does not exist). `git clean` is used to undo any changes made by the last
N
Nick Thomas 已提交
3900
job, and `git fetch` is used to retrieve commits made since the last job ran.
M
Mark Pundsack 已提交
3901

3902
```yaml
M
Mark Pundsack 已提交
3903 3904 3905 3906
variables:
  GIT_STRATEGY: fetch
```

3907
`none` also re-uses the local working copy, but skips all Git operations
3908
(including GitLab Runner's pre-clone script, if present). It's mostly useful
3909
for jobs that operate exclusively on artifacts (for example, `deploy`). Git repository
3910
data may be present, but it's certain to be out of date, so you should only
3911
rely on files brought into the local working copy from cache or artifacts.
N
Nick Thomas 已提交
3912

3913
```yaml
N
Nick Thomas 已提交
3914 3915 3916 3917
variables:
  GIT_STRATEGY: none
```

3918
NOTE: **Note:** `GIT_STRATEGY` is not supported for
E
Evan Read 已提交
3919
[Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html),
3920
but may be in the future. See the [support Git strategy with Kubernetes executor feature proposal](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3847)
3921 3922
for updates.

3923
### Git submodule strategy
3924 3925 3926 3927

> Requires GitLab Runner v1.10+.

The `GIT_SUBMODULE_STRATEGY` variable is used to control if / how Git
3928 3929
submodules are included when fetching the code before a build. You can set them
globally or per-job in the [`variables`](#variables) section.
3930

3931
There are three possible values: `none`, `normal`, and `recursive`:
3932

3933
- `none` means that submodules won't be included when fetching the project
3934 3935
  code. This is the default, which matches the pre-v1.10 behavior.

3936
- `normal` means that only the top-level submodules will be included. It's
3937
  equivalent to:
3938

3939
  ```shell
M
Marcel Amirault 已提交
3940 3941 3942
  git submodule sync
  git submodule update --init
  ```
3943 3944

- `recursive` means that all submodules (including submodules of submodules)
3945 3946
  will be included. This feature needs Git v1.8.1 and later. When using a
  GitLab Runner with an executor not based on Docker, make sure the Git version
3947
  meets that requirement. It's equivalent to:
3948

3949
  ```shell
M
Marcel Amirault 已提交
3950 3951 3952
  git submodule sync --recursive
  git submodule update --init --recursive
  ```
3953 3954 3955

Note that for this feature to work correctly, the submodules must be configured
(in `.gitmodules`) with either:
3956

3957 3958 3959 3960
- the HTTP(S) URL of a publicly-accessible repository, or
- a relative path to another repository on the same GitLab server. See the
  [Git submodules](../git_submodules.md) documentation.

3961
### Git checkout
3962

E
Evan Read 已提交
3963
> Introduced in GitLab Runner 9.3.
3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985

The `GIT_CHECKOUT` variable can be used when the `GIT_STRATEGY` is set to either
`clone` or `fetch` to specify whether a `git checkout` should be run. If not
specified, it defaults to true. You can set them globally or per-job in the
[`variables`](#variables) section.

If set to `false`, the Runner will:

- when doing `fetch` - update the repository and leave working copy on
  the current revision,
- when doing `clone` - clone the repository and leave working copy on the
  default branch.

Having this setting set to `true` will mean that for both `clone` and `fetch`
strategies the Runner will checkout the working copy to a revision related
to the CI pipeline:

```yaml
variables:
  GIT_STRATEGY: clone
  GIT_CHECKOUT: "false"
script:
3986 3987 3988 3989
  - git checkout -B master origin/master
  - git merge $CI_COMMIT_SHA
```

3990
### Git clean flags
3991 3992 3993 3994 3995 3996 3997

> Introduced in GitLab Runner 11.10

The `GIT_CLEAN_FLAGS` variable is used to control the default behavior of
`git clean` after checking out the sources. You can set it globally or per-job in the
[`variables`](#variables) section.

3998
`GIT_CLEAN_FLAGS` accepts all possible options of the [`git clean`](https://git-scm.com/docs/git-clean)
3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014
command.

`git clean` is disabled if `GIT_CHECKOUT: "false"` is specified.

If `GIT_CLEAN_FLAGS` is:

- Not specified, `git clean` flags default to `-ffdx`.
- Given the value `none`, `git clean` is not executed.

For example:

```yaml
variables:
  GIT_CLEAN_FLAGS: -ffdx -e cache/
script:
  - ls -al cache/
4015
```
4016

4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035
### Git fetch extra flags

> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4142) in GitLab Runner 13.1.

The `GIT_FETCH_EXTRA_FLAGS` variable is used to control the behavior of
`git fetch`. You can set it globally or per-job in the [`variables`](#variables) section.

`GIT_FETCH_EXTRA_FLAGS` accepts all possible options of the [`git fetch`](https://git-scm.com/docs/git-fetch) command, but please note that `GIT_FETCH_EXTRA_FLAGS` flags will be appended after the default flags that can't be modified.

The default flags are:

- [GIT_DEPTH](#shallow-cloning).
- The list of [refspecs](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec).
- A remote called `origin`.

If `GIT_FETCH_EXTRA_FLAGS` is:

- Not specified, `git fetch` flags default to `--prune --quiet` along with the default flags.
- Given the value `none`, `git fetch` is executed only with the default flags.
4036

4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053
For example, the default flags are `--prune --quiet`, so you can make `git fetch` more verbose by overriding this with just `--prune`:

```yaml
variables:
  GIT_FETCH_EXTRA_FLAGS: --prune
script:
  - ls -al cache/
```

The configurtion above will result in `git fetch` being called this way:

```shell
git fetch origin $REFSPECS --depth 50  --prune
```

Where `$REFSPECS` is a value provided to the Runner internally by GitLab.

4054
### Job stages attempts
4055 4056 4057

> Introduced in GitLab, it requires GitLab Runner v1.9+.

4058
You can set the number for attempts the running job will try to execute each
4059 4060
of the following stages:

4061 4062 4063 4064 4065 4066
| Variable                          | Description                                                                                                                                                                                                                                                                                                        |
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **GET_SOURCES_ATTEMPTS**          | Number of attempts to fetch sources running a job                                                                                                                                                                                                                                                                  |
| **ARTIFACT_DOWNLOAD_ATTEMPTS**    | Number of attempts to download artifacts running a job                                                                                                                                                                                                                                                             |
| **RESTORE_CACHE_ATTEMPTS**        | Number of attempts to restore the cache running a job                                                                                                                                                                                                                                                              |
| **EXECUTOR_JOB_SECTION_ATTEMPTS** | [Since GitLab 12.10](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450), the number of attempts to run a section in a job after a [`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) error ([Docker executor](https://docs.gitlab.com/runner/executors/docker.html) only). |
4067 4068 4069 4070 4071

The default is one single attempt.

Example:

4072
```yaml
4073
variables:
4074
  GET_SOURCES_ATTEMPTS: 3
4075 4076
```

4077
You can set them globally or per-job in the [`variables`](#variables) section.
4078

4079
### Shallow cloning
M
Mark Pundsack 已提交
4080

4081 4082
> Introduced in GitLab 8.9 as an experimental feature.

4083 4084
NOTE: **Note**:
As of GitLab 12.0, newly created projects will automatically have a [default `git depth` value of `50`](../pipelines/settings.md#git-shallow-clone).
M
Mark Pundsack 已提交
4085 4086

You can specify the depth of fetching and cloning using `GIT_DEPTH`. This allows
M
Mark Pundsack 已提交
4087 4088 4089
shallow cloning of the repository which can significantly speed up cloning for
repositories with a large number of commits or old, large binaries. The value is
passed to `git fetch` and `git clone`.
M
Mark Pundsack 已提交
4090

E
Evan Read 已提交
4091
NOTE: **Note:**
4092 4093
If you use a depth of 1 and have a queue of jobs or retry
jobs, jobs may fail.
M
Mark Pundsack 已提交
4094

4095 4096
Since Git fetching and cloning is based on a ref, such as a branch name, Runners
can't clone a specific commit SHA. If there are multiple jobs in the queue, or
4097
you're retrying an old job, the commit to be tested needs to be within the
4098
Git history that is cloned. Setting too small a value for `GIT_DEPTH` can make
M
Mark Pundsack 已提交
4099
it impossible to run these old commits. You will see `unresolved reference` in
4100
job logs. You should then reconsider changing `GIT_DEPTH` to a higher value.
M
Mark Pundsack 已提交
4101

4102 4103
Jobs that rely on `git describe` may not work correctly when `GIT_DEPTH` is
set since only part of the Git history is present.
M
Mark Pundsack 已提交
4104 4105

To fetch or clone only the last 3 commits:
4106 4107

```yaml
M
Mark Pundsack 已提交
4108
variables:
M
Mark Pundsack 已提交
4109
  GIT_DEPTH: "3"
M
Mark Pundsack 已提交
4110 4111
```

4112 4113
You can set it globally or per-job in the [`variables`](#variables) section.

4114
### Custom build directories
4115

4116
> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2211) in GitLab Runner 11.10
4117 4118 4119 4120 4121 4122

NOTE: **Note:**
This can only be used when `custom_build_dir` is enabled in the [Runner's
configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section).
This is the default configuration for `docker` and `kubernetes` executor.

E
Evan Read 已提交
4123 4124 4125
By default, GitLab Runner clones the repository in a unique subpath of the
`$CI_BUILDS_DIR` directory. However, your project might require the code in a
specific directory (Go projects, for example). In that case, you can specify
A
Anthony Mastrean 已提交
4126 4127
the `GIT_CLONE_PATH` variable to tell the Runner in which directory to clone the
repository:
4128

4129
```yaml
4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141
variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name

test:
  script:
    - pwd
```

The `GIT_CLONE_PATH` has to always be within `$CI_BUILDS_DIR`. The directory set in `$CI_BUILDS_DIR`
is dependent on executor and configuration of [runners.builds_dir](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section)
setting.

4142
#### Handling concurrency
4143 4144 4145 4146

An executor using a concurrency greater than `1` might lead
to failures because multiple jobs might be working on the same directory if the `builds_dir`
is shared between jobs.
4147
GitLab Runner does not try to prevent this situation. It's up to the administrator
4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158
and developers to comply with the requirements of Runner configuration.

To avoid this scenario, you can use a unique path within `$CI_BUILDS_DIR`, because Runner
exposes two additional variables that provide a unique `ID` of concurrency:

- `$CI_CONCURRENT_ID`: Unique ID for all jobs running within the given executor.
- `$CI_CONCURRENT_PROJECT_ID`: Unique ID for all jobs running within the given executor and project.

The most stable configuration that should work well in any scenario and on any executor
is to use `$CI_CONCURRENT_ID` in the `GIT_CLONE_PATH`. For example:

4159
```yaml
4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170
variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name

test:
  script:
    - pwd
```

The `$CI_CONCURRENT_PROJECT_ID` should be used in conjunction with `$CI_PROJECT_PATH`
as the `$CI_PROJECT_PATH` provides a path of a repository. That is, `group/subgroup/project`. For example:

4171
```yaml
4172 4173 4174 4175 4176 4177 4178 4179
variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH

test:
  script:
    - pwd
```

4180
#### Nested paths
4181 4182

The value of `GIT_CLONE_PATH` is expanded once and nesting variables
4183
within is not supported.
4184 4185 4186 4187

For example, you define both the variables below in your
`.gitlab-ci.yml` file:

4188
```yaml
4189 4190 4191 4192 4193 4194 4195
variables:
  GOPATH: $CI_BUILDS_DIR/go
  GIT_CLONE_PATH: $GOPATH/src/namespace/project
```

The value of `GIT_CLONE_PATH` is expanded once into
`$CI_BUILDS_DIR/go/src/namespace/project`, and results in failure
4196
because `$CI_BUILDS_DIR` is not expanded.
4197

4198 4199 4200 4201 4202 4203 4204 4205
## Special YAML features

It's possible to use special YAML features like anchors (`&`), aliases (`*`)
and map merging (`<<`), which will allow you to greatly reduce the complexity
of `.gitlab-ci.yml`.

Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/).

4206 4207 4208 4209
In most cases, the [`extends` keyword](#extends) is more user friendly and should
be used over these special YAML features. YAML anchors may still
need to be used to merge arrays.

4210 4211
### Anchors

4212
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
4213

4214
YAML has a handy feature called 'anchors', which lets you easily duplicate
4215
content across your document. Anchors can be used to duplicate/inherit
4216
properties, and is a perfect example to be used with [hidden jobs](#hide-jobs)
4217 4218
to provide templates for your jobs. When there is duplicate keys, GitLab will
perform a reverse deep merge based on the keys.
4219 4220 4221 4222

The following example uses anchors and map merging. It will create two jobs,
`test1` and `test2`, that will inherit the parameters of `.job_template`, each
having their own custom `script` defined:
4223 4224

```yaml
4225
.job_template: &job_definition  # Hidden key that defines an anchor named 'job_definition'
4226
  image: ruby:2.6
4227 4228 4229 4230 4231
  services:
    - postgres
    - redis

test1:
4232
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
4233
  script:
4234
    - test1 project
4235 4236

test2:
4237
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
4238
  script:
4239 4240 4241 4242 4243 4244 4245 4246 4247
    - test2 project
```

`&` sets up the name of the anchor (`job_definition`), `<<` means "merge the
given hash into the current one", and `*` includes the named anchor
(`job_definition` again). The expanded version looks like this:

```yaml
.job_template:
4248
  image: ruby:2.6
4249 4250 4251 4252 4253
  services:
    - postgres
    - redis

test1:
4254
  image: ruby:2.6
4255 4256 4257 4258 4259 4260 4261
  services:
    - postgres
    - redis
  script:
    - test1 project

test2:
4262
  image: ruby:2.6
4263 4264 4265 4266 4267
  services:
    - postgres
    - redis
  script:
    - test2 project
4268 4269
```

4270 4271 4272 4273
Let's see another one example. This time we will use anchors to define two sets
of services. This will create two jobs, `test:postgres` and `test:mysql`, that
will share the `script` directive defined in `.job_template`, and the `services`
directive defined in `.postgres_services` and `.mysql_services` respectively:
4274 4275 4276 4277 4278

```yaml
.job_template: &job_definition
  script:
    - test project
4279 4280
  tags:
    - dev
4281 4282 4283 4284 4285 4286

.postgres_services:
  services: &postgres_definition
    - postgres
    - ruby

4287
.mysql_services:
4288 4289 4290 4291 4292
  services: &mysql_definition
    - mysql
    - ruby

test:postgres:
A
Achilleas Pipinellis 已提交
4293
  <<: *job_definition
4294
  services: *postgres_definition
4295 4296
  tags:
    - postgres
4297 4298

test:mysql:
A
Achilleas Pipinellis 已提交
4299
  <<: *job_definition
4300 4301 4302
  services: *mysql_definition
```

4303
The expanded version looks like this:
4304

4305 4306 4307 4308
```yaml
.job_template:
  script:
    - test project
4309 4310
  tags:
    - dev
4311

4312 4313 4314 4315
.postgres_services:
  services:
    - postgres
    - ruby
4316

4317 4318 4319 4320 4321 4322
.mysql_services:
  services:
    - mysql
    - ruby

test:postgres:
4323
  script:
4324 4325 4326 4327
    - test project
  services:
    - postgres
    - ruby
4328 4329
  tags:
    - postgres
4330 4331 4332 4333 4334 4335 4336

test:mysql:
  script:
    - test project
  services:
    - mysql
    - ruby
4337 4338
  tags:
    - dev
4339 4340
```

4341
You can see that the hidden jobs are conveniently used as templates.
4342

4343 4344 4345
NOTE: **Note:**
Note that `tags: [dev]` has been overwritten by `tags: [postgres]`.

4346 4347
NOTE: **Note:**
You can't use YAML anchors across multiple files when leveraging the [`include`](#include)
4348 4349
feature. Anchors are only valid within the file they were defined in. Instead
of using YAML anchors, you can use the [`extends` keyword](#extends).
4350

4351 4352
#### YAML anchors for `before_script` and `after_script`

4353
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23005) in GitLab 12.5.
4354 4355 4356 4357 4358 4359 4360 4361 4362

You can use [YAML anchors](#anchors) with `before_script` and `after_script`,
which makes it possible to include a predefined list of commands in multiple
jobs.

Example:

```yaml
.something_before: &something_before
4363
  - echo 'something before'
4364 4365

.something_after: &something_after
4366 4367
  - echo 'something after'
  - echo 'another thing after'
4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379

job_name:
  before_script:
    - *something_before
  script:
    - echo 'this is the script'
  after_script:
    - *something_after
```

#### YAML anchors for `script`

4380
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23005) in GitLab 12.5.
4381 4382 4383 4384 4385 4386 4387 4388

You can use [YAML anchors](#anchors) with scripts, which makes it possible to
include a predefined list of commands in multiple jobs.

For example:

```yaml
.something: &something
4389
  - echo 'something'
4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409

job_name:
  script:
    - *something
    - echo 'this is the script'
```

#### YAML anchors for variables

[YAML anchors](#anchors) can be used with `variables`, to easily repeat assignment
of variables across multiple jobs. It can also enable more flexibility when a job
requires a specific `variables` block that would otherwise override the global variables.

In the example below, we will override the `GIT_STRATEGY` variable without affecting
the use of the `SAMPLE_VARIABLE` variable:

```yaml
# global variables
variables: &global-variables
  SAMPLE_VARIABLE: sample_variable_value
4410
  ANOTHER_SAMPLE_VARIABLE: another_sample_variable_value
4411 4412 4413 4414 4415 4416 4417 4418 4419 4420

# a job that needs to 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
```

4421
### Hide jobs
4422

4423 4424 4425 4426
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.

If you want to temporarily 'disable' a job, rather than commenting out all the
lines where the job is defined:
E
Evan Read 已提交
4427

4428 4429 4430 4431 4432
```yaml
#hidden_job:
#  script:
#    - run test
```
4433

4434
You can instead start its name with a dot (`.`) and it won't be processed by
4435 4436 4437 4438 4439 4440 4441 4442 4443
GitLab CI/CD. In the following example, `.hidden_job` will be ignored:

```yaml
.hidden_job:
  script:
    - run test
```

Use this feature to ignore jobs, or use the
4444
[special YAML features](#special-yaml-features) and transform the hidden jobs
4445 4446 4447 4448 4449 4450 4451 4452 4453
into templates.

## Skip Pipeline

If your commit message contains `[ci skip]` or `[skip ci]`, using any
capitalization, the commit will be created but the pipeline will be skipped.

Alternatively, one can pass the `ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd)
if using Git 2.10 or newer.
4454

4455 4456
## Processing Git pushes

4457 4458
GitLab will create at most 4 branch and tag pipelines when
pushing multiple changes in single `git push` invocation.
4459

4460 4461
This limitation does not affect any of the updated Merge Request pipelines.
All updated Merge Requests will have a pipeline created when using
4462 4463
[pipelines for merge requests](../merge_request_pipelines/index.md).

4464
## Deprecated parameters
4465

4466
The following parameters are deprecated.
4467

4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499
### Globally-defined `types`

CAUTION: **Deprecated:**
`types` is deprecated, and could be removed in a future release.
Use [`stages`](#stages) instead.

### Job-defined `type`

CAUTION: **Deprecated:**
`type` is deprecated, and could be removed in one of the future releases.
Use [`stage`](#stage) instead.

### Globally-defined `image`, `services`, `cache`, `before_script`, `after_script`

Defining `image`, `services`, `cache`, `before_script`, and
`after_script` globally is deprecated. Support could be removed
from a future release.

Use [`default:`](#global-defaults) instead. For example:

```yaml
default:
  image: ruby:2.5
  services:
    - docker:dind
  cache:
    paths: [vendor/]
  before_script:
    - bundle install --path vendor/
  after_script:
    - rm -rf tmp/
```
4500

M
Marcia Ramos 已提交
4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511
<!-- ## Troubleshooting

Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.

Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->