README.md 94,7 КБ
Newer Older
Evan Read's avatar
Evan Read включено в состав коммита
1
# GitLab CI/CD Pipeline Configuration Reference
Douwe Maan's avatar
Douwe Maan включено в состав коммита
2

Evan Read's avatar
Evan Read включено в состав коммита
3
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 включено в состав коммита
4

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

Evan Read's avatar
Evan Read включено в состав коммита
7
8
9
10
11
12
13
14
15
16
17
18
19
- 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 включено в состав коммита
20

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
21
NOTE: **Note:**
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
22
If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository-starter),
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
23
24
25
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 включено в состав коммита
26
27
28
## Introduction

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

Evan Read's avatar
Evan Read включено в состав коммита
30
31
32
33
34
35
36
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 включено в состав коммита
37
38
39
40
41
42
43
44
45

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

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

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

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

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

### Unavailable names for jobs

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

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

Evan Read's avatar
Evan Read включено в состав коммита
75
76
77
78
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
108
109
110
111
112
113
114
115
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
### 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [`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`, and `artifacts:reports:performance`. |
| [`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`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [`extends`](#extends)                              | Configuration entry that this job is going to inherit from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [`pages`](#pages)                                  | Upload the result of a job to use with GitLab Pages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [`variables`](#variables)                          | Define job variables on a job level.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

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

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

Martin Nowak's avatar
Martin Nowak включено в состав коммита
214
The `before_script` and the main `script` are concatenated and run in a single context/container.
Stefan Agner's avatar
Stefan Agner включено в состав коммита
215
216
217
The `after_script` is run separately. The current working directory is set back to
default. Depending on the executor, changes done outside of the working tree might
not be visible, e.g. software installed in the `before_script`.
Martin Nowak's avatar
Martin Nowak включено в состав коммита
218

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
222
223
```yaml
before_script:
pityonline's avatar
pityonline включено в состав коммита
224
  - global before script
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
225
226
227

job:
  before_script:
pityonline's avatar
pityonline включено в состав коммита
228
    - execute this instead of global before script
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
229
  script:
pityonline's avatar
pityonline включено в состав коммита
230
    - my command
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
231
  after_script:
pityonline's avatar
pityonline включено в состав коммита
232
    - execute this after my script
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
233
234
```

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
237
238
239
240
`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 включено в состав коммита
241
The ordering of elements in `stages` defines the ordering of jobs' execution:
Douwe Maan's avatar
Douwe Maan включено в состав коммита
242

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
243
244
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 включено в состав коммита
245
   complete successfully.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
246
247

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

```yaml
Douwe Maan's avatar
Douwe Maan включено в состав коммита
250
251
252
253
254
255
stages:
  - build
  - test
  - deploy
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
256
1. First, all jobs of `build` are executed in parallel.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
257
258
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 включено в состав коммита
259
1. If all jobs of `deploy` succeed, the commit is marked as `passed`.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
260
261
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 включено в состав коммита
262

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

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

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

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

```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
276
277
278
279
280
281
282
283
284
285
286
287
288
289
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 включено в состав коммита
290
  stage: test
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
291
292
293
294
295
  script: make test

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

Evan Read's avatar
Evan Read включено в состав коммита
298
299
300
301
302
303
304
305
306
307
308
#### 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 включено в состав коммита
309
### `only`/`except` (basic)
Douwe Maan's avatar
Douwe Maan включено в состав коммита
310

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

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

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

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

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

| **Value** |  **Description**  |
| --------- |  ---------------- |
Shinya Maeda's avatar
Shinya Maeda включено в состав коммита
330
331
332
333
334
335
336
337
338
339
| `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)). |
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
340

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

```yaml
job:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
346
  # use regexp
Douwe Maan's avatar
Douwe Maan включено в состав коммита
347
  only:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
348
349
    - /^issue-.*$/
  # use special keyword
Douwe Maan's avatar
Douwe Maan включено в состав коммита
350
  except:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
351
    - branches
Douwe Maan's avatar
Douwe Maan включено в состав коммита
352
353
```

Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
354
355
356
357
358
359
360
361
362
363
364
365
366
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 включено в состав коммита
367
In this example, `job` will run only for refs that are tagged, or if a build is
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
368
explicitly requested via an API trigger or a [Pipeline Schedule][schedules]:
Jason Roehm's avatar
Jason Roehm включено в состав коммита
369
370
371
372
373
374
375

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
379
380
The repository path can be used to have jobs executed only for the parent
repository and not forks:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
381
382
383
384
385
386
387

