README.md 45.4 KB
Newer Older
1
# Configuration of your jobs with .gitlab-ci.yml
D
Douwe Maan 已提交
2

3
This document describes the usage of `.gitlab-ci.yml`, the file that is used by
4
GitLab Runner to manage your project's jobs.
5

6 7 8 9
From version 7.12, GitLab CI uses a [YAML](https://en.wikipedia.org/wiki/YAML)
file (`.gitlab-ci.yml`) for the project configuration. It is placed in the root
of your repository and contains definitions of how your project should be built.

10 11 12
If you want a quick introduction to GitLab CI, follow our
[quick start guide](../quick_start/README.md).

13 14 15 16 17
NOTE: **Note:**
If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository),
you may need to enable pipeline triggering in your project's
**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.

18 19
## Jobs

20
The YAML file defines a set of jobs with constraints stating when they should
21 22 23
be run. You can specify an unlimited number of jobs which are defined as
top-level elements with an arbitrary name and always have to contain at least
the `script` clause.
D
Douwe Maan 已提交
24 25 26 27 28 29 30 31 32

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

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

33
The above example is the simplest possible CI/CD configuration with two separate
34 35 36
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.
D
Douwe Maan 已提交
37

38 39 40
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.
D
Douwe Maan 已提交
41

42 43
Each job must have a unique name, but there are a few **reserved `keywords` that
cannot be used as job names**:
D
Douwe Maan 已提交
44

45 46 47 48 49 50 51 52
- `image`
- `services`
- `stages`
- `types`
- `before_script`
- `after_script`
- `variables`
- `cache`
D
Douwe Maan 已提交
53

54
A job is defined by a list of parameters that define the job behavior.
D
Douwe Maan 已提交
55

56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
| Keyword       | Required | Description |
|---------------|----------|-------------|
| script        | yes      | Defines a shell script which is executed by Runner |
| image         | no       | Use docker image, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
| services      | no       | Use docker services, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
| stage         | no       | Defines a job stage (default: `test`) |
| type          | no       | Alias for `stage` |
| variables     | no       | Define job variables on a job level |
| only          | no       | Defines a list of git refs for which job is created |
| except        | no       | Defines a list of git refs for which job is not created |
| tags          | no       | Defines a list of tags which are used to select Runner |
| allow_failure | no       | Allow job to fail. Failed job doesn't contribute to commit status |
| when          | no       | Define when to run job. Can be `on_success`, `on_failure`, `always` or `manual` |
| dependencies  | no       | Define other jobs that a job depends on so that you can pass artifacts between them|
| artifacts     | no       | Define list of [job artifacts](#artifacts) |
| cache         | no       | Define list of files that should be cached between subsequent runs |
| before_script | no       | Override a set of commands that are executed before job |
| after_script  | no       | Override a set of commands that are executed after job |
| environment   | no       | Defines a name of environment to which deployment is done by this job |
| coverage      | no       | Define code coverage settings for a given job |
| retry         | no       | Define how many times a job can be auto-retried in case of a failure |
77

78
### `pages`
D
Douwe Maan 已提交
79

80 81 82 83 84 85 86 87 88 89 90 91 92 93
`pages` is a special job that is used to upload static content to GitLab that
can be used to serve your website. It has a special syntax, so the two
requirements below must be met:

1. Any static content must be placed under a `public/` directory
1. `artifacts` with a path to the `public/` directory must be defined

The example below simply moves all files from the root of the project to the
`public/` directory. The `.public` workaround is so `cp` doesn't also copy
`public/` to itself in an infinite loop:

```
pages:
  stage: deploy
D
Douwe Maan 已提交
94
  script:
95 96 97 98 99 100
  - mkdir .public
  - cp -r * .public
  - mv .public public
  artifacts:
    paths:
    - public
D
Douwe Maan 已提交
101
  only:
102
  - master
D
Douwe Maan 已提交
103 104
```

105
Read more on [GitLab Pages user documentation](../../user/project/pages/index.md).
D
Douwe Maan 已提交
106

107
## `image` and `services`
108 109

This allows to specify a custom Docker image and a list of services that can be
110
used for time of the job. The configuration of this feature is covered in
111
[a separate document](../docker/README.md).
D
Douwe Maan 已提交
112

113
## `before_script` and `after_script`
114

115
> Introduced in GitLab 8.7 and requires Gitlab Runner v1.2
K
Kamil Trzcinski 已提交
116

117 118 119 120
`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.

121
`after_script` is used to define the command that will be run after for all
122
jobs, including failed ones. This has to be an array or a multi-line string.
123

124 125 126 127 128
The `before_script` and the main `script` are concatenated and run in a single context/container.
The `after_script` is run separately, so depending on the executor, changes done
outside of the working tree might not be visible, e.g. software installed in the
`before_script`.

129 130
It's possible to overwrite the globally defined `before_script` and `after_script`
if you set it per-job:
131

132 133 134 135 136 137 138 139 140 141 142 143 144 145
```yaml
before_script:
- global before script

job:
  before_script:
  - execute this instead of global before script
  script:
  - my command
  after_script:
  - execute this after my script
```

## `stages`
D
Douwe Maan 已提交
146

147 148 149 150
`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.
151
The ordering of elements in `stages` defines the ordering of jobs' execution:
D
Douwe Maan 已提交
152

153 154
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
155
   complete successfully.
D
Douwe Maan 已提交
156 157

Let's consider the following example, which defines 3 stages:
158 159

```yaml
D
Douwe Maan 已提交
160 161 162 163 164 165
stages:
  - build
  - test
  - deploy
```

166
1. First, all jobs of `build` are executed in parallel.
167 168
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.
169
1. If all jobs of `deploy` succeed, the commit is marked as `passed`.
170 171
1. If any of the previous jobs fails, the commit is marked as `failed` and no
   jobs of further stage are executed.
172

173
There are also two edge cases worth mentioning:
174

175 176 177
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.
2. If a job doesn't specify a `stage`, the job is assigned the `test` stage.
178

179
## `stage`
180

181 182 183
`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
`stage` are executed in `parallel`. For example:
D
Douwe Maan 已提交
184 185

```yaml
186 187 188 189 190 191 192 193 194 195 196 197 198 199
stages:
  - build
  - test
  - deploy

job 1:
  stage: build
  script: make build dependencies

job 2:
  stage: build
  script: make build artifacts

job 3:
D
Douwe Maan 已提交
200
  stage: test
201 202 203 204 205
  script: make test

job 4:
  stage: deploy
  script: make deploy
D
Douwe Maan 已提交
206 207
```

208
## `types`
D
Douwe Maan 已提交
209

210 211 212
CAUTION: **Deprecated:**
`types` is deprecated, and could be removed in one of the future releases.
Use [stages](#stages) instead.
213

214 215 216 217
## `script`

`script` is the only required keyword that a job needs. It's a shell script
which is executed by the Runner. For example:
D
Douwe Maan 已提交
218 219 220 221 222 223 224

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

This parameter can also contain several commands using an array:
225

D
Douwe Maan 已提交
226 227 228 229 230 231 232
```yaml
job:
  script:
    - uname -a
    - bundle exec rspec
```

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

239
## `only` and `except` (simplified)
D
Douwe Maan 已提交
240

241 242
`only` and `except` are two parameters that set a job policy to limit when
jobs are created:
D
Douwe Maan 已提交
243

244
1. `only` defines the names of branches and tags for which the job will run.
245
2. `except` defines the names of branches and tags for which the job will
246
    **not** run.
247

248
There are a few rules that apply to the usage of job policy:
249 250 251 252 253 254 255

* `only` and `except` are inclusive. If both `only` and `except` are defined
   in a job specification, the ref is filtered by `only` and `except`.
* `only` and `except` allow the use of regular expressions.
* `only` and `except` allow to specify a repository path to filter jobs for
   forks.

256 257 258 259 260 261 262 263 264 265 266 267 268 269
In addition, `only` and `except` allow the use of special keywords:

| **Value** |  **Description**  |
| --------- |  ---------------- |
| `branches`  | When a branch is pushed.  |
| `tags`      | When a tag is pushed.  |
| `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**). |

