Read about our upcoming Code of Conduct on this issue

README.md 121 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`
Douwe Maan's avatar
Douwe Maan committed
78

Evan Read's avatar
Evan Read committed
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
### 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
103
| [`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
104
105
106
107
108
| [`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`.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
109
| [`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`. |
110
| [`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
111
112
| [`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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
113
| [`timeout`](#timeout)                              | Define a custom job-level timeout that takes precedence over the project-wide setting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
Evan Read's avatar
Evan Read committed
114
115
116
| [`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
117
| [`extends`](#extends)                              | Configuration entries that this job is going to inherit from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
Evan Read's avatar
Evan Read committed
118
119
| [`pages`](#pages)                                  | Upload the result of a job to use with GitLab Pages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [`variables`](#variables)                          | Define job variables on a job level.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
120
| [`interruptible`](#interruptible)                  | Defines if a job can be canceled when made redundant by a newer run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
Evan Read's avatar
Evan Read committed
121
122
123
124

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

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

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

185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
#### 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.

Example:

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

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

Evan Read's avatar
Evan Read committed
204
205
206
207
208
209
### `image`

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

For:

210
- 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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
- 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:

231
- 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
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
- 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
262

263
264
`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).
265
This must be an an array.
266

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

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

273
274
Scripts specified in `after_script` are executed in a new shell, separate from any
`before_script` or `script` scripts. As a result, they:
275
276

- Have a current working directory set back to the default.
277
278
279
280
281
282
- 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`
283
if you set it per-job:
284

285
```yaml
Kamil Trzciński's avatar
Kamil Trzciński committed
286
287
288
default:
  before_script:
    - global before script
289
290
291

job:
  before_script:
pityonline's avatar
pityonline committed
292
    - execute this instead of global before script
293
  script:
pityonline's avatar
pityonline committed
294
    - my command
295
  after_script:
pityonline's avatar
pityonline committed
296
    - execute this after my script
297
298
```

299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
#### 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
326
### `stages`
Douwe Maan's avatar
Douwe Maan committed
327

328
329
330
331
`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.
332
The ordering of elements in `stages` defines the ordering of jobs' execution:
Douwe Maan's avatar
Douwe Maan committed
333

334
335
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
336
   complete successfully.
Douwe Maan's avatar
Douwe Maan committed
337
338

Let's consider the following example, which defines 3 stages:
339
340

```yaml
Douwe Maan's avatar
Douwe Maan committed
341
342
343
344
345
346
stages:
  - build
  - test
  - deploy
```

347
1. First, all jobs of `build` are executed in parallel.
348
349
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.
350
1. If all jobs of `deploy` succeed, the commit is marked as `passed`.
351
352
1. If any of the previous jobs fails, the commit is marked as `failed` and no
   jobs of further stage are executed.
353

354
There are also two edge cases worth mentioning:
355

356
357
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
358
1. If a job doesn't specify a `stage`, the job is assigned the `test` stage.
359

360
361
362
363
364
365
366
367
368
369
370
#### `.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`.

371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
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
402
### `stage`
403

404
405
`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
406
`stage` are executed in parallel (subject to [certain conditions](#using-your-own-runners)). For example:
Douwe Maan's avatar
Douwe Maan committed
407
408

```yaml
409
410
411
412
413
stages:
  - build
  - test
  - deploy

414
415
416
417
job 0:
  stage: .pre
  script: make something useful before build stage

418
419
420
421
422
423
424
425
426
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
427
  stage: test
428
429
430
431
432
  script: make test

job 4:
  stage: deploy
  script: make deploy
433
434
435
436

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

439
440
441
442
443
444
445
446
447
448
449
#### 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
450
### `only`/`except` (basic)
Douwe Maan's avatar
Douwe Maan committed
451

452
453
454
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.

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

458
1. `only` defines the names of branches and tags for which the job will run.
Evan Read's avatar
Evan Read committed
459
1. `except` defines the names of branches and tags for which the job will
460
    **not** run.
461

462
There are a few rules that apply to the usage of job policy:
463

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

470
471
472
473
In addition, `only` and `except` allow the use of special keywords:

| **Value** |  **Description**  |
| --------- |  ---------------- |
474
475
| `branches`       | When a Git reference of a pipeline is a branch.  |
| `tags`           | When a Git reference of a pipeline is a tag.  |
476
477
478
479
480
481
482
483
| `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)). |
484
| `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)). |
485
| `chat`          | For jobs created using a [GitLab ChatOps](../chatops/README.md) command. |
486

487
In the example below, `job` will run only for refs that start with `issue-`,
488
whereas all branches will be skipped:
Douwe Maan's avatar
Douwe Maan committed
489
490
491

```yaml
job:
492
  # use regexp
Douwe Maan's avatar
Douwe Maan committed
493
  only:
494
495
    - /^issue-.*$/
  # use special keyword
Douwe Maan's avatar
Douwe Maan committed
496
  except:
497
    - branches
Douwe Maan's avatar
Douwe Maan committed
498
499
```

500
501
502
503
504
505
506
507
508
509
510
511
512
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
```

513
In this example, `job` will run only for refs that are tagged, or if a build is
514
explicitly requested via an API trigger or a [Pipeline Schedule][schedules]:
515
516
517
518
519
520
521

```yaml
job:
  # use special keywords
  only:
    - tags
    - triggers
522
    - schedules
523
524
```

525
526
The repository path can be used to have jobs executed only for the parent
repository and not forks:
527
528
529
530

```yaml
job:
  only:
531
    - branches@gitlab-org/gitlab
532
  except:
533
534
    - master@gitlab-org/gitlab
    - /^release/.*$/@gitlab-org/gitlab
535
```
536

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

540
541
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.
542
543
544
545
546
547
548
549

For example,

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

550
is translated to:
551
552
553
554
555
556
557

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

558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
#### 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`.

580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
### 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
601
### `only`/`except` (advanced)
602

603
CAUTION: **Warning:**
otuhs_d's avatar
otuhs_d committed
604
This is an _alpha_ feature, and it is subject to change at any time without
605
prior notice!
606

607
608
GitLab supports both simple and complex strategies, so it's possible to use an
array and a hash configuration scheme.
609

610
Four keys are available:
611

612
613
614
615
- `refs`
- `variables`
- `changes`
- `kubernetes`
616

617
618
619
620
621
622
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
623
With `only`, individual keys are logically joined by an AND:
624

625
> (any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active)
626

627
628
`except` is implemented as a negation of this complete expression:

629
> NOT((any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active))
630
631
632

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

633
> (any of refs) OR (any of variables) OR (any of changes) OR (if Kubernetes is active)
634

Evan Read's avatar
Evan Read committed
635
#### `only:refs`/`except:refs`
636

637
638
> `refs` policy introduced in GitLab 10.0.

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

642
643
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:
644
645

```yaml
646
deploy:
647
648
649
650
  only:
    refs:
      - master
      - schedules
651
652
```

Evan Read's avatar
Evan Read committed
653
#### `only:kubernetes`/`except:kubernetes`
654

655
656
> `kubernetes` policy introduced in GitLab 10.0.

657
658
659
660
661
662
663
664
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:
665
666
667
    kubernetes: active
```

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

670
671
> `variables` policy introduced in GitLab 10.7.

672
673
674
675
676
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.

677
Examples of using variables expressions:
678
679
680

```yaml
deploy:
681
  script: cap staging deploy
682
683
684
685
686
687
688
689
  only:
    refs:
      - branches
    variables:
      - $RELEASE == "staging"
      - $STAGING
```

690
Another use case is excluding jobs depending on a commit message:
691
692
693
694
695
696
697
698
699

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

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

Evan Read's avatar
Evan Read committed
702
#### `only:changes`/`except:changes`
703

704
705
> `changes` policy [introduced][ce-19232] in GitLab 11.4.

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

For example:
710
711
712
713
714
715
716
717

```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
718
      - dockerfiles/**/*
719
      - more_scripts/*.{rb,py,sh}
720
721
```

722
723
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
724
commits contains changes to any of the following:
725
726
727

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

731
732
733
734
735
736
737
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:
738
739
740
741
742
743
744
745
746
747

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

748
749
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:
750
751
752
753
754
755
756
757
758

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

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

763
##### Using `only:changes` with pipelines for merge requests
764
765

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

769
770
771
772
773
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.

774
775
For example:

776
```yaml
777
778
779
780
781
782
783
784
785
786
docker build service one:
  script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG .
  only:
    refs:
      - merge_requests
    changes:
      - Dockerfile
      - service-one/**/*
```

787
788
789
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.
790

791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
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.

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.

827
828
### `rules`

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

`rules` allows for a list of individual rule objects to be evaluated
832
833
834
835
*in order*, until one matches and dynamically provides attributes to the job.

Available rule clauses include:

Evan Read's avatar
Evan Read committed
836
837
838
839
- [`if`](#rulesif)
  (similar to [`only:variables`](#onlyvariablesexceptvariables)).
- [`changes`](#ruleschanges)
  (same as [`only:changes`](#onlychangesexceptchanges)).
840
- [`exists`](#rulesexists)
841

Evan Read's avatar
Evan Read committed
842
843
844
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:
845
846
847
848
849

```yaml
job:
  script: "echo Hello, Rules!"
  rules:
850
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'
851
      when: always
Evan Read's avatar
Evan Read committed
852
    - if: '$VAR =~ /pattern/'
853
      when: manual
Evan Read's avatar
Evan Read committed
854
    - when: on_success
855
856
```

Evan Read's avatar
Evan Read committed
857
858
859
860
861
862
863
864
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.
865
866
867
868
869
870
871
872
873
874
875

#### `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:
876
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' # This rule will be evaluated
877
      when: always
878
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/' # This rule will only be evaluated if the target branch is not "master"
879
      when: manual
880
    - 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
881
882
883
884
885
886
887
888
889
890
```

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
891
892
893
accepting an array of paths.

For example:
894
895
896
897
898
899
900
901
902
903
904
905
906
907

```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
908
909
910
911
912
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.

913
914
#### `rules:exists`

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

917
918
919
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
945
946
`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
947
#### Complex rule clauses
948

949
950
To conjoin `if`, `changes`, and `exists` clauses with an AND, use them in the
same rule.
Evan Read's avatar
Evan Read committed
951
952
953
954
955
956

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.
957
958
959
960
961
962
963
964
965
966
967
968
969

```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
970
971
972
973
The only clauses currently available are:

- `if`
- `changes`
974
- `exists`
Evan Read's avatar
Evan Read committed
975
976
977
978

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.
979
980
981

#### Permitted attributes

Evan Read's avatar
Evan Read committed
982
983
984
985
986
987
988
The only job attributes currently set by `rules` are:

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

A job will be included in a pipeline if `when` is evaluated to any value
except `never`.
989

Evan Read's avatar
Evan Read committed
990
991
Delayed jobs require a `start_in` value, so rule objects do as well. For
example:
992
993
994
995
996
997
998
999
1000
1001
1002
1003

```yaml
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - changes: # Will include the job and delay 3 hours when the Dockerfile has changed
      - Dockerfile
      when: delayed
      start_in: '3 hours'
    - when: on_success # Otherwise include the job and set to run normally
```

Evan Read's avatar
Evan Read committed
1004
1005
Additional job configuration may be added to rules in the future. If something
useful isn't available, please
1006
[open an issue](https://gitlab.com/gitlab-org/gitlab/issues).
1007

Evan Read's avatar
Evan Read committed
1008
### `tags`
Douwe Maan's avatar
Douwe Maan committed
1009

1010
`tags` is used to select specific Runners from the list of all Runners that are
1011
allowed to run this project.
Douwe Maan's avatar
Douwe Maan committed
1012

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

1016
`tags` allow you to run jobs with Runners that have the specified tags
1017
1018
1019
assigned to them:

```yaml
Douwe Maan's avatar
Douwe Maan committed
1020
1021
1022
1023
1024
1025
job:
  tags:
    - ruby
    - postgres
```

1026
The specification above, will make sure that `job` is built by a Runner that
1027
has both `ruby` AND `postgres` tags defined.
Douwe Maan's avatar
Douwe Maan committed
1028

1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
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:

```yaml
windows job:
  stage:
    - build
  tags:
    - windows
  script:
    - echo Hello, %USERNAME%!

osx job:
  stage:
    - build
  tags:
    - osx
  script:
    - echo "Hello, $USER!"
```

Evan Read's avatar
Evan Read committed
1051
### `allow_failure`
1052

1053
1054
`allow_failure` allows a job to fail without impacting the rest of the CI
suite.
1055
The default value is `false`, except for [manual](#whenmanual) jobs.
1056

1057
1058
1059
1060
1061
1062
1063
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.

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.
1064
1065
1066
1067
1068
1069
1070
1071
1072

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

```yaml
job1:
  stage: test
  script:
pityonline's avatar
pityonline committed
1073
    - execute_script_that_will_fail
1074
1075
1076
1077
1078
  allow_failure: true

job2:
  stage: test
  script:
pityonline's avatar
pityonline committed
1079
    - execute_script_that_will_succeed
1080
1081
1082
1083

job3:
  stage: deploy
  script:
pityonline's avatar
pityonline committed
1084
    - deploy_to_staging
1085
1086
```

Evan Read's avatar
Evan Read committed
1087
### `when`
1088
1089
1090

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

Robert Speicher's avatar
Robert Speicher committed
1092
1093
`when` can be set to one of the following values:

1094
1. `on_success` - execute job only when all jobs from prior stages
1095
1096
    succeed (or are considered succeeding because they are marked
    `allow_failure`). This is the default.
1097
1. `on_failure` - execute job only when at least one job from prior stages
1098
    fails.
1099
1100
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
1101
    [manual actions](#whenmanual) below.
1102

1103
1104
1105
For example:

```yaml
1106
stages:
pityonline's avatar
pityonline committed
1107
1108
1109
1110
1111
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup
1112

1113
build_job:
1114
1115
  stage: build
  script:
pityonline's avatar
pityonline committed
1116
    - make build
1117

1118
cleanup_build_job:
1119
1120
  stage: cleanup_build
  script:
pityonline's avatar
pityonline committed
1121
    - cleanup build when failed
1122
1123
  when: on_failure

1124
test_job:
1125
1126
  stage: test
  script:
pityonline's avatar
pityonline committed
1127
    - make test
1128

1129
deploy_job:
1130
1131
  stage: deploy
  script:
pityonline's avatar
pityonline committed
1132
    - make deploy
1133
  when: manual
1134

1135
cleanup_job:
1136
1137
  stage: cleanup
  script:
pityonline's avatar
pityonline committed
1138
    - cleanup after jobs
1139
1140
1141
1142
  when: always
```

The above script will:
1143

1144
1. Execute `cleanup_build_job` only when `build_job` fails.
Evan Read's avatar
Evan Read committed
1145
1. Always execute `cleanup_job` as the last step in pipeline regardless of
1146
   success or failure.
Evan Read's avatar
Evan Read committed
1147
1. Allow you to manually execute `deploy_job` from GitLab's UI.
1148

Evan Read's avatar
Evan Read committed
1149
#### `when:manual`
1150

1151
1152
1153
> - Introduced in GitLab 8.10.
> - Blocking manual actions were introduced in GitLab 9.0.
> - Protected actions were introduced in GitLab 9.2.
1154

1155
1156
1157
1158
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
1159
[environments documentation](../environments.md#configuring-manual-deployments).
1160

1161
1162
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
1163
possible to resume execution of the pipeline when someone executes a blocking
1164
manual action by clicking a _play_ button.
1165

1166
When a pipeline is blocked, it will not be merged if Merge When Pipeline Succeeds
1167
1168
1169
1170
1171
is set. Blocked pipelines also do have a special status, called _manual_.
Manual actions are non-blocking by default. If you want to make manual action
blocking, it is necessary to add `allow_failure: false` to the job's definition
in `.gitlab-ci.yml`.

1172
1173
1174
Optional manual actions have `allow_failure: true` set by default and their
Statuses do not contribute to the overall pipeline status. So, if a manual
action fails, the pipeline will eventually succeed.
1175

1176
1177
Manual actions are considered to be write actions, so permissions for
[protected branches](../../user/project/protected_branches.md) are used when
Brendan O'Leary 🐢's avatar
Brendan O'Leary 🐢 committed
1178
1179
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
1180
have the ability to merge to this branch. It is possible to use protected environments
1181
to more strictly [protect manual deployments](#protecting-manual-jobs-premium) from being
1182
run by unauthorized users.
1183

1184
1185
1186
1187
1188
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.

1189
##### Protecting manual jobs **(PREMIUM)**
1190
1191
1192
1193
1194
1195

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
users associated with a protected environment to trigger manual jobs, it is possible
to implement some special use cases, such as:

1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
- More precisely limiting who can deploy to an environment.
- Enabling a pipeline to be blocked until an approved user "approves" it.

To do this, you must:

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

   ```yaml
   deploy_prod:
     stage: deploy
     script:
       - echo "Deploy to production server"
     environment:
       name: production
       url: https://example.com
     when: manual
     only:
       - master
   ```

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.
1221
1222
1223
1224
1225
1226

Additionally, if a manual job is defined as blocking by adding `allow_failure: false`,
the next stages of the pipeline will not run until the manual job is triggered. This
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.

Evan Read's avatar
Evan Read committed
1227
#### `when:delayed`
1228

1229
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/21767) in GitLab 11.4.
1230
1231
1232
1233
1234

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

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
1235
provided. `start_in` key must be less than or equal to one hour. Examples of valid values include:
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260

- `10 seconds`
- `30 minutes`
- `1 hour`

When there is a delayed job in a stage, the pipeline will not progress until the delayed job has finished.
This means this keyword can also be used for inserting delays between different stages.

The timer of a delayed job starts immediately after the previous stage has completed.
Similar to other types of jobs, a delayed job's timer will not start unless the previous stage passed.

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

```yaml
timed rollout 10%:
  stage: deploy
  script: echo 'Rolling out 10% ...'
  when: delayed
  start_in: 30 minutes
```

You can stop the active timer of a delayed job by clicking the **Unschedule** button.
This job will never be executed in the future unless you execute the job manually.

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

Evan Read's avatar
Evan Read committed
1263
### `environment`
1264

1265
1266
1267
> - Introduced in GitLab 8.9.
> - You can read more about environments and find more examples in the
>   [documentation about environments][environment].
1268

1269
`environment` is used to define that a job deploys to a specific environment.
Mark Pundsack's avatar
Mark Pundsack committed
1270
1271
If `environment` is specified and no environment under that name exists, a new
one will be created automatically.
1272

1273
In its simplest form, the `environment` keyword can be defined like:
1274

1275
```yaml
1276
1277
1278
deploy to production:
  stage: deploy
  script: git push production HEAD:master
1279
1280
  environment:
    name: production
1281
1282
```

1283
1284
1285
In the above example, the `deploy to production` job will be marked as doing a
deployment to the `production` environment.

Evan Read's avatar
Evan Read committed
1286
#### `environment:name`
1287

1288
1289
1290
1291
1292
1293
1294
> - 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).
>   You however cannot use variables defined under `script`.
1295

1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
The `environment` name can contain:

- letters
- digits
- spaces
- `-`
- `_`
- `/`
- `$`
- `{`
- `}`

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

1311
1312