README.md 103,7 КБ
Newer Older
Marcia Ramos's avatar
Marcia Ramos включено в состав коммита
1
2
3
4
---
type: reference
---

Evan Read's avatar
Evan Read включено в состав коммита
5
# GitLab CI/CD Pipeline Configuration Reference
Douwe Maan's avatar
Douwe Maan включено в состав коммита
6

Evan Read's avatar
Evan Read включено в состав коммита
7
GitLab CI/CD [pipelines](../pipelines.md) are configured using a YAML file called `.gitlab-ci.yml` within each project.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
8

Evan Read's avatar
Evan Read включено в состав коммита
9
The `.gitlab-ci.yml` file defines the structure and order of the pipelines and determines:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
10

Evan Read's avatar
Evan Read включено в состав коммита
11
12
13
14
15
16
17
18
19
20
21
22
23
- What to execute using [GitLab Runner](https://docs.gitlab.com/runner/).
- What decisions to make when specific conditions are encountered. For example, when a process succeeds or fails.

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

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

We have complete examples of configuring pipelines:

- 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).
- To see a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab-ce`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
24

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
25
NOTE: **Note:**
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
26
If you have a [mirrored repository where GitLab pulls from](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter),
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
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 включено в состав коммита
30
31
32
## Introduction

Pipeline configuration begins with jobs. Jobs are the most fundamental element of a `.gitlab-ci.yml` file.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
33

Evan Read's avatar
Evan Read включено в состав коммита
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 включено в состав коммита
41
42
43
44
45
46
47
48
49

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
50
The above example is the simplest possible CI/CD configuration with two separate
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
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 включено в состав коммита
54

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
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 включено в состав коммита
58

Evan Read's avatar
Evan Read включено в состав коммита
59
60
61
62
### Validate the .gitlab-ci.yml

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 включено в состав коммита
63
project namespace. For example, `https://gitlab.example.com/gitlab-org/project-123/-/ci/lint`.
Evan Read's avatar
Evan Read включено в состав коммита
64
65
66

### Unavailable names for jobs

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
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 включено в состав коммита
69

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
70
71
72
73
74
75
76
77
- `image`
- `services`
- `stages`
- `types`
- `before_script`
- `after_script`
- `variables`
- `cache`
Douwe Maan's avatar
Douwe Maan включено в состав коммита
78

Evan Read's avatar
Evan Read включено в состав коммита
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
### 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).                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [`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`.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
108
| [`artifacts`](#artifacts)                          | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `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`. |
Evan Read's avatar
Evan Read включено в состав коммита
109
110
111
112
113
114
| [`dependencies`](#dependencies)                    | Other jobs that a job depends on so that you can pass artifacts between them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [`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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [`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`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
Wolphin's avatar
Wolphin включено в состав коммита
115
| [`extends`](#extends)                              | Configuration entries that this job is going to inherit from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
Evan Read's avatar
Evan Read включено в состав коммита
116
117
118
119
120
121
| [`pages`](#pages)                                  | Upload the result of a job to use with GitLab Pages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [`variables`](#variables)                          | Define job variables on a job level.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

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

Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
## 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)

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 включено в состав коммита
151
152
153
154
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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
## 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:
`:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.

### `image`

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

For:

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

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

- Simple definition examples, see [Define `image` and `services` from .gitlab-ci.yml](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml).
- Detailed usage information, refer to [Docker integration](../docker/README.md) documentation.
- For example services, see [GitLab CI 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 включено в состав коммита
239

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
240
241
242
243
`before_script` is used to define the command that should be run before all
jobs, including deploy jobs, but after the restoration of [artifacts](#artifacts).
This can be an array or a multi-line string.

Jeff Frontz's avatar
Jeff Frontz включено в состав коммита
244
`after_script` is used to define the command that will be run after all
Damian Nowak's avatar
Damian Nowak включено в состав коммита
245
jobs, including failed ones. This has to be an array or a multi-line string.
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
246

Evan Read's avatar
Evan Read включено в состав коммита
247
Scripts specified in `before_script` are:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
248

Evan Read's avatar
Evan Read включено в состав коммита
249
250
251
252
253
- Concatenated with scripts specified in the main `script`. Job-level
  `before_script` definition override global-level `before_script` definition
  when concatenated with `script` definition.
- Executed together with main `script` script as one script in a single shell
  context.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
254

Evan Read's avatar
Evan Read включено в состав коммита
255
Scripts specified in `after_script`:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
256
257

- Have a current working directory set back to the default.
Evan Read's avatar
Evan Read включено в состав коммита
258
259
260
261
262
263
264
265
- Are executed in a shell context separated from `before_script` and `script`
  scripts.
- Because of separated context, cannot see changes done by scripts defined
  in `before_script` or `script` scripts, either:
  - In shell. For example, command aliases and variables exported in `script`
    scripts.
  - Outside of the working tree (depending on the Runner executor). For example,
    software installed by a `before_script` or `script` scripts.
Martin Nowak's avatar
Martin Nowak включено в состав коммита
266

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
267
268
It's possible to overwrite the globally defined `before_script` and `after_script`
if you set it per-job:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
269

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
270
```yaml
Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
271
272
273
default:
  before_script:
    - global before script
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
274
275
276

job:
  before_script:
pityonline's avatar
pityonline включено в состав коммита
277
    - execute this instead of global before script
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
278
  script:
pityonline's avatar
pityonline включено в состав коммита
279
    - my command
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
280
  after_script:
pityonline's avatar
pityonline включено в состав коммита
281
    - execute this after my script
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
282
283
```

Evan Read's avatar
Evan Read включено в состав коммита
284
### `stages`
Douwe Maan's avatar
Douwe Maan включено в состав коммита
285

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
286
287
288
289
`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.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
290
The ordering of elements in `stages` defines the ordering of jobs' execution:
Douwe Maan's avatar
Douwe Maan включено в состав коммита
291

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
292
293
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
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
294
   complete successfully.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
295
296

Let's consider the following example, which defines 3 stages:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
297
298

```yaml
Douwe Maan's avatar
Douwe Maan включено в состав коммита
299
300
301
302
303
304
stages:
  - build
  - test
  - deploy
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
305
1. First, all jobs of `build` are executed in parallel.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
306
307
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.
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
308
1. If all jobs of `deploy` succeed, the commit is marked as `passed`.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
309
310
1. If any of the previous jobs fails, the commit is marked as `failed` and no
   jobs of further stage are executed.
Nick Thomas's avatar
Nick Thomas включено в состав коммита
311

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
312
There are also two edge cases worth mentioning:
Nick Thomas's avatar
Nick Thomas включено в состав коммита
313

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
314
315
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 включено в состав коммита
316
1. If a job doesn't specify a `stage`, the job is assigned the `test` stage.
Nick Thomas's avatar
Nick Thomas включено в состав коммита
317

Evan Read's avatar
Evan Read включено в состав коммита
318
### `stage`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
319

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
320
321
`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
Evan Read's avatar
Evan Read включено в состав коммита
322
`stage` are executed in parallel (subject to [certain conditions](#using-your-own-runners)). For example:
Douwe Maan's avatar
Douwe Maan включено в состав коммита
323
324

```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
325
326
327
328
329
330
331
332
333
334
335
336
337
338
stages:
  - build
  - test
  - deploy

job 1:
  stage: build
  script: make build dependencies

job 2:
  stage: build
  script: make build artifacts

job 3:
Douwe Maan's avatar
Douwe Maan включено в состав коммита
339
  stage: test
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
340
341
342
343
344
  script: make test

job 4:
  stage: deploy
  script: make deploy
Douwe Maan's avatar
Douwe Maan включено в состав коммита
345
346
```

Evan Read's avatar
Evan Read включено в состав коммита
347
348
349
350
351
352
353
354
355
356
357
#### 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 включено в состав коммита
358
### `only`/`except` (basic)
Douwe Maan's avatar
Douwe Maan включено в состав коммита
359

Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
360
361
`only` and `except` are two parameters that set a job policy to limit when
jobs are created:
Douwe Maan's avatar
Douwe Maan включено в состав коммита
362

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
363
1. `only` defines the names of branches and tags for which the job will run.
Evan Read's avatar
Evan Read включено в состав коммита
364
1. `except` defines the names of branches and tags for which the job will
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
365
    **not** run.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
366

Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
367
There are a few rules that apply to the usage of job policy:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
368

Evan Read's avatar
Evan Read включено в состав коммита
369
- `only` and `except` are inclusive. If both `only` and `except` are defined
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
370
   in a job specification, the ref is filtered by `only` and `except`.
Cody Mize's avatar
Cody Mize включено в состав коммита
371
- `only` and `except` allow the use of regular expressions ([supported regexp syntax](#supported-onlyexcept-regexp-syntax)).
Evan Read's avatar
Evan Read включено в состав коммита
372
- `only` and `except` allow to specify a repository path to filter jobs for
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
373
374
   forks.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
375
376
377
378
In addition, `only` and `except` allow the use of special keywords:

| **Value** |  **Description**  |
| --------- |  ---------------- |
Shinya Maeda's avatar
Shinya Maeda включено в состав коммита
379
380
381
382
383
384
385
386
387
388
| `branches`       | When a git reference of a pipeline is a branch.  |
| `tags`           | When a git reference of a pipeline is a tag.  |
| `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)). |
BAI Peng's avatar
BAI Peng включено в состав коммита
389
| `chats`          | For jobs created using a [GitLab ChatOps](../chatops/README.md) command. |
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
390

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
391
In the example below, `job` will run only for refs that start with `issue-`,
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
392
whereas all branches will be skipped:
Douwe Maan's avatar
Douwe Maan включено в состав коммита
393
394
395

```yaml
job:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
396
  # use regexp
Douwe Maan's avatar
Douwe Maan включено в состав коммита
397
  only:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
398
399
    - /^issue-.*$/
  # use special keyword
Douwe Maan's avatar
Douwe Maan включено в состав коммита
400
  except:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
401
    - branches
Douwe Maan's avatar
Douwe Maan включено в состав коммита
402
403
```

Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
404
405
406
407
408
409
410
411
412
413
414
415
416
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
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
417
In this example, `job` will run only for refs that are tagged, or if a build is
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
418
explicitly requested via an API trigger or a [Pipeline Schedule][schedules]:
Jason Roehm's avatar
Jason Roehm включено в состав коммита
419
420
421
422
423
424
425

```yaml
job:
  # use special keywords
  only:
    - tags
    - triggers
Filip Krakowski's avatar
Filip Krakowski включено в состав коммита
426
    - schedules
Jason Roehm's avatar
Jason Roehm включено в состав коммита
427
428
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
429
430
The repository path can be used to have jobs executed only for the parent
repository and not forks:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
431
432
433
434
435
436
437

```yaml
job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce
Raphael Das Gupta's avatar
Raphael Das Gupta включено в состав коммита
438
    - /^release/.*$/@gitlab-org/gitlab-ce
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
439
```
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
440
441

The above example will run `job` for all branches on `gitlab-org/gitlab-ce`,
Toon Claes's avatar
Toon Claes включено в состав коммита
442
except `master` and those with names prefixed with `release/`.
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
443

Shinya Maeda's avatar
Shinya Maeda включено в состав коммита
444
445
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.
Shinya Maeda's avatar
Shinya Maeda включено в состав коммита
446
447
448
449
450
451
452
453

For example,

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
454
is translated to:
Shinya Maeda's avatar
Shinya Maeda включено в состав коммита
455
456
457
458
459
460
461

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

Raphael Das Gupta's avatar
Raphael Das Gupta включено в состав коммита
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
#### 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`.

Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
### 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 включено в состав коммита
505
### `only`/`except` (advanced)
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
506

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
507
CAUTION: **Warning:**
otuhs_d's avatar
otuhs_d включено в состав коммита
508
This is an _alpha_ feature, and it is subject to change at any time without
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
509
prior notice!
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
510

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
511
512
GitLab supports both simple and complex strategies, so it's possible to use an
array and a hash configuration scheme.
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
513

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
514
Four keys are available:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
515

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
516
517
518
519
- `refs`
- `variables`
- `changes`
- `kubernetes`
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
520

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
521
If you use multiple keys under `only` or `except`, they act as an AND. The logic is:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
522

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
523
> (any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active)
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
524

Evan Read's avatar
Evan Read включено в состав коммита
525
#### `only:refs`/`except:refs`
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
526

Elan Ruusamäe's avatar
Elan Ruusamäe включено в состав коммита
527
528
> `refs` policy introduced in GitLab 10.0.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
529
The `refs` strategy can take the same values as the
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
530
[simplified only/except configuration](#onlyexcept-basic).
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
531

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
532
533
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:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
534
535

```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
536
deploy:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
537
538
539
540
  only:
    refs:
      - master
      - schedules
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
541
542
```

Evan Read's avatar
Evan Read включено в состав коммита
543
#### `only:kubernetes`/`except:kubernetes`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
544

Elan Ruusamäe's avatar
Elan Ruusamäe включено в состав коммита
545
546
> `kubernetes` policy introduced in GitLab 10.0.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
547
548
549
550
551
552
553
554
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:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
555
556
557
    kubernetes: active
```

Evan Read's avatar
Evan Read включено в состав коммита
558
#### `only:variables`/`except:variables`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
559

Elan Ruusamäe's avatar
Elan Ruusamäe включено в состав коммита
560
561
> `variables` policy introduced in GitLab 10.7.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
562
563
564
565
566
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.

Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
567
Examples of using variables expressions:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
568
569
570

```yaml
deploy:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
571
  script: cap staging deploy
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
572
573
574
575
576
577
578
579
  only:
    refs:
      - branches
    variables:
      - $RELEASE == "staging"
      - $STAGING
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
580
Another use case is excluding jobs depending on a commit message:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
581
582
583
584
585
586
587
588
589

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

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
590
Learn more about [variables expressions](../variables/README.md#environment-variables-expressions).
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
591

Evan Read's avatar
Evan Read включено в состав коммита
592
#### `only:changes`/`except:changes`
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
593

Elan Ruusamäe's avatar
Elan Ruusamäe включено в состав коммита
594
595
> `changes` policy [introduced][ce-19232] in GitLab 11.4.

Said Masoud's avatar
Said Masoud включено в состав коммита
596
Using the `changes` keyword with `only` or `except` makes it possible to define if
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
597
598
599
a job should be created based on files modified by a git push event.

For example:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
600
601
602
603
604
605
606
607

```yaml
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  only:
    changes:
      - Dockerfile
      - docker/scripts/*
Lukas Schneider's avatar
Lukas Schneider включено в состав коммита
608
      - dockerfiles/**/*
Kirill Zaitsev's avatar
Kirill Zaitsev включено в состав коммита
609
      - more_scripts/*.{rb,py,sh}
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
610
611
```

Olliver Schinagl's avatar
Olliver Schinagl включено в состав коммита
612
In the scenario above, when pushing multiple commits to GitLab to an existing
Said Masoud's avatar
Said Masoud включено в состав коммита
613
614
branch, GitLab creates and triggers the `docker build` job, provided that one of the
commits contains changes to any of the following:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
615
616
617

- The `Dockerfile` file.
- Any of the files inside `docker/scripts/` directory.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
618
619
- Any of the files and subdirectories inside the `dockerfiles` directory.
- Any of the files with `rb`, `py`, `sh` extensions inside the `more_scripts` directory.
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
620

Said Masoud's avatar
Said Masoud включено в состав коммита
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
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. For example:

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

NOTE: **Note:**
In the example above, the expressions are wrapped double quotes because they are glob patterns. GitLab will fail to parse `.gitlab-ci.yml` files with unwrapped glob patterns.

The following example will skip the CI job if a change is detected in any file in the root directory of the repo with a `.md` extension:

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

Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
645
CAUTION: **Warning:**
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
646
647
648
There are some caveats when using this feature with new branches and tags. See
the section below.

Evan Read's avatar
Evan Read включено в состав коммита
649
##### Using `changes` with new branches and tags
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
650

Olliver Schinagl's avatar
Olliver Schinagl включено в состав коммита
651
652
653
654
When pushing a **new** branch or a **new** tag to GitLab, the policy always
evaluates to true and GitLab will create a job. This feature is not connected
with merge requests yet and, because GitLab is creating pipelines before a user
can create a merge request, it is unknown what the target branch is at this point.
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
655

Evan Read's avatar
Evan Read включено в состав коммита
656
##### Using `changes` with `merge_requests`
Hiroyuki Sato's avatar
Hiroyuki Sato включено в состав коммита
657
658

With [pipelines for merge requests](../merge_request_pipelines/index.md),
Olliver Schinagl's avatar
Olliver Schinagl включено в состав коммита
659
it is possible to define a job to be created based on files modified
Hiroyuki Sato's avatar
Hiroyuki Sato включено в состав коммита
660
661
662
663
in a merge request.

For example:

Olliver Schinagl's avatar
Olliver Schinagl включено в состав коммита
664
```yaml
Hiroyuki Sato's avatar
Hiroyuki Sato включено в состав коммита
665
666
667
668
669
670
671
672
673
674
docker build service one:
  script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG .
  only:
    refs:
      - merge_requests
    changes:
      - Dockerfile
      - service-one/**/*
```

Olliver Schinagl's avatar
Olliver Schinagl включено в состав коммита
675
676
677
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.
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
678

Evan Read's avatar
Evan Read включено в состав коммита
679
### `tags`
Douwe Maan's avatar
Douwe Maan включено в состав коммита
680

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
681
`tags` is used to select specific Runners from the list of all Runners that are
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
682
allowed to run this project.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
683

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
684
During the registration of a Runner, you can specify the Runner's tags, for
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
685
686
example `ruby`, `postgres`, `development`.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
687
`tags` allow you to run jobs with Runners that have the specified tags
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
688
689
690
assigned to them:

```yaml
Douwe Maan's avatar
Douwe Maan включено в состав коммита
691
692
693
694
695
696
job:
  tags:
    - ruby
    - postgres
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
697
The specification above, will make sure that `job` is built by a Runner that
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
698
has both `ruby` AND `postgres` tags defined.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
699

Mart Sõmermaa's avatar
Mart Sõmermaa включено в состав коммита
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
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 включено в состав коммита
722
### `allow_failure`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
723

C.J. Jameson's avatar
C.J. Jameson включено в состав коммита
724
725
`allow_failure` allows a job to fail without impacting the rest of the CI
suite.
Olivier Gonzalez's avatar
Olivier Gonzalez включено в состав коммита
726
The default value is `false`, except for [manual](#whenmanual) jobs.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
727

C.J. Jameson's avatar
C.J. Jameson включено в состав коммита
728
729
730
731
732
733
734
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.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
735
736
737
738
739
740
741
742
743

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 включено в состав коммита
744
    - execute_script_that_will_fail
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
745
746
747
748
749
  allow_failure: true

job2:
  stage: test
  script:
pityonline's avatar
pityonline включено в состав коммита
750
    - execute_script_that_will_succeed
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
751
752
753
754

job3:
  stage: deploy
  script:
pityonline's avatar
pityonline включено в состав коммита
755
    - deploy_to_staging
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
756
757
```

Evan Read's avatar
Evan Read включено в состав коммита
758
### `when`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
759
760
761

`when` is used to implement jobs that are run in case of failure or despite the
failure.
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
762

Robert Speicher's avatar
Robert Speicher включено в состав коммита
763
764
`when` can be set to one of the following values:

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
765
1. `on_success` - execute job only when all jobs from prior stages
C.J. Jameson's avatar
C.J. Jameson включено в состав коммита
766
767
    succeed (or are considered succeeding because they are marked
    `allow_failure`). This is the default.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
768
1. `on_failure` - execute job only when at least one job from prior stages
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
769
    fails.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
770
771
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
Philipp Hasper's avatar
Philipp Hasper включено в состав коммита
772
    [manual actions](#whenmanual) below.
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
773

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
774
775
776
For example:

```yaml
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
777
stages:
pityonline's avatar
pityonline включено в состав коммита
778
779
780
781
782
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
783

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
784
build_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
785
786
  stage: build
  script:
pityonline's avatar
pityonline включено в состав коммита
787
    - make build
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
788

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
789
cleanup_build_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
790
791
  stage: cleanup_build
  script:
pityonline's avatar
pityonline включено в состав коммита
792
    - cleanup build when failed
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
793
794
  when: on_failure

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
795
test_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
796
797
  stage: test
  script:
pityonline's avatar
pityonline включено в состав коммита
798
    - make test
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
799

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
800
deploy_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
801
802
  stage: deploy
  script:
pityonline's avatar
pityonline включено в состав коммита
803
    - make deploy
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
804
  when: manual
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
805

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
806
cleanup_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
807
808
  stage: cleanup
  script:
pityonline's avatar
pityonline включено в состав коммита
809
    - cleanup after jobs
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
810
811
812
813
  when: always
```

The above script will:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
814

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
815
1. Execute `cleanup_build_job` only when `build_job` fails.
Evan Read's avatar
Evan Read включено в состав коммита
816
1. Always execute `cleanup_job` as the last step in pipeline regardless of
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
817
   success or failure.
Evan Read's avatar
Evan Read включено в состав коммита
818
1. Allow you to manually execute `deploy_job` from GitLab's UI.
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
819

Evan Read's avatar
Evan Read включено в состав коммита
820
#### `when:manual`
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
821

Brett Walker's avatar
Brett Walker включено в состав коммита
822
823
824
> - Introduced in GitLab 8.10.
> - Blocking manual actions were introduced in GitLab 9.0.
> - Protected actions were introduced in GitLab 9.2.
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
825

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
826
827
828
829
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
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
830
[environments documentation](../environments.md#configuring-manual-deployments).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
831

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
832
833
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
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
834
possible to resume execution of the pipeline when someone executes a blocking
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
835
manual action by clicking a _play_ button.
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
836

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
837
When a pipeline is blocked, it will not be merged if Merge When Pipeline Succeeds
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
838
839
840
841
842
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`.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
843
844
845
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.
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
846

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
847
848
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 🐢 включено в состав коммита
849
850
851
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
have the ability to merge to this branch.
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
852

Evan Read's avatar
Evan Read включено в состав коммита
853
#### `when:delayed`
Winnie Hellmann's avatar
Winnie Hellmann включено в состав коммита
854
855
856
857
858
859
860

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21767) in GitLab 11.4.

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
Shane A. Stillwell's avatar
Shane A. Stillwell включено в состав коммита
861
provided. `start_in` key must be less than or equal to one hour. Examples of valid values include:
Winnie Hellmann's avatar
Winnie Hellmann включено в состав коммита
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888

- `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.
GitLab runner will pick your job soon and start the job.

Evan Read's avatar
Evan Read включено в состав коммита
889
### `environment`
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
890

Brett Walker's avatar
Brett Walker включено в состав коммита
891
892
893
> - Introduced in GitLab 8.9.
> - You can read more about environments and find more examples in the
>   [documentation about environments][environment].
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
894

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
895
`environment` is used to define that a job deploys to a specific environment.
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
896
897
If `environment` is specified and no environment under that name exists, a new
one will be created automatically.
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
898

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
899
In its simplest form, the `environment` keyword can be defined like:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
900

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
901
```yaml
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
902
903
904
deploy to production:
  stage: deploy
  script: git push production HEAD:master
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
905
906
  environment:
    name: production
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
907
908
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
909
910
911
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 включено в состав коммита
912
#### `environment:name`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
913

Brett Walker's avatar
Brett Walker включено в состав коммита
914
915
916
917
918
919
920
> - 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`.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
921

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
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.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
937
938
939
940
Instead of defining the name of the environment right after the `environment`
keyword, it is also possible to define it as a separate value. For that, use
the `name` keyword under `environment`:

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
941
```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
942
943
944
945
946
947
948
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
```

Evan Read's avatar
Evan Read включено в состав коммита
949
#### `environment:url`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
950

Brett Walker's avatar
Brett Walker включено в состав коммита
951
952
953
954
955
956
> - Introduced in GitLab 8.11.
> - Before GitLab 8.11, the URL could be added only in GitLab's UI. The
>   recommended way now is to define it in `.gitlab-ci.yml`.
> - The `url` parameter can use any of the defined CI variables,
>   including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
>   You however cannot use variables defined under `script`.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
957
958
959
960
961
962
963
964

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
965
```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
966
967
968
969
970
971
972
973
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
    url: https://prod.example.com
```

Evan Read's avatar
Evan Read включено в состав коммита
974
#### `environment:on_stop`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
975

Brett Walker's avatar
Brett Walker включено в состав коммита
976
977
978
979
> - [Introduced][ce-6669] in GitLab 8.13.
> - Starting with GitLab 8.14, when you have an environment that has a stop action
>   defined, GitLab will automatically trigger a stop action when the associated
>   branch is deleted.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
980

Bryce Chidester's avatar
Bryce Chidester включено в состав коммита
981
Closing (stopping) environments can be achieved with the `on_stop` keyword defined under
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
982
983
984
985
986
`environment`. It declares a different job that runs in order to close
the environment.

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

Evan Read's avatar
Evan Read включено в состав коммита
987
#### `environment:action`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
988
989
990
991
992
993

> [Introduced][ce-6669] in GitLab 8.13.

The `action` keyword is to be used in conjunction with `on_stop` and is defined
in the job that is called to close the environment.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
994
995
996
997
998
999
1000
Take for instance:

```yaml
review_app:
  stage: deploy
  script: make deploy-app
  environment:
Для ускорения просмотра не вся история отображается Просмотреть всю вину