270
In the example below, `job` will run only for refs that start with `issue-`,
271
whereas all branches will be skipped:
D
Douwe Maan 已提交
272 273 274

```yaml
job:
275
  # use regexp
D
Douwe Maan 已提交
276
  only:
277 278
    - /^issue-.*$/
  # use special keyword
D
Douwe Maan 已提交
279
  except:
280
    - branches
D
Douwe Maan 已提交
281 282
```

283
In this example, `job` will run only for refs that are tagged, or if a build is
284
explicitly requested via an API trigger or a [Pipeline Schedule][schedules]:
285 286 287 288 289 290 291

```yaml
job:
  # use special keywords
  only:
    - tags
    - triggers
292
    - schedules
293 294
```

295 296
The repository path can be used to have jobs executed only for the parent
repository and not forks:
297 298 299 300 301 302 303 304

```yaml
job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce
```
305 306 307

The above example will run `job` for all branches on `gitlab-org/gitlab-ce`,
except master.
308

309
## `only` and `except` (complex)
310

311
> `refs` and `kubernetes` policies introduced in GitLab 10.0
312

313
> `variables` policy introduced in 10.7
314

315 316 317
CAUTION: **Warning:**
This an _alpha_ feature, and it it subject to change at any time without
prior notice!
318

319 320
Since GitLab 10.0 it is possible to define a more elaborate only/except job
policy configuration.
321 322

GitLab now supports both, simple and complex strategies, so it is possible to
323
use an array and a hash configuration scheme.
324

325 326 327 328 329 330 331 332
Three keys are now available: `refs`, `kubernetes` and `variables`.
Refs strategy equals to simplified only/except configuration, whereas
kubernetes strategy accepts only `active` keyword.

`variables` keyword is used to define variables expressions. In other words
you can use predefined variables / secret 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.
333 334 335 336 337 338 339 340 341 342 343 344 345 346

See the example below. Job is going to be created only when pipeline has been
scheduled or runs for a `master` branch, and only if kubernetes service is
active in the project.

```yaml
job:
  only:
    refs:
      - master
      - schedules
    kubernetes: active
```

347 348 349 350 351 352 353 354 355 356 357 358
Example of using variables expressions:

```yaml
deploy:
  only:
    refs:
      - branches
    variables:
      - $RELEASE == "staging"
      - $STAGING
```

359
Learn more about variables expressions on [a separate page][variables-expressions].
360

361
## `tags`
D
Douwe Maan 已提交
362

363
`tags` is used to select specific Runners from the list of all Runners that are
364
allowed to run this project.
D
Douwe Maan 已提交
365

366
During the registration of a Runner, you can specify the Runner's tags, for
367 368
example `ruby`, `postgres`, `development`.

369
`tags` allow you to run jobs with Runners that have the specified tags
370 371 372
assigned to them:

```yaml
D
Douwe Maan 已提交
373 374 375 376 377 378
job:
  tags:
    - ruby
    - postgres
```