```yaml
job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce
Toon Claes's avatar
Toon Claes включено в состав коммита
388
    - release/.*@gitlab-org/gitlab-ce
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
389
```
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
390
391

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

Cody Mize's avatar
Cody Mize включено в состав коммита
394
395
396
397
398
NOTE: **Note:**
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`.

Shinya Maeda's avatar
Shinya Maeda включено в состав коммита
399
400
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 включено в состав коммита
401
402
403
404
405
406
407
408

For example,

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
409
is translated to:
Shinya Maeda's avatar
Shinya Maeda включено в состав коммита
410
411
412
413
414
415
416

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

Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
### 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 включено в состав коммита
438
### `only`/`except` (advanced)
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
439

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

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
449
450
451
452
- `refs`
- `variables`
- `changes`
- `kubernetes`
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
453

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

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

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

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

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

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

```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
469
deploy:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
470
471
472
473
  only:
    refs:
      - master
      - schedules
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
474
475
```

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
480
481
482
483
484
485
486
487
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 включено в состав коммита
488
489
490
    kubernetes: active
```

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
495
496
497
498
499
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 включено в состав коммита
500
Examples of using variables expressions:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
501
502
503

```yaml
deploy:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
504
  script: cap staging deploy
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
505
506
507
508
509
510
511
512
  only:
    refs:
      - branches
    variables:
      - $RELEASE == "staging"
      - $STAGING
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
513
Another use case is excluding jobs depending on a commit message:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
514
515
516
517
518
519
520
521
522

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

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

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

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

For example:
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
533
534
535
536
537
538
539
540

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

Olliver Schinagl's avatar
Olliver Schinagl включено в состав коммита
545
In the scenario above, when pushing multiple commits to GitLab to an existing
Said Masoud's avatar
Said Masoud включено в состав коммита
546
547
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 включено в состав коммита
548
549
550

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

Said Masoud's avatar
Said Masoud включено в состав коммита
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
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 включено в состав коммита
578
CAUTION: **Warning:**
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
579
580
581
There are some caveats when using this feature with new branches and tags. See
the section below.

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

Olliver Schinagl's avatar
Olliver Schinagl включено в состав коммита
584
585
586
587
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 включено в состав коммита
588

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

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

For example:

Olliver Schinagl's avatar
Olliver Schinagl включено в состав коммита
597
```yaml
Hiroyuki Sato's avatar
Hiroyuki Sato включено в состав коммита
598
599
600
601
602
603
604
605
606
607
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 включено в состав коммита
608
609
610
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 включено в состав коммита
611

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

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

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

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

```yaml
Douwe Maan's avatar
Douwe Maan включено в состав коммита
624
625
626
627
628
629
job:
  tags:
    - ruby
    - postgres
```

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

Mart Sõmermaa's avatar
Mart Sõmermaa включено в состав коммита
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
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 включено в состав коммита
655
### `allow_failure`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
656

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

C.J. Jameson's avatar
C.J. Jameson включено в состав коммита
661
662
663
664
665
666
667
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 включено в состав коммита
668
669
670
671
672
673
674
675
676

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 включено в состав коммита
677
    - execute_script_that_will_fail
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
678
679
680
681
682
  allow_failure: true

job2:
  stage: test
  script:
pityonline's avatar
pityonline включено в состав коммита
683
    - execute_script_that_will_succeed
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
684
685
686
687

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

Evan Read's avatar
Evan Read включено в состав коммита
691
### `when`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
692
693
694

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

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
707
708
709
For example:

```yaml
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
710
stages:
pityonline's avatar
pityonline включено в состав коммита
711
712
713
714
715
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
716

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
717
build_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
718
719
  stage: build
  script:
pityonline's avatar
pityonline включено в состав коммита
720
    - make build
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
721

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
722
cleanup_build_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
723
724
  stage: cleanup_build
  script:
pityonline's avatar
pityonline включено в состав коммита
725
    - cleanup build when failed
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
726
727
  when: on_failure

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
728
test_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
729
730
  stage: test
  script:
pityonline's avatar
pityonline включено в состав коммита
731
    - make test
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
732

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
733
deploy_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
734
735
  stage: deploy
  script:
pityonline's avatar
pityonline включено в состав коммита
736
    - make deploy
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
737
  when: manual
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
738

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
739
cleanup_job:
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
740
741
  stage: cleanup
  script:
pityonline's avatar
pityonline включено в состав коммита
742
    - cleanup after jobs
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
743
744
745
746
  when: always
```

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

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

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

