README.md 127 KB
Newer Older
Marcia Ramos's avatar
Marcia Ramos committed
1
2
3
4
---
type: reference
---

Evan Read's avatar
Evan Read committed
5
# GitLab CI/CD Pipeline Configuration Reference
Douwe Maan's avatar
Douwe Maan committed
6

Evan Read's avatar
Evan Read committed
7
GitLab CI/CD [pipelines](../pipelines.md) are configured using a YAML file called `.gitlab-ci.yml` within each project.
8

Evan Read's avatar
Evan Read committed
9
The `.gitlab-ci.yml` file defines the structure and order of the pipelines and determines:
10

Evan Read's avatar
Evan Read committed
11
12
13
14
15
16
17
18
19
20
21
22
- 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:

- For a quick introduction to GitLab CI, follow our [quick start guide](../quick_start/README.md).
- For a collection of examples, see [GitLab CI/CD Examples](../examples/README.md).
23
- 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).
24

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

Evan Read's avatar
Evan Read committed
30
31
32
## Introduction

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

Evan Read's avatar
Evan Read committed
34
35
36
37
38
39
40
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:
Douwe Maan's avatar
Douwe Maan committed
41
42
43
44
45
46
47
48
49

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

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

50
The above example is the simplest possible CI/CD configuration with two separate
51
52
53
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.
Douwe Maan's avatar
Douwe Maan committed
54

55
56
57
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.
Douwe Maan's avatar
Douwe Maan committed
58

59
### Validate the `.gitlab-ci.yml`
Evan Read's avatar
Evan Read committed
60
61
62

Each instance of GitLab CI has an embedded debug tool called Lint, which validates the
content of your `.gitlab-ci.yml` files. You can find the Lint under the page `ci/lint` of your
Marcel Amirault's avatar
Marcel Amirault committed
63
project namespace. For example, `https://gitlab.example.com/gitlab-org/project-123/-/ci/lint`.
Evan Read's avatar
Evan Read committed
64
65
66

### Unavailable names for jobs

67
68
Each job must have a unique name, but there are a few **reserved `keywords` that
cannot be used as job names**:
Douwe Maan's avatar
Douwe Maan committed
69

70
71
72
73
74
75
76
77
- `image`
- `services`
- `stages`
- `types`
- `before_script`
- `after_script`
- `variables`
- `cache`
78
- `include`
Douwe Maan's avatar
Douwe Maan committed
79

Evan Read's avatar
Evan Read committed
80
81
82
83
84
85
86
87
88
89
90
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:

| Keyword                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
|:---------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`script`](#script)                                | Shell script which is executed by Runner.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [`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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [`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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [`stages`](#stages)                                | Define stages in a pipeline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [`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).                                                                                                                                                                                                                                                                                                                                                                                                                                  |
Evan Read's avatar
Evan Read committed
104
| [`rules`](#rules)                                  | List of conditions to evaluate and determine selected attributes of a job, and whether or not it is created. May not be used alongside `only`/`except`.                                                                                                                                                                                                                                                                                                                                                                                                                                |
Evan Read's avatar
Evan Read committed
105
106
107
108
109
| [`tags`](#tags)                                    | List of tags which are used to select Runner.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [`allow_failure`](#allow_failure)                  | Allow job to fail. Failed job doesn't contribute to commit status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [`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`, 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
Evan Read's avatar
Evan Read committed
110
| [`artifacts`](#artifacts)                          | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:expose_as`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, `artifacts:reports`, and `artifacts:reports:junit`.<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_management`, `artifacts:reports:performance` and `artifacts:reports:metrics`. |
111
| [`dependencies`](#dependencies)                    | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
Evan Read's avatar
Evan Read committed
112
113
| [`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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
Evan Read's avatar
Evan Read committed
114
| [`timeout`](#timeout)                              | Define a custom job-level timeout that takes precedence over the project-wide setting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
Evan Read's avatar
Evan Read committed
115
116
117
| [`parallel`](#parallel)                            | How many instances of a job should be run in parallel.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [`trigger`](#trigger-premium)                      | 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
Evan Read's avatar
Evan Read committed
118
| [`extends`](#extends)                              | Configuration entries that this job is going to inherit from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
Evan Read's avatar
Evan Read committed
119
120
| [`pages`](#pages)                                  | Upload the result of a job to use with GitLab Pages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [`variables`](#variables)                          | Define job variables on a job level.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
121
| [`interruptible`](#interruptible)                  | Defines if a job can be canceled when made redundant by a newer run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
Evan Read's avatar
Evan Read committed
122
123
124
125

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

Kamil Trzciński's avatar
Kamil Trzciński committed
126
127
128
129
130
131
132
133
134
135
136
137
## Setting default parameters

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)
138
- [`tags`](#tags)
Kamil Trzciński's avatar
Kamil Trzciński committed
139
- [`cache`](#cache)
140
- [`retry`](#retry)
141
- [`timeout`](#timeout)
142
- [`interruptible`](#interruptible)
Kamil Trzciński's avatar
Kamil Trzciński committed
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

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
```

Evan Read's avatar
Evan Read committed
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
## Parameter details

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

### `script`

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

```yaml
job:
  script: "bundle exec rspec"
```

This parameter can also contain several commands using an array:

```yaml
job:
  script:
    - uname -a
    - bundle exec rspec
```

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:
`:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.

189
190
191
192
193
194
195
196
197
198
199
If any of the script commands return an exit code different from zero, the job
will fail and further commands will not be executed. This behavior can be avoided by
storing the exit code in a variable:

```yaml
job:
  script:
    - false && true; exit_code=$?
    - if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi;
```

200
201
202
203
204
205
206
#### YAML anchors for `script`

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

You can use [YAML anchors](#anchors) with scripts, which makes it possible to
include a predefined list of commands in multiple jobs.

207
For example:
208
209
210
211
212
213
214
215
216
217
218

```yaml
.something: &something
- echo 'something'

job_name:
  script:
    - *something
    - echo 'this is the script'
```

Evan Read's avatar
Evan Read committed
219
220
221
222
223
224
### `image`

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

For:

225
- Simple definition examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml).
Evan Read's avatar
Evan Read committed
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
- Detailed usage information, refer to [Docker integration](../docker/README.md) documentation.

#### `image:name`

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

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

#### `image:entrypoint`

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

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

### `services`

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).

For:

246
- Simple definition examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml).
Evan Read's avatar
Evan Read committed
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
- Detailed usage information, refer to [Docker integration](../docker/README.md) documentation.
- For example services, see [GitLab CI Services](../services/README.md).

#### `services:name`

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

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

#### `services:alias`

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

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

#### `services:entrypoint`

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

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

#### `services:command`

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

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

### `before_script` and `after_script`

> Introduced in GitLab 8.7 and requires GitLab Runner v1.2.
Kamil Trzcinski's avatar
Kamil Trzcinski committed
277

278
279
`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).
Mohammad Mahabadi's avatar
Mohammad Mahabadi committed
280
This must be an array.
281

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

285
`after_script` is used to define the command that will be run after each
Mohammad Mahabadi's avatar
Mohammad Mahabadi committed
286
job, including failed ones. This must be an array.
287

288
289
Scripts specified in `after_script` are executed in a new shell, separate from any
`before_script` or `script` scripts. As a result, they:
290
291

- Have a current working directory set back to the default.
292
293
294
295
296
297
- 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.

It's possible to overwrite a globally defined `before_script` or `after_script`
298
if you set it per-job:
299

300
```yaml
Kamil Trzciński's avatar
Kamil Trzciński committed
301
302
303
default:
  before_script:
    - global before script
304
305
306

job:
  before_script:
pityonline's avatar
pityonline committed
307
    - execute this instead of global before script
308
  script:
pityonline's avatar
pityonline committed
309
    - my command
310
  after_script:
pityonline's avatar
pityonline committed
311
    - execute this after my script
312
313
```

314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
#### YAML anchors for `before_script` and `after_script`

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

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
- echo 'something before'

.something_after: &something_after
- echo 'something after'


job_name:
  before_script:
    - *something_before
  script:
    - echo 'this is the script'
  after_script:
    - *something_after
```

Evan Read's avatar
Evan Read committed
341
### `stages`
Douwe Maan's avatar
Douwe Maan committed
342

343
344
345
346
`stages` is used to define stages that can be used by jobs and is defined
globally.

The specification of `stages` allows for having flexible multi stage pipelines.
347
The ordering of elements in `stages` defines the ordering of jobs' execution:
Douwe Maan's avatar
Douwe Maan committed
348

349
350
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
351
   complete successfully.
Douwe Maan's avatar
Douwe Maan committed
352
353

Let's consider the following example, which defines 3 stages:
354
355

```yaml
Douwe Maan's avatar
Douwe Maan committed
356
357
358
359
360
361
stages:
  - build
  - test
  - deploy
```

362
1. First, all jobs of `build` are executed in parallel.
363
364
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.
365
1. If all jobs of `deploy` succeed, the commit is marked as `passed`.
366
367
1. If any of the previous jobs fails, the commit is marked as `failed` and no
   jobs of further stage are executed.
368

369
There are also two edge cases worth mentioning:
370

371
372
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.
Evan Read's avatar
Evan Read committed
373
1. If a job doesn't specify a `stage`, the job is assigned the `test` stage.
374

375
376
377
378
379
380
381
382
383
384
385
#### `.pre` and `.post`

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

The following stages are available to every pipeline:

- `.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.

User-defined stages are executed after `.pre` and before `.post`.

386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
The order of `.pre` and `.post` cannot be changed, even if defined out of order in `.gitlab-ci.yml`.
For example, the following are equivalent configuration:

- Configured in order:

  ```yml
  stages:
    - .pre
    - a
    - b
    - .post
  ```

- Configured out of order:

  ```yml
  stages:
    - a
    - .pre
    - b
    - .post
  ```

- Not explicitly configured:

  ```yml
  stages:
    - a
    - b
  ```

Evan Read's avatar
Evan Read committed
417
### `stage`
418

419
420
`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
421
`stage` are executed in parallel (subject to [certain conditions](#using-your-own-runners)). For example:
Douwe Maan's avatar
Douwe Maan committed
422
423

```yaml
424
425
426
427
428
stages:
  - build
  - test
  - deploy

429
430
431
432
job 0:
  stage: .pre
  script: make something useful before build stage

433
434
435
436
437
438
439
440
441
job 1:
  stage: build
  script: make build dependencies

job 2:
  stage: build
  script: make build artifacts

job 3:
Douwe Maan's avatar
Douwe Maan committed
442
  stage: test
443
444
445
446
447
  script: make test

job 4:
  stage: deploy
  script: make deploy
448
449
450
451

job 5:
  stage: .post
  script: make something useful at the end of pipeline
Douwe Maan's avatar
Douwe Maan committed
452
453
```

454
455
456
457
458
459
460
461
462
463
464
#### Using your own Runners

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).

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

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

Evan Read's avatar
Evan Read committed
465
### `only`/`except` (basic)
Douwe Maan's avatar
Douwe Maan committed
466

467
468
469
NOTE: **Note:**
These parameters will soon be [deprecated](https://gitlab.com/gitlab-org/gitlab/issues/27449) in favor of [`rules`](#rules) as it offers a more powerful syntax.

470
471
`only` and `except` are two parameters that set a job policy to limit when
jobs are created:
Douwe Maan's avatar
Douwe Maan committed
472

473
1. `only` defines the names of branches and tags for which the job will run.
Evan Read's avatar
Evan Read committed
474
1. `except` defines the names of branches and tags for which the job will
475
    **not** run.
476

477
There are a few rules that apply to the usage of job policy:
478

479
- `only` and `except` are inclusive. If both `only` and `except` are defined
480
   in a job specification, the ref is filtered by `only` and `except`.
Cody Mize's avatar
Cody Mize committed
481
- `only` and `except` allow the use of regular expressions ([supported regexp syntax](#supported-onlyexcept-regexp-syntax)).
482
- `only` and `except` allow to specify a repository path to filter jobs for
483
484
   forks.

485
486
487
488
In addition, `only` and `except` allow the use of special keywords:

| **Value** |  **Description**  |
| --------- |  ---------------- |
489
490
| `branches`       | When a Git reference of a pipeline is a branch.  |
| `tags`           | When a Git reference of a pipeline is a tag.  |
491
492
493
494
495
496
497
498
| `api`            | When pipeline has been triggered by a second pipelines API (not triggers API).  |
| `external`       | When using CI services other than GitLab. |
| `pipelines`      | For multi-project triggers, created using the API with `CI_JOB_TOKEN`. |
| `pushes`         | Pipeline is triggered by a `git push` by the user. |
| `schedules`      | For [scheduled pipelines][schedules]. |
| `triggers`       | For pipelines created using a trigger token. |
| `web`            | For pipelines created using **Run pipeline** button in GitLab UI (under your project's **Pipelines**). |
| `merge_requests` | When a merge request is created or updated (See [pipelines for merge requests](../merge_request_pipelines/index.md)). |
499
| `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)). |
500
| `chat`          | For jobs created using a [GitLab ChatOps](../chatops/README.md) command. |
501

502
In the example below, `job` will run only for refs that start with `issue-`,
503
whereas all branches will be skipped:
Douwe Maan's avatar
Douwe Maan committed
504
505
506

```yaml
job:
507
  # use regexp
Douwe Maan's avatar
Douwe Maan committed
508
  only:
509
510
    - /^issue-.*$/
  # use special keyword
Douwe Maan's avatar
Douwe Maan committed
511
  except:
512
    - branches
Douwe Maan's avatar
Douwe Maan committed
513
514
```

515
516
517
518
519
520
521
522
523
524
525
526
527
Pattern matching is case-sensitive by default. Use `i` flag modifier, like
`/pattern/i` to make a pattern case-insensitive:

```yaml
job:
  # use regexp
  only:
    - /^issue-.*$/i
  # use special keyword
  except:
    - branches
```

528
In this example, `job` will run only for refs that are tagged, or if a build is
529
explicitly requested via an API trigger or a [Pipeline Schedule][schedules]:
530
531
532
533
534
535
536

```yaml
job:
  # use special keywords
  only:
    - tags
    - triggers
537
    - schedules
538
539
```

540
541
The repository path can be used to have jobs executed only for the parent
repository and not forks:
542
543
544
545

```yaml
job:
  only:
546
    - branches@gitlab-org/gitlab
547
  except:
548
549
    - master@gitlab-org/gitlab
    - /^release/.*$/@gitlab-org/gitlab
550
```
551

552
The above example will run `job` for all branches on `gitlab-org/gitlab`,
553
except `master` and those with names prefixed with `release/`.
554

555
556
If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by
default. If it doesn't have an `except` rule, it is empty.
557
558
559
560
561
562
563
564

For example,

```yaml
job:
  script: echo 'test'
```

565
is translated to:
566
567
568
569
570
571
572

```yaml
job:
  script: echo 'test'
  only: ['branches', 'tags']
```

573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
#### Regular expressions

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`.

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

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-`.

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`.

595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
### Supported `only`/`except` regexp syntax

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

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).

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.

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.

```ruby
Feature.enable(:allow_unsafe_ruby_regexp)
```

Evan Read's avatar
Evan Read committed
616
### `only`/`except` (advanced)
617

618
CAUTION: **Warning:**
otuhs_d's avatar
otuhs_d committed
619
This is an _alpha_ feature, and it is subject to change at any time without
620
prior notice!
621

622
623
GitLab supports both simple and complex strategies, so it's possible to use an
array and a hash configuration scheme.
624

625
Four keys are available:
626

627
628
629
630
- `refs`
- `variables`
- `changes`
- `kubernetes`
631

632
633
634
635
636
637
If you use multiple keys under `only` or `except`, the keys will be evaluated as a
single conjoined expression. That is:

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

Evan Read's avatar
Evan Read committed
638
With `only`, individual keys are logically joined by an AND:
639

640
> (any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active)
641

642
643
`except` is implemented as a negation of this complete expression:

644
> NOT((any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active))
645
646
647

This, more intuitively, means the keys join by an OR. A functionally equivalent expression:

648
> (any of refs) OR (any of variables) OR (any of changes) OR (if Kubernetes is active)
649

Evan Read's avatar
Evan Read committed
650
#### `only:refs`/`except:refs`
651

652
653
> `refs` policy introduced in GitLab 10.0.

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

657
658
In the example below, the `deploy` job is going to be created only when the
pipeline has been [scheduled][schedules] or runs for the `master` branch:
659
660

```yaml
661
deploy:
662
663
664
665
  only:
    refs:
      - master
      - schedules
666
667
```

Evan Read's avatar
Evan Read committed
668
#### `only:kubernetes`/`except:kubernetes`
669

670
671
> `kubernetes` policy introduced in GitLab 10.0.

672
673
674
675
676
677
678
679
The `kubernetes` strategy accepts only the `active` keyword.

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

```yaml
deploy:
  only:
680
681
682
    kubernetes: active
```

Evan Read's avatar
Evan Read committed
683
#### `only:variables`/`except:variables`
684

685
686
> `variables` policy introduced in GitLab 10.7.

687
688
689
690
691
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.

692
Examples of using variables expressions:
693
694
695

```yaml
deploy:
696
  script: cap staging deploy
697
698
699
700
701
702
703
704
  only:
    refs:
      - branches
    variables:
      - $RELEASE == "staging"
      - $STAGING
```

705
Another use case is excluding jobs depending on a commit message:
706
707
708
709
710
711
712
713
714

```yaml
end-to-end:
  script: rake test:end-to-end
  except:
    variables:
      - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/
```

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

Evan Read's avatar
Evan Read committed
717
#### `only:changes`/`except:changes`
718

719
720
> `changes` policy [introduced][ce-19232] in GitLab 11.4.

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

For example:
725
726
727
728
729
730
731
732

```yaml
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  only:
    changes:
      - Dockerfile
      - docker/scripts/*
Lukas Schneider's avatar
Lukas Schneider committed
733
      - dockerfiles/**/*
734
      - more_scripts/*.{rb,py,sh}
735
736
```

737
738
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
739
commits contains changes to any of the following:
740
741
742

- The `Dockerfile` file.
- Any of the files inside `docker/scripts/` directory.
743
744
- Any of the files and subdirectories inside the `dockerfiles` directory.
- Any of the files with `rb`, `py`, `sh` extensions inside the `more_scripts` directory.
745

746
747
748
749
750
751
752
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),
undesired behavior could result if you do not [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests).

You can also use glob patterns to match multiple files in either the root directory
of the repo, or in _any_ directory within the repo, but they must be wrapped
in double quotes or GitLab will fail to parse the `.gitlab-ci.yml`. For example:
753
754
755
756
757
758
759
760
761
762

```yaml
test:
  script: npm run test
  only:
    changes:
      - "*.json"
      - "**/*.sql"
```

763
764
The following example will skip the `build` job if a change is detected in any file
in the root directory of the repo with a `.md` extension:
765
766
767
768
769
770
771
772
773

```yaml
build:
  script: npm run build
  except:
    changes:
      - "*.md"
```

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

778
##### Using `only:changes` with pipelines for merge requests
779
780

With [pipelines for merge requests](../merge_request_pipelines/index.md),
781
it is possible to define a job to be created based on files modified
782
783
in a merge request.

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

789
790
For example:

791
```yaml
792
793
794
795
796
797
798
799
800
801
docker build service one:
  script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG .
  only:
    refs:
      - merge_requests
    changes:
      - Dockerfile
      - service-one/**/*
```

802
803
804
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.
805

806
Note that if [pipelines for merge requests](../merge_request_pipelines/index.md) is
807
combined with `only: [change]`, but `only: [merge_requests]` is omitted, there could be
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
unwanted behavior.

For example:

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

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,
but includes changes to the `Dockerfile`, and this pipeline could pass because it is only
testing the changes to the `Dockerfile`. GitLab checks the **most recent pipeline**,
that **passed**, and will show the merge request as mergable, despite the earlier
failed pipeline caused by a change that was not yet corrected.

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

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

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:

- 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.

842
843
### `rules`

844
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/29011) in GitLab 12.3.
Evan Read's avatar
Evan Read committed
845
846

`rules` allows for a list of individual rule objects to be evaluated
847
848
849
850
*in order*, until one matches and dynamically provides attributes to the job.

Available rule clauses include:

Evan Read's avatar
Evan Read committed
851
852
853
854
- [`if`](#rulesif)
  (similar to [`only:variables`](#onlyvariablesexceptvariables)).
- [`changes`](#ruleschanges)
  (same as [`only:changes`](#onlychangesexceptchanges)).
James Fargher's avatar
James Fargher committed
855
- [`exists`](#rulesexists)
856

Evan Read's avatar
Evan Read committed
857
858
859
For example, using `if`. This configuration specifies that `job` should be built
and run for every pipeline on merge requests targeting `master`, regardless of
the status of other builds:
860
861
862
863
864

```yaml
job:
  script: "echo Hello, Rules!"
  rules:
865
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'
866
      when: always
Evan Read's avatar
Evan Read committed
867
    - if: '$VAR =~ /pattern/'
868
      when: manual
Evan Read's avatar
Evan Read committed
869
    - when: on_success
870
871
```

Evan Read's avatar
Evan Read committed
872
873
874
875
876
877
878
879
In this example, if the first rule:

- Matches, the job will be given the `when:always` attribute.
- Does not match, the second and third rules will be evaluated sequentially
  until a match is found. That is, the job will be given either the:
  - `when: manual` attribute if the second rule matches.
  - `when: on_success` attribute if the second rule does not match. The third
    rule will always match when reached because it has no conditional clauses.
880
881
882
883
884
885
886
887
888
889
890

#### `rules:if`

`rules:if` differs slightly from `only:variables` by accepting only a single
expression string, rather than an array of them. Any set of expressions to be
evaluated should be conjoined into a single expression using `&&` or `||`. For example:

```yaml
job:
  script: "echo Hello, Rules!"
  rules:
891
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' # This rule will be evaluated
892
      when: always
893
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/' # This rule will only be evaluated if the target branch is not "master"
894
      when: manual
895
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # If neither of the first two match but the simple presence does, we set to "on_success" by default
896
897
898
899
900
901
902
903
904
905
```

If none of the provided rules match, the job will be set to `when:never`, and
not included in the pipeline. If `rules:when` is not included in the configuration
at all, the behavior defaults to `job:when`, which continues to default to
`on_success`.

#### `rules:changes`

`changes` works exactly the same way as [`only`/`except`](#onlychangesexceptchanges),
Evan Read's avatar
Evan Read committed
906
907
908
accepting an array of paths.

For example:
909
910
911
912
913
914
915
916
917
918
919
920
921
922

```yaml
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - changes: # Will include the job and set to when:manual if any of the follow paths match a modified file.
      - Dockerfile
      when: manual
    - if: '$VAR == "string value"'
      when: manual # Will include the job and set to when:manual if the expression evaluates to true, after the `changes:` rule fails to match.
    - when: on_success # If neither of the first rules match, set to on_success

```

Evan Read's avatar
Evan Read committed
923
924
925
926
927
In this example, a job either set to:

- Run manually if `Dockerfile` has changed OR `$VAR == "string value"`.
- `when:on_success` by the last rule, where no earlier clauses evaluate to true.

James Fargher's avatar
James Fargher committed
928
929
#### `rules:exists`

930
931
> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16574) in GitLab 12.4.

James Fargher's avatar
James Fargher committed
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
`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:
      - Dockerfile
```

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:
      - spec/**.rb
```

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.

Evan Read's avatar
Evan Read committed
962
#### Complex rule clauses
963

James Fargher's avatar
James Fargher committed
964
965
To conjoin `if`, `changes`, and `exists` clauses with an AND, use them in the
same rule.
Evan Read's avatar
Evan Read committed
966
967
968
969
970
971

In the following example:

- We run the job manually if `Dockerfile` or any file in `docker/scripts/`
  has changed AND `$VAR == "string value"`.
- Otherwise, the job will not be included in the pipeline.
972
973
974
975
976
977
978
979
980
981
982
983
984

```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.
      - Dockerfile
      - docker/scripts/*
      when: manual
  # - when: never would be redundant here, this is implied any time rules are listed.
```

Evan Read's avatar
Evan Read committed
985
986
987
988
The only clauses currently available are:

- `if`
- `changes`
James Fargher's avatar
James Fargher committed
989
- `exists`
Evan Read's avatar
Evan Read committed
990
991
992
993

Keywords such as `branches` or `refs` that are currently available for
`only`/`except` are not yet available in `rules` as they are being individually
considered for their usage and behavior in this context.
994
995
996

#### Permitted attributes

Evan Read's avatar
Evan Read committed
997
998
999
1000
The only job attributes currently set by `rules` are:

- `when`.
- `start_in`, if `when` is set to `delayed`.