379
The specification above, will make sure that `job` is built by a Runner that
380
has both `ruby` AND `postgres` tags defined.
D
Douwe Maan 已提交
381

382
## `allow_failure`
383

384 385
`allow_failure` is used when you want to allow a job to fail without impacting
the rest of the CI suite. Failed jobs don't contribute to the commit status.
386

387
When enabled and the job fails, the pipeline will be successful/green for all
388
intents and purposes, but a "CI build passed with warnings" message  will be
389 390
displayed on the merge request or commit or job page. This is to be used by
jobs that are allowed to fail, but where failure indicates some other (manual)
391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414
steps should be taken elsewhere.

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:
  - execute_script_that_will_fail
  allow_failure: true

job2:
  stage: test
  script:
  - execute_script_that_will_succeed

job3:
  stage: deploy
  script:
  - deploy_to_staging
```

415
## `when`
416 417 418

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

R
Robert Speicher 已提交
420 421
`when` can be set to one of the following values:

422
1. `on_success` - execute job only when all jobs from prior stages
423
    succeed. This is the default.
424
1. `on_failure` - execute job only when at least one job from prior stages
425
    fails.
426 427
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
428
    [manual actions](#when-manual) below.
429

430 431 432
For example:

```yaml
433 434 435 436 437 438 439
stages:
- build
- cleanup_build
- test
- deploy
- cleanup

440
build_job:
441 442 443 444
  stage: build
  script:
  - make build

445
cleanup_build_job:
446 447 448 449 450
  stage: cleanup_build
  script:
  - cleanup build when failed
  when: on_failure

451
test_job:
452 453 454 455
  stage: test
  script:
  - make test

456
deploy_job:
457 458 459
  stage: deploy
  script:
  - make deploy
460
  when: manual
461

462
cleanup_job:
463 464
  stage: cleanup
  script:
465
  - cleanup after jobs
466 467 468 469
  when: always
```

The above script will:
470

471 472 473 474
1. Execute `cleanup_build_job` only when `build_job` fails.
2. Always execute `cleanup_job` as the last step in pipeline regardless of
   success or failure.
3. Allow you to manually execute `deploy_job` from GitLab's UI.
475

476
### `when:manual`
477

478 479 480 481
> **Notes:**
- Introduced in GitLab 8.10.
- Blocking manual actions were introduced in GitLab 9.0.
- Protected actions were introduced in GitLab 9.2.
482

483 484 485 486 487
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
[environments documentation][env-manual].
488

489 490
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
491
possible to resume execution of the pipeline when someone executes a blocking
492
manual action by clicking a _play_ button.
493

494
When a pipeline is blocked, it will not be merged if Merge When Pipeline Succeeds
495 496 497 498 499
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`.

500 501 502
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.
503

504 505 506 507 508
Manual actions are considered to be write actions, so permissions for
[protected branches](../../user/project/protected_branches.md) are used when
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, user needs to
have ability to merge to this branch.
509

510
## `environment`
511

512 513 514 515 516
>
**Notes:**
- Introduced in GitLab 8.9.
- You can read more about environments and find more examples in the
  [documentation about environments][environment].
517

518
`environment` is used to define that a job deploys to a specific environment.
M
Mark Pundsack 已提交
519 520
If `environment` is specified and no environment under that name exists, a new
one will be created automatically.
521

522
In its simplest form, the `environment` keyword can be defined like:
523

524
```yaml
525 526 527
deploy to production:
  stage: deploy
  script: git push production HEAD:master
528 529
  environment:
    name: production
530 531
```

532 533 534
In the above example, the `deploy to production` job will be marked as doing a
deployment to the `production` environment.

535
### `environment:name`
536

537 538 539 540 541 542
>
**Notes:**
- 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.
543 544 545
- 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`.
546

547 548 549 550 551 552 553 554 555 556 557 558 559 560 561
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.

562 563 564 565
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`:

566
```yaml
567 568 569 570 571 572 573
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
```

574
### `environment:url`
575

576 577 578 579 580
>
**Notes:**
- 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`.
581 582 583
- 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`.
584 585 586 587 588 589 590 591

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

592
```yaml
593 594 595 596 597 598 599 600
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
    url: https://prod.example.com
```

601
### `environment:on_stop`
602