Brett Walker's avatar
Brett Walker включено в состав коммита
755
756
757
> - 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 включено в состав коммита
758

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
759
760
761
762
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 включено в состав коммита
763
[environments documentation](../environments.md#configuring-manual-deployments).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
764

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
770
When a pipeline is blocked, it will not be merged if Merge When Pipeline Succeeds
Grzegorz Bizon's avatar
Grzegorz Bizon включено в состав коммита
771
772
773
774
775
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 включено в состав коммита
776
777
778
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 включено в состав коммита
779

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
780
781
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 🐢 включено в состав коммита
782
783
784
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 включено в состав коммита
785

Evan Read's avatar
Evan Read включено в состав коммита
786
#### `when:delayed`
Winnie Hellmann's avatar
Winnie Hellmann включено в состав коммита
787
788
789
790
791
792
793

> [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 включено в состав коммита
794
provided. `start_in` key must be less than or equal to one hour. Examples of valid values include:
Winnie Hellmann's avatar
Winnie Hellmann включено в состав коммита
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821

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

Brett Walker's avatar
Brett Walker включено в состав коммита
824
825
826
> - 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 включено в состав коммита
827

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

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

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
834
```yaml
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
835
836
837
deploy to production:
  stage: deploy
  script: git push production HEAD:master
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
838
839
  environment:
    name: production
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
840
841
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
842
843
844
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 включено в состав коммита
845
#### `environment:name`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
846

Brett Walker's avatar
Brett Walker включено в состав коммита
847
848
849
850
851
852
853
> - 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 включено в состав коммита
854

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
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 включено в состав коммита
870
871
872
873
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 включено в состав коммита
874
```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
875
876
877
878
879
880
881
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
```

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

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

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 включено в состав коммита
898
```yaml
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
899
900
901
902
903
904
905
906
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 включено в состав коммита
907
#### `environment:on_stop`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
908

Brett Walker's avatar
Brett Walker включено в состав коммита
909
910
911
912
> - [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 включено в состав коммита
913

Bryce Chidester's avatar
Bryce Chidester включено в состав коммита
914
Closing (stopping) environments can be achieved with the `on_stop` keyword defined under
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
915
916
917
918
919
`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 включено в состав коммита
920
#### `environment:action`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
921
922
923
924
925
926

> [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 включено в состав коммита
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
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
  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 включено в состав коммита
950
set it up to `manual` so it will need a [manual action](#whenmanual) via
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
951
952
953
954
955
956
957
958
959
960
GitLab's web interface in order to run.

The `stop_review_app` job is **required** to have the following keywords defined:

- `when` - [reference](#when)
- `environment:name`
- `environment:action`
- `stage` should be the same as the `review_app` in order for the environment
  to stop automatically when the branch is deleted

Evan Read's avatar
Evan Read включено в состав коммита
961
#### Dynamic environments
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
962

Brett Walker's avatar
Brett Walker включено в состав коммита
963
964
965
966
967
> - [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6.
> - The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15.
> - The `name` and `url` parameters 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 включено в состав коммита
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994

For example:

```yaml
deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com/
```

The `deploy as review app` job will be marked as deployment to dynamically
create the `review/$CI_COMMIT_REF_NAME` environment, where `$CI_COMMIT_REF_NAME`
is an [environment variable][variables] set by the Runner. The
`$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable
for inclusion in URLs. In this case, if the `deploy as review app` job was run
in a branch named `pow`, this environment would be accessible with an URL like
`https://review-pow.example.com/`.

This of course implies that the underlying server which hosts the application
is properly configured.

The common use case is to create dynamic environments for branches and use them
as Review Apps. You can see a simple example using Review Apps at
<https://gitlab.com/gitlab-examples/review-apps-nginx/>.

Evan Read's avatar
Evan Read включено в состав коммита
995
### `cache`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
996

Brett Walker's avatar
Brett Walker включено в состав коммита
997
998
999
1000
> - Introduced in GitLab Runner v0.7.0.
> - `cache` can be set globally and per-job.
> - From GitLab 9.0, caching is enabled and shared between pipelines and jobs
>   by default.
Для ускорения просмотра не вся история отображается Просмотреть всю вину