README.md 98,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
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
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
| [`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).

## 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 включено в состав коммита
210

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
211
212
213
214
`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 включено в состав коммита
215
`after_script` is used to define the command that will be run after all
Damian Nowak's avatar
Damian Nowak включено в состав коммита
216
jobs, including failed ones. This has to be an array or a multi-line string.
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
217

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

Evan Read's avatar
Evan Read включено в состав коммита
220
221
222
223
224
- 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 включено в состав коммита
225

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

- Have a current working directory set back to the default.
Evan Read's avatar
Evan Read включено в состав коммита
229
230
231
232
233
234
235
236
- 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 включено в состав коммита
237

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
241
242
```yaml
before_script:
pityonline's avatar
pityonline включено в состав коммита
243
  - global before script
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
244
245
246

job:
  before_script:
pityonline's avatar
pityonline включено в состав коммита
247
    - execute this instead of global before script
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
248
  script:
pityonline's avatar
pityonline включено в состав коммита
249
    - my command
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
250
  after_script:
pityonline's avatar
pityonline включено в состав коммита
251
    - execute this after my script
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
252
253
```

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
256
257
258
259
`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 включено в состав коммита
260
The ordering of elements in `stages` defines the ordering of jobs' execution:
Douwe Maan's avatar
Douwe Maan включено в состав коммита
261

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
262
263
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 включено в состав коммита
264
   complete successfully.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
265
266

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

```yaml
Douwe Maan's avatar
Douwe Maan включено в состав коммита
269
270
271
272
273
274
stages:
  - build
  - test
  - deploy
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
275
1. First, all jobs of `build` are executed in parallel.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
276
277
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 включено в состав коммита
278
1. If all jobs of `deploy` succeed, the commit is marked as `passed`.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
279
280
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 включено в состав коммита
281

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

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

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

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

```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
295
296
297
298
299
300
301
302
303
304
305
306
307
308
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 включено в состав коммита
309
  stage: test
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
310
311
312
313
314
  script: make test

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

Evan Read's avatar
Evan Read включено в состав коммита
317
318
319
320
321
322
323
324
325
326
327
#### 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 включено в состав коммита
328
### `only`/`except` (basic)
Douwe Maan's avatar
Douwe Maan включено в состав коммита
329

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

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

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

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

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

| **Value** |  **Description**  |
| --------- |  ---------------- |
Shinya Maeda's avatar
Shinya Maeda включено в состав коммита
349
350
351
352
353
354
355
356
357
358
| `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 включено в состав коммита
359
| `chats`          | For jobs created using a [GitLab ChatOps](../chatops/README.md) command. |
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
360

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

```yaml
job:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
366
  # use regexp
Douwe Maan's avatar
Douwe Maan включено в состав коммита
367
  only:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
368
369
    - /^issue-.*$/
  # use special keyword
Douwe Maan's avatar
Douwe Maan включено в состав коммита
370
  except:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
371
    - branches
Douwe Maan's avatar
Douwe Maan включено в состав коммита
372
373
```

Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
374
375
376
377
378
379
380
381
382
383
384
385
386
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 включено в состав коммита
387
In this example, `job` will run only for refs that are tagged, or if a build is
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
388
explicitly requested via an API trigger or a [Pipeline Schedule][schedules]:
Jason Roehm's avatar
Jason Roehm включено в состав коммита
389
390
391
392
393
394
395

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
399
400
The repository path can be used to have jobs executed only for the parent
repository and not forks:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
401
402
403
404
405
406
407

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

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

Shinya Maeda's avatar
Shinya Maeda включено в состав коммита
414
415
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 включено в состав коммита
416
417
418
419
420
421
422
423

For example,

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
424
is translated to:
Shinya Maeda's avatar
Shinya Maeda включено в состав коммита
425
426
427
428
429
430
431

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

Raphael Das Gupta's avatar
Raphael Das Gupta включено в состав коммита
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
#### 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 включено в состав коммита
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
### 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 включено в состав коммита
475
### `only`/`except` (advanced)
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
476

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
477
CAUTION: **Warning:**
Takuya Noguchi's avatar
Takuya Noguchi включено в состав коммита
478
This an _alpha_ feature, and it is subject to change at any time without
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
479
prior notice!
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
480

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
486
487
488
489
- `refs`
- `variables`
- `changes`
- `kubernetes`
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
490

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

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

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

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

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

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

```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
506
deploy:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
507
508
509
510
  only:
    refs:
      - master
      - schedules
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
511
512
```

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
517
518
519
520
521
522
523
524
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 включено в состав коммита
525
526
527
    kubernetes: active
```

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
532
533
534
535
536
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 включено в состав коммита
537
Examples of using variables expressions:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
538
539
540

```yaml
deploy:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
541
  script: cap staging deploy
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
542
543
544
545
546
547
548
549
  only:
    refs:
      - branches
    variables:
      - $RELEASE == "staging"
      - $STAGING
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
550
Another use case is excluding jobs depending on a commit message:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
551
552
553
554
555
556
557
558
559

```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 включено в состав коммита
560
Learn more about [variables expressions](../variables/README.md#environment-variables-expressions).
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
561

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

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

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

For example:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
570
571
572
573
574
575
576
577

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

Olliver Schinagl's avatar
Olliver Schinagl включено в состав коммита
582
In the scenario above, when pushing multiple commits to GitLab to an existing
Said Masoud's avatar
Said Masoud включено в состав коммита
583
584
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 включено в состав коммита
585
586
587

- The `Dockerfile` file.
- Any of the files inside `docker/scripts/` directory.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
588
589
- 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 включено в состав коммита
590

Said Masoud's avatar
Said Masoud включено в состав коммита
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
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 включено в состав коммита
615
CAUTION: **Warning:**
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
616
617
618
There are some caveats when using this feature with new branches and tags. See
the section below.

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

Olliver Schinagl's avatar
Olliver Schinagl включено в состав коммита
621
622
623
624
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 включено в состав коммита
625

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

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

For example:

Olliver Schinagl's avatar
Olliver Schinagl включено в состав коммита
634
```yaml
Hiroyuki Sato's avatar
Hiroyuki Sato включено в состав коммита
635
636
637
638
639
640
641
642
643
644
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 включено в состав коммита
645
646
647
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 включено в состав коммита
648

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

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

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

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

```yaml
Douwe Maan's avatar
Douwe Maan включено в состав коммита
661
662
663
664
665
666
job:
  tags:
    - ruby
    - postgres
```

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

Mart Sõmermaa's avatar
Mart Sõmermaa включено в состав коммита
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
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 включено в состав коммита
692
### `allow_failure`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
693

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

C.J. Jameson's avatar
C.J. Jameson включено в состав коммита
698
699
700
701
702
703
704
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 включено в состав коммита
705
706
707
708
709
710
711
712
713

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 включено в состав коммита
714
    - execute_script_that_will_fail
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
715
716
717
718
719
  allow_failure: true

job2:
  stage: test
  script:
pityonline's avatar
pityonline включено в состав коммита
720
    - execute_script_that_will_succeed
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
721
722
723
724

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

Evan Read's avatar
Evan Read включено в состав коммита
728
### `when`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
729
730
731

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
735
1. `on_success` - execute job only when all jobs from prior stages
C.J. Jameson's avatar
C.J. Jameson включено в состав коммита
736
737
    succeed (or are considered succeeding because they are marked
    `allow_failure`). This is the default.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
738
1. `on_failure` - execute job only when at least one job from prior stages
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
739
    fails.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
740
741
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 включено в состав коммита
742
    [manual actions](#whenmanual) below.
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
743

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
744
745
746
For example:

```yaml
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
747
stages:
pityonline's avatar
pityonline включено в состав коммита
748
749
750
751
752
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
753

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
754
build_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
755
756
  stage: build
  script:
pityonline's avatar
pityonline включено в состав коммита
757
    - make build
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
758

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
759
cleanup_build_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
760
761
  stage: cleanup_build
  script:
pityonline's avatar
pityonline включено в состав коммита
762
    - cleanup build when failed
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
763
764
  when: on_failure

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
765
test_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
766
767
  stage: test
  script:
pityonline's avatar
pityonline включено в состав коммита
768
    - make test
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
769

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
770
deploy_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
771
772
  stage: deploy
  script:
pityonline's avatar
pityonline включено в состав коммита
773
    - make deploy
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
774
  when: manual
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
775

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
776
cleanup_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
777
778
  stage: cleanup
  script:
pityonline's avatar
pityonline включено в состав коммита
779
    - cleanup after jobs
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
780
781
782
783
  when: always
```

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

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

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

Brett Walker's avatar
Brett Walker включено в состав коммита
792
793
794
> - 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 включено в состав коммита
795

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
796
797
798
799
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 включено в состав коммита
800
[environments documentation](../environments.md#configuring-manual-deployments).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
801

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
807
When a pipeline is blocked, it will not be merged if Merge When Pipeline Succeeds
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
808
809
810
811
812
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 включено в состав коммита
813
814
815
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 включено в состав коммита
816

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
817
818
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 🐢 включено в состав коммита
819
820
821
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 включено в состав коммита
822

Evan Read's avatar
Evan Read включено в состав коммита
823
#### `when:delayed`
Winnie Hellmann's avatar
Winnie Hellmann включено в состав коммита
824
825
826
827
828
829
830

> [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 включено в состав коммита
831
provided. `start_in` key must be less than or equal to one hour. Examples of valid values include:
Winnie Hellmann's avatar
Winnie Hellmann включено в состав коммита
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858

- `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 включено в состав коммита
859
### `environment`
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
860

Brett Walker's avatar
Brett Walker включено в состав коммита
861
862
863
> - 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 включено в состав коммита
864

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
871
```yaml
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
872
873
874
deploy to production:
  stage: deploy
  script: git push production HEAD:master
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
875
876
  environment:
    name: production
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
877
878
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
879
880
881
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 включено в состав коммита
882
#### `environment:name`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
883

Brett Walker's avatar
Brett Walker включено в состав коммита
884
885
886
887
888
889
890
> - 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 включено в состав коммита
891

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
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 включено в состав коммита
907
908
909
910
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 включено в состав коммита
911
```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
912
913
914
915
916
917
918
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
```

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

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

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 включено в состав коммита
935
```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
936
937
938
939
940
941
942
943
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 включено в состав коммита
944
#### `environment:on_stop`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
945

Brett Walker's avatar
Brett Walker включено в состав коммита
946
947
948
949
> - [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 включено в состав коммита
950

Bryce Chidester's avatar
Bryce Chidester включено в состав коммита
951
Closing (stopping) environments can be achieved with the `on_stop` keyword defined under
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
952
953
954
955
956
`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 включено в состав коммита
957
#### `environment:action`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
958
959
960
961
962
963

> [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 включено в состав коммита
964
965
966
967
968
969
970
971
972
973
974
975
Take for instance:

```yaml
review_app:
  stage: deploy
  script: make deploy-app
  environment:
    name: review
    on_stop: stop_review_app

stop_review_app:
  stage: deploy
Mark Lapierre's avatar
Mark Lapierre включено в состав коммита
976
977
  variables:
    GIT_STRATEGY: none  
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
978
979
980
981
982
983
984
985
986
987
988
  script: make delete-app
  when: manual
  environment:
    name: review
    action: stop
```

In the above example we set up the `review_app` job to deploy to the `review`
environment, and we also defined a new `stop_review_app` job under `on_stop`.
Once the `review_app` job is successfully finished, it will trigger the
`stop_review_app` job based on what is defined under `when`. In this case we
Evan Read's avatar
Evan Read включено в состав коммита
989
set it up to `manual` so it will need a [manual action](#whenmanual) via
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
990
991
GitLab's web interface in order to run.

Mark Lapierre's avatar
Mark Lapierre включено в состав коммита
992
993
994
995
Also in the example, `GIT_STRATEGY` is set to `none` so that GitLab Runner won’t
try to check out the code after the branch is deleted when the `stop_review_app`
job is [automatically triggered](../environments.md#automatically-stopping-an-environment).

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
996
997
998
999
1000
The `stop_review_app` job is **required** to have the following keywords defined:

- `when` - [reference](#when)
- `environment:name`
- `environment:action`
Для ускорения просмотра не вся история отображается Просмотреть всю вину