603 604 605 606 607 608
>
**Notes:**
- [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.
609 610 611 612 613 614 615

Closing (stoping) environments can be achieved with the `on_stop` keyword defined under
`environment`. It declares a different job that runs in order to close
the environment.

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

616
### `environment:action`
617 618 619 620 621 622

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

623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702
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
set it up to `manual` so it will need a [manual action](#manual-actions) via
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

### Dynamic environments

>
**Notes:**
- [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`.

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

## `cache`

>
**Notes:**
- 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.
- From GitLab 9.2, caches are restored before [artifacts](#artifacts).

703 704 705 706
TIP: **Learn more:**
Read how caching works and find out some good practices in the
[caching dependencies documentation](../caching/index.md).

707 708 709 710 711 712 713
`cache` is used to specify a list of files and directories which should be
cached between jobs. You can only use paths that are within the project
workspace.

If `cache` is defined outside the scope of jobs, it means it is set
globally and all jobs will use that definition.

714
### `cache:paths`
715

716 717
Use the `paths` directive to choose which files or directories will be cached.
Wildcards can be used as well.
718

719
Cache all files in `binaries` that end in `.apk` and the `.config` file:
720 721 722 723 724 725

```yaml
rspec:
  script: test
  cache:
    paths:
726 727
    - binaries/*.apk
    - .config
728 729 730 731 732 733 734 735 736 737 738 739 740
```

Locally defined cache overrides globally defined options. The following `rspec`
job will cache only `binaries/`:

```yaml
cache:
  paths:
  - my/files

rspec:
  script: test
  cache:
741
    key: rspec
742 743 744 745
    paths:
    - binaries/
```

746 747 748 749
Note that since cache is shared between jobs, if you're using different
paths for different jobs, you should also set a different **cache:key**
otherwise cache content can be overwritten.

750 751 752 753
### `cache:key`

> Introduced in GitLab Runner v1.0.0.

754 755 756
Since the cache is shared between jobs, if you're using different
paths for different jobs, you should also set a different `cache:key`
otherwise cache content can be overwritten.
757

758 759 760 761
The `key` directive allows you to define the affinity of caching between jobs,
allowing to have a single cache for all jobs, cache per-job, cache per-branch
or any other way that fits your workflow. This way, you can fine tune caching,
allowing you to cache data between different jobs or even different branches.
762 763

The `cache:key` variable can use any of the
764 765 766
[predefined variables](../variables/README.md), and the default key, if not
set, is just literal `default` which means everything is shared between each
pipelines and jobs by default, starting from GitLab 9.0.
767 768 769 770 771

NOTE: **Note:**
The `cache:key` variable cannot contain the `/` character, or the equivalent
URI-encoded `%2F`; a value made only of dots (`.`, `%2E`) is also forbidden.

772
For example, to enable per-branch caching:
773 774 775 776

```yaml
cache:
  key: "$CI_COMMIT_REF_SLUG"
777 778
  paths:
  - binaries/
779 780
```

781 782
If you use **Windows Batch** to run your shell scripts you need to replace
`$` with `%`:
783 784 785

```yaml
cache:
786
  key: "%CI_COMMIT_REF_SLUG%"
787 788
  paths:
  - binaries/
789 790
```

791 792
If you use **Windows PowerShell** to run your shell scripts you need to replace
`$` with `$env:`:
793 794 795

```yaml
cache:
796
  key: "$env:CI_COMMIT_REF_SLUG"
797 798
  paths:
  - binaries/
799 800
```

801 802 803 804
### `cache:untracked`

Set `untracked: true` to cache all files that are untracked in your Git
repository:
805 806

```yaml
807 808 809 810
rspec:
  script: test
  cache:
    untracked: true
811 812
```

813
Cache all Git untracked files and files in `binaries`:
814 815

```yaml
816 817 818 819 820 821
rspec:
  script: test
  cache:
    untracked: true
    paths:
    - binaries/
822 823
```

824
### `cache:policy`
825

826
> Introduced in GitLab 9.4.
827

828 829 830 831
The default behaviour of a caching job is to download the files at the start of
execution, and to re-upload them at the end. This allows any changes made by the
job to be persisted for future runs, and is known as the `pull-push` cache
policy.
832

833 834 835 836
If you know the job doesn't alter the cached files, you can skip the upload step
by setting `policy: pull` in the job specification. Typically, this would be
twinned with an ordinary cache job at an earlier stage to ensure the cache
is updated from time to time:
837

838 839 840 841
```yaml
stages:
  - setup
  - test
842

843 844 845 846 847 848 849 850
prepare:
  stage: setup
  cache:
    key: gems
    paths:
      - vendor/bundle
  script:
    - bundle install --deployment
851

852 853 854 855 856 857 858 859 860
rspec:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - bundle exec rspec ...
861 862
```

863 864 865
This helps to speed up job execution and reduce load on the cache server,
especially when you have a large number of cache-using jobs executing in
parallel.
866

867 868 869
Additionally, if you have a job that unconditionally recreates the cache without
reference to its previous contents, you can use `policy: push` in that job to
skip the download step.
870

871
## `artifacts`
K
Kamil Trzcinski 已提交
872

873
>
874 875 876
**Notes:**
- Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
- Windows support was added in GitLab Runner v.1.0.0.
877
- From GitLab 9.2, caches are restored before artifacts.
878
- Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart).
879
- Job artifacts are only collected for successful jobs by default.
880

881
`artifacts` is used to specify a list of files and directories which should be
882
attached to the job after success.
883

884 885
The artifacts will be sent to GitLab after the job finishes successfully and will
be available for download in the GitLab UI.
886

887
[Read more about artifacts.](../../user/project/pipelines/job_artifacts.md)
888

889
### `artifacts:paths`
890

891 892
You can only use paths that are within the project workspace. To pass artifacts
between different jobs, see [dependencies](#dependencies).
893

894
Send all files in `binaries` and `.config`:
K
Kamil Trzcinski 已提交
895

896 897 898 899
```yaml
artifacts:
  paths:
  - binaries/
900
  - .config
901
```
K
Kamil Trzcinski 已提交
902

903 904 905 906 907 908 909 910 911
To disable artifact passing, define the job with empty [dependencies](#dependencies):

```yaml
job:
  stage: build
  script: make build
  dependencies: []
```

912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933
You may want to create artifacts only for tagged releases to avoid filling the
build server storage with temporary build artifacts.

Create artifacts only for tags (`default-job` will not create artifacts):

```yaml
default-job:
  script:
    - mvn test -U
  except:
    - tags

release-job:
  script:
    - mvn package -U
  artifacts:
    paths:
    - target/*.war
  only:
    - tags
```

934
### `artifacts:name`
935

936
> Introduced in GitLab 8.6 and GitLab Runner v1.1.0.
937

A
Achilleas Pipinellis 已提交
938
The `name` directive allows you to define the name of the created artifacts
939
archive. That way, you can have a unique name for every archive which could be
A
Achilleas Pipinellis 已提交
940 941
useful when you'd like to download the archive from GitLab. The `artifacts:name`
variable can make use of any of the [predefined variables](../variables/README.md).
942
The default name is `artifacts`, which becomes `artifacts.zip` when downloaded.
943

944
To create an archive with a name of the current job:
945 946 947 948

```yaml
job:
  artifacts:
Z
Z.J. van de Weg 已提交
949
    name: "$CI_JOB_NAME"
950 951
    paths:
    - binaries/
952 953
```

A
Achilleas Pipinellis 已提交
954
To create an archive with a name of the current branch or tag including only
955
the binaries directory:
956 957 958 959

```yaml
job:
   artifacts:
Z
Z.J. van de Weg 已提交
960
     name: "$CI_COMMIT_REF_NAME"
961 962
    paths:
    - binaries/
963 964
```

965
To create an archive with a name of the current job and the current branch or
966
tag including only the binaries directory:
967 968 969 970

```yaml
job:
  artifacts:
J
John Burak 已提交
971
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
972 973
    paths:
    - binaries/
974 975
```

A
Achilleas Pipinellis 已提交
976
To create an archive with a name of the current [stage](#stages) and branch name:
977 978 979 980

```yaml
job:
  artifacts:
J
John Burak 已提交
981
    name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
982 983
    paths:
    - binaries/
984 985
```

A
Achilleas Pipinellis 已提交
986 987
---

988 989 990 991 992 993
If you use **Windows Batch** to run your shell scripts you need to replace
`$` with `%`:

```yaml
job:
  artifacts:
J
John Burak 已提交
994
    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
995 996
    paths:
    - binaries/
997 998
```

999 1000 1001 1002 1003 1004
If you use **Windows PowerShell** to run your shell scripts you need to replace
`$` with `$env:`:

```yaml
job:
  artifacts:
J
John Burak 已提交
1005
    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032
    paths:
    - binaries/
```

### `artifacts:untracked`

`artifacts:untracked` is used to add all Git untracked files as artifacts (along
to the paths defined in `artifacts:paths`).

NOTE: **Note:**
To exclude the folders/files which should not be a part of `untracked` just
add them to `.gitignore`.

Send all Git untracked files:

```yaml
artifacts:
  untracked: true
```

Send all Git untracked files and files in `binaries`:

```yaml
artifacts:
  untracked: true
  paths:
  - binaries/
1033 1034
```

1035
### `artifacts:when`
1036

1037
> Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
1038

1039
`artifacts:when` is used to upload artifacts on job failure or despite the
1040 1041 1042 1043
failure.

`artifacts:when` can be set to one of the following values:

1044 1045 1046
1. `on_success` - upload artifacts only when the job succeeds. This is the default.
1. `on_failure` - upload artifacts only when the job fails.
1. `always` - upload artifacts regardless of the job status.
1047

1048
To upload artifacts only when job fails:
1049 1050 1051 1052 1053 1054 1055

```yaml
job:
  artifacts:
    when: on_failure
```

1056
### `artifacts:expire_in`
1057

1058
> Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
1059

1060 1061 1062 1063 1064
`expire_in` allows you to specify how long artifacts should live before they
expire and therefore deleted, counting from the time they are uploaded and
stored on GitLab. If the expiry time is not defined, it defaults to the
[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration)
(30 days by default, forever on GitLab.com).
1065

1066
You can use the **Keep** button on the job page to override expiration and
1067
keep artifacts forever.
1068

1069 1070
After their expiry, artifacts are deleted hourly by default (via a cron job),
and are not accessible anymore.
1071

1072
The value of `expire_in` is an elapsed time. Examples of parsable values:
1073

1074 1075 1076 1077 1078 1079 1080
- '3 mins 4 sec'
- '2 hrs 20 min'
- '2h20min'
- '6 mos 1 day'
- '47 yrs 6 mos and 4d'
- '3 weeks and 2 days'

1081
To expire artifacts 1 week after being uploaded:
1082 1083 1084 1085 1086 1087 1088

```yaml
job:
  artifacts:
    expire_in: 1 week
```

1089
## `dependencies`
1090

1091
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
1092

1093
This feature should be used in conjunction with [`artifacts`](#artifacts) and
1094
allows you to define the artifacts to pass between different jobs.
1095

1096
Note that `artifacts` from all previous [stages](#stages) are passed by default.
1097

1098
To use this feature, define `dependencies` in context of the job and pass
1099 1100
a list of all previous jobs from which the artifacts should be downloaded.
You can only define jobs from stages that are executed before the current one.
S
Shinya Maeda 已提交
1101
An error will be shown if you define jobs from the current stage or next ones.
1102
Defining an empty array will skip downloading any artifacts for that job.
F
Fabio Busatto 已提交
1103 1104
The status of the previous job is not considered when using `dependencies`, so
if it failed or it is a manual job that was not run, no error occurs.
1105 1106

---
1107

1108 1109 1110 1111 1112
In the following example, we define two jobs with artifacts, `build:osx` and
`build:linux`. When the `test:osx` is executed, the artifacts from `build:osx`
will be downloaded and extracted in the context of the build. The same happens
for `test:linux` and artifacts from `build:linux`.

1113
The job `deploy` will download artifacts from all previous jobs because of
1114
the [stage](#stages) precedence:
1115

1116
```yaml
1117 1118
build:osx:
  stage: build
1119
  script: make build:osx
1120 1121 1122
  artifacts:
    paths:
    - binaries/
1123

1124 1125
build:linux:
  stage: build
1126
  script: make build:linux
1127 1128 1129 1130 1131 1132
  artifacts:
    paths:
    - binaries/

test:osx:
  stage: test
1133
  script: make test:osx
1134 1135 1136 1137 1138
  dependencies:
  - build:osx

test:linux:
  stage: test
1139
  script: make test:linux
1140 1141 1142 1143 1144
  dependencies:
  - build:linux

deploy:
  stage: deploy
1145
  script: make deploy
1146 1147
```

1148
### When a dependent job will fail
1149 1150

> Introduced in GitLab 10.3.
S
Shinya Maeda 已提交
1151

1152 1153 1154 1155
If the artifacts of the job that is set as a dependency have been
[expired](#artifacts-expire_in) or
[erased](../../user/project/pipelines/job_artifacts.md#erasing-artifacts), then
the dependent job will fail.
S
Shinya Maeda 已提交
1156

1157 1158 1159 1160
NOTE: **Note:**
You can ask your administrator to
[flip this switch](../../administration/job_artifacts.md#validation-for-dependencies)
and bring back the old behavior.
S
Shinya Maeda 已提交
1161

1162
## `coverage`
1163

1164
> [Introduced][ce-7447] in GitLab 8.17.
1165

1166 1167
`coverage` allows you to configure how code coverage will be extracted from the
job output.
1168

1169 1170 1171 1172 1173 1174
Regular expressions are the only valid kind of value expected here. So, using
surrounding `/` is mandatory in order to consistently and explicitly represent
a regular expression string. You must escape special characters if you want to
match them literally.

A simple example:
1175 1176 1177

```yaml
job1:
1178
  script: rspec
M
Max Raab 已提交
1179
  coverage: '/Code coverage: \d+\.\d+/'
1180 1181
```

1182
## `retry`
1183

G
George Tsiolis 已提交
1184
> [Introduced][ce-12909] in GitLab 9.5.
1185 1186 1187 1188 1189 1190 1191

`retry` allows you to configure how many times a job is going to be retried in
case of a failure.

When a job fails, and has `retry` configured it is going to be processed again
up to the amount of times specified by the `retry` keyword.

1192
If `retry` is set to 2, and a job succeeds in a second run (first retry), it won't be retried
1193
again. `retry` value has to be a positive integer, equal or larger than 0, but
1194
lower or equal to 2 (two retries maximum, three runs in total).
1195 1196 1197 1198 1199 1200

A simple example:

```yaml
test:
  script: rspec
1201
  retry: 2
1202 1203
```

1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246
## `variables`

> Introduced in GitLab Runner v0.5.0.

NOTE: **Note:**
Integers (as well as strings) are legal both for variable's name and value.
Floats are not legal and cannot be used.

GitLab CI/CD allows you to define variables inside `.gitlab-ci.yml` that are
then passed in the job environment. They can be set globally and per-job.
When the `variables` keyword is used on a job level, it overrides the global
YAML variables and predefined ones.

They are stored in the Git repository and are meant to store non-sensitive
project configuration, for example:

```yaml
variables:
  DATABASE_URL: "postgres://postgres@postgres/my_database"
```

These variables can be later used in all executed commands and scripts.
The YAML-defined variables are also set to all created service containers,
thus allowing to fine tune them.

To turn off global defined variables in a specific job, define an empty hash:

```yaml
job_name:
  variables: {}
```

Except for the user defined variables, there are also the ones [set up by the
Runner itself](../variables/README.md#predefined-variables-environment-variables).
One example would be `CI_COMMIT_REF_NAME` which has the value of
the branch or tag name for which project is built. Apart from the variables
you can set in `.gitlab-ci.yml`, there are also the so called
[secret variables](../variables/README.md#secret-variables)
which can be set in GitLab's UI.

[Learn more about variables and their priority.][variables]

### Git strategy
M
Mark Pundsack 已提交
1247

N
Nick Thomas 已提交
1248 1249 1250 1251 1252
> Introduced in GitLab 8.9 as an experimental feature.  May change or be removed
  completely in future releases. `GIT_STRATEGY=none` requires GitLab Runner
  v1.7+.

You can set the `GIT_STRATEGY` used for getting recent application code, either
1253 1254
globally or per-job in the [`variables`](#variables) section. If left
unspecified, the default from project settings will be used.
M
Mark Pundsack 已提交
1255

N
Nick Thomas 已提交
1256 1257 1258 1259
There are three possible values: `clone`, `fetch`, and `none`.

`clone` is the slowest option. It clones the repository from scratch for every
job, ensuring that the project workspace is always pristine.
M
Mark Pundsack 已提交
1260

1261
```yaml
M
Mark Pundsack 已提交
1262 1263 1264 1265
variables:
  GIT_STRATEGY: clone
```

N
Nick Thomas 已提交
1266 1267 1268
`fetch` is faster as it re-uses the project workspace (falling back to `clone`
if it doesn't exist). `git clean` is used to undo any changes made by the last
job, and `git fetch` is used to retrieve commits made since the last job ran.
M
Mark Pundsack 已提交
1269

1270
```yaml
M
Mark Pundsack 已提交
1271 1272 1273 1274
variables:
  GIT_STRATEGY: fetch
```

N
Nick Thomas 已提交
1275 1276 1277 1278 1279 1280
`none` also re-uses the project workspace, but skips all Git operations
(including GitLab Runner's pre-clone script, if present). It is mostly useful
for jobs that operate exclusively on artifacts (e.g., `deploy`). Git repository
data may be present, but it is certain to be out of date, so you should only
rely on files brought into the project workspace from cache or artifacts.

1281
```yaml
N
Nick Thomas 已提交
1282 1283 1284 1285
variables:
  GIT_STRATEGY: none
```

1286
### Git submodule strategy
1287 1288 1289 1290

> Requires GitLab Runner v1.10+.

The `GIT_SUBMODULE_STRATEGY` variable is used to control if / how Git
1291 1292
submodules are included when fetching the code before a build. You can set them
globally or per-job in the [`variables`](#variables) section.
1293

1294
There are three possible values: `none`, `normal`, and `recursive`:
1295 1296 1297 1298 1299 1300

- `none` means that submodules will not be included when fetching the project
  code. This is the default, which matches the pre-v1.10 behavior.

- `normal` means that only the top-level submodules will be included. It is
  equivalent to:
1301

1302
    ```
1303 1304
    git submodule sync
    git submodule update --init
1305 1306 1307 1308
    ```

- `recursive` means that all submodules (including submodules of submodules)
  will be included. It is equivalent to:
1309

1310
    ```
1311 1312
    git submodule sync --recursive
    git submodule update --init --recursive
1313 1314 1315 1316
    ```

Note that for this feature to work correctly, the submodules must be configured
(in `.gitmodules`) with either:
1317

1318 1319 1320 1321
- the HTTP(S) URL of a publicly-accessible repository, or
- a relative path to another repository on the same GitLab server. See the
  [Git submodules](../git_submodules.md) documentation.

1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349
### Git checkout

> Introduced in GitLab Runner 9.3

The `GIT_CHECKOUT` variable can be used when the `GIT_STRATEGY` is set to either
`clone` or `fetch` to specify whether a `git checkout` should be run. If not
specified, it defaults to true. You can set them globally or per-job in the
[`variables`](#variables) section.

If set to `false`, the Runner will:

- when doing `fetch` - update the repository and leave working copy on
  the current revision,
- when doing `clone` - clone the repository and leave working copy on the
  default branch.

Having this setting set to `true` will mean that for both `clone` and `fetch`
strategies the Runner will checkout the working copy to a revision related
to the CI pipeline:

```yaml
variables:
  GIT_STRATEGY: clone
  GIT_CHECKOUT: "false"
script:
  - git checkout master
  - git merge $CI_BUILD_REF_NAME
```
1350

1351
### Job stages attempts
1352 1353 1354

> Introduced in GitLab, it requires GitLab Runner v1.9+.

1355
You can set the number for attempts the running job will try to execute each
1356 1357
of the following stages:

1358 1359 1360 1361 1362
| Variable                        | Description |
|-------------------------------- |-------------|
| **GET_SOURCES_ATTEMPTS**        | Number of attempts to fetch sources running a job |
| **ARTIFACT_DOWNLOAD_ATTEMPTS**  | Number of attempts to download artifacts running a job |
| **RESTORE_CACHE_ATTEMPTS**      | Number of attempts to restore the cache running a job |
1363 1364 1365 1366 1367

The default is one single attempt.

Example:

1368
```yaml
1369
variables:
1370
  GET_SOURCES_ATTEMPTS: 3
1371 1372
```

1373
You can set them globally or per-job in the [`variables`](#variables) section.
1374

1375
### Shallow cloning
M
Mark Pundsack 已提交
1376

1377
> Introduced in GitLab 8.9 as an experimental feature. May change in future
M
Mark Pundsack 已提交
1378
releases or be removed completely.
M
Mark Pundsack 已提交
1379 1380

You can specify the depth of fetching and cloning using `GIT_DEPTH`. This allows
M
Mark Pundsack 已提交
1381 1382 1383
shallow cloning of the repository which can significantly speed up cloning for
repositories with a large number of commits or old, large binaries. The value is
passed to `git fetch` and `git clone`.
M
Mark Pundsack 已提交
1384

M
Mark Pundsack 已提交
1385
>**Note:**
1386 1387
If you use a depth of 1 and have a queue of jobs or retry
jobs, jobs may fail.
M
Mark Pundsack 已提交
1388

1389 1390 1391 1392
Since Git fetching and cloning is based on a ref, such as a branch name, Runners
can't clone a specific commit SHA. If there are multiple jobs in the queue, or
you are retrying an old job, the commit to be tested needs to be within the
Git history that is cloned. Setting too small a value for `GIT_DEPTH` can make
M
Mark Pundsack 已提交
1393
it impossible to run these old commits. You will see `unresolved reference` in
1394
job logs. You should then reconsider changing `GIT_DEPTH` to a higher value.
M
Mark Pundsack 已提交
1395

1396 1397
Jobs that rely on `git describe` may not work correctly when `GIT_DEPTH` is
set since only part of the Git history is present.
M
Mark Pundsack 已提交
1398 1399

To fetch or clone only the last 3 commits:
1400 1401

```yaml
M
Mark Pundsack 已提交
1402
variables:
M
Mark Pundsack 已提交
1403
  GIT_DEPTH: "3"
M
Mark Pundsack 已提交
1404 1405
```

1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416
You can set it globally or per-job in the [`variables`](#variables) section.

## Special YAML features

It's possible to use special YAML features like anchors (`&`), aliases (`*`)
and map merging (`<<`), which will allow you to greatly reduce the complexity
of `.gitlab-ci.yml`.

Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/).

### Hidden keys (jobs)
A
Achilleas Pipinellis 已提交
1417

1418
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
A
Achilleas Pipinellis 已提交
1419

1420 1421 1422 1423 1424 1425 1426 1427
If you want to temporarily 'disable' a job, rather than commenting out all the
lines where the job is defined:

```
#hidden_job:
#  script:
#    - run test
```
A
Achilleas Pipinellis 已提交
1428

1429 1430
you can instead start its name with a dot (`.`) and it will not be processed by
GitLab CI. In the following example, `.hidden_job` will be ignored:
A
Achilleas Pipinellis 已提交
1431 1432

```yaml
1433
.hidden_job:
A
Achilleas Pipinellis 已提交
1434
  script:
1435
    - run test
A
Achilleas Pipinellis 已提交
1436 1437
```

1438 1439 1440
Use this feature to ignore jobs, or use the
[special YAML features](#special-yaml-features) and transform the hidden keys
into templates.
1441

1442 1443
### Anchors

1444
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
1445

1446
YAML has a handy feature called 'anchors', which lets you easily duplicate
1447
content across your document. Anchors can be used to duplicate/inherit
1448
properties, and is a perfect example to be used with [hidden keys](#hidden-keys-jobs)
1449 1450 1451 1452 1453
to provide templates for your jobs.

The following example uses anchors and map merging. It will create two jobs,
`test1` and `test2`, that will inherit the parameters of `.job_template`, each
having their own custom `script` defined:
1454 1455

```yaml
1456
.job_template: &job_definition  # Hidden key that defines an anchor named 'job_definition'
1457 1458 1459 1460 1461 1462
  image: ruby:2.1
  services:
    - postgres
    - redis

test1:
1463
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
1464
  script:
1465
    - test1 project
1466 1467

test2:
1468
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
1469
  script:
1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498
    - test2 project
```

`&` sets up the name of the anchor (`job_definition`), `<<` means "merge the
given hash into the current one", and `*` includes the named anchor
(`job_definition` again). The expanded version looks like this:

```yaml
.job_template:
  image: ruby:2.1
  services:
    - postgres
    - redis

test1:
  image: ruby:2.1
  services:
    - postgres
    - redis
  script:
    - test1 project

test2:
  image: ruby:2.1
  services:
    - postgres
    - redis
  script:
    - test2 project
1499 1500
```

1501 1502 1503 1504
Let's see another one example. This time we will use anchors to define two sets
of services. This will create two jobs, `test:postgres` and `test:mysql`, that
will share the `script` directive defined in `.job_template`, and the `services`
directive defined in `.postgres_services` and `.mysql_services` respectively:
1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515

```yaml
.job_template: &job_definition
  script:
    - test project

.postgres_services:
  services: &postgres_definition
    - postgres
    - ruby

1516
.mysql_services:
1517 1518 1519 1520 1521
  services: &mysql_definition
    - mysql
    - ruby

test:postgres:
A
Achilleas Pipinellis 已提交
1522
  <<: *job_definition
1523 1524 1525
  services: *postgres_definition

test:mysql:
A
Achilleas Pipinellis 已提交
1526
  <<: *job_definition
1527 1528 1529
  services: *mysql_definition
```

1530
The expanded version looks like this:
1531

1532 1533 1534 1535
```yaml
.job_template:
  script:
    - test project
1536

1537 1538 1539 1540
.postgres_services:
  services:
    - postgres
    - ruby
1541

1542 1543 1544 1545 1546 1547
.mysql_services:
  services:
    - mysql
    - ruby

test:postgres:
1548
  script:
1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559
    - test project
  services:
    - postgres
    - ruby

test:mysql:
  script:
    - test project
  services:
    - mysql
    - ruby
1560 1561
```

1562
You can see that the hidden keys are conveniently used as templates.
1563

1564 1565 1566 1567 1568 1569 1570
## Triggers

Triggers can be used to force a rebuild of a specific branch, tag or commit,
with an API call.

[Read more in the triggers documentation.](../triggers/README.md)

1571
## Skipping jobs
1572

1573 1574
If your commit message contains `[ci skip]` or `[skip ci]`, using any
capitalization, the commit will be created but the pipeline will be skipped.
1575

D
Douwe Maan 已提交
1576
## Validate the .gitlab-ci.yml
1577

1578
Each instance of GitLab CI has an embedded debug tool called Lint, which validates the
1579
content of your `.gitlab-ci.yml` files. You can find the Lint under the page `ci/lint` of your
T
Takuya Noguchi 已提交
1580
project namespace (e.g, `http://gitlab-example.com/gitlab-org/project-123/-/ci/lint`)
D
Douwe Maan 已提交
1581

1582 1583 1584 1585 1586
## Using reserved keywords

If you get validation error when using specific values (e.g., `true` or `false`),
try to quote them, or change them to a different form (e.g., `/bin/true`).

A
Achilleas Pipinellis 已提交
1587 1588 1589 1590 1591
## Examples

Visit the [examples README][examples] to see a list of examples using GitLab
CI with various languages.

1592
[env-manual]: ../environments.md#manually-deploying-to-environments
A
Achilleas Pipinellis 已提交
1593
[examples]: ../examples/README.md
1594 1595
[ce-6323]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6323
[environment]: ../environments.md
1596 1597
[ce-6669]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6669
[variables]: ../variables/README.md
1598
[ce-7983]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7983
1599
[ce-7447]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7447
G
George Tsiolis 已提交
1600
[ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909
1601
[schedules]: ../../user/project/pipelines/schedules.md
1602
[variables-expressions]: ../variables/README.md#variables-expressions