README.md 48.2 KB
Newer Older
1
# Configuration of your jobs with .gitlab-ci.yml
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 10

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

## .gitlab-ci.yml

11 12 13 14 15 16
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.

The YAML file defines a set of jobs with constraints stating when they should
be run. The jobs are defined as top-level elements with a name and always have
17
to contain at least the `script` clause:
18 19 20 21 22 23 24 25 26

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

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

27 28 29 30 31
The above example is the simplest possible CI configuration with two separate
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.
32

33 34 35
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.
36

37 38
The YAML syntax allows for using more complex job specifications than in the
above example:
39 40

```yaml
James Lopez's avatar
James Lopez committed
41
image: ruby:2.1
42 43 44 45
services:
  - postgres

before_script:
frodsan's avatar
frodsan committed
46
  - bundle install
47

48 49 50
after_script:
  - rm secrets

51 52 53 54 55 56 57 58 59 60 61 62 63 64 65
stages:
  - build
  - test
  - deploy

job1:
  stage: build
  script:
    - execute-script-for-job1
  only:
    - master
  tags:
    - docker
```

66
There are a few reserved `keywords` that **cannot** be used as job names:
67

68
| Keyword       | Required | Description |
69
|---------------|----------|-------------|
70 71 72
| image         | no | Use docker image, covered in [Use Docker](../docker/README.md) |
| services      | no | Use docker services, covered in [Use Docker](../docker/README.md) |
| stages        | no | Define build stages |
73
| types         | no | Alias for `stages` (deprecated) |
74
| before_script | no | Define commands that run before each job's script |
75
| after_script  | no | Define commands that run after each job's script |
76 77
| variables     | no | Define build variables |
| cache         | no | Define list of files that should be cached between subsequent runs |
78 79

### image and services
80 81

This allows to specify a custom Docker image and a list of services that can be
82
used for time of the job. The configuration of this feature is covered in
83
[a separate document](../docker/README.md).
84 85

### before_script
86 87

`before_script` is used to define the command that should be run before all
88 89
jobs, including deploy jobs, but after the restoration of artifacts. This can
be an array or a multi-line string.
90

91 92
### after_script

93
> Introduced in GitLab 8.7 and requires Gitlab Runner v1.2
Kamil Trzcinski's avatar
Kamil Trzcinski committed
94

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

98 99 100 101 102 103
> **Note:**
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`.

104
### stages
105

106
`stages` is used to define stages that can be used by jobs.
107 108
The specification of `stages` allows for having flexible multi stage pipelines.

109
The ordering of elements in `stages` defines the ordering of jobs' execution:
110

111 112
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
113
   complete successfully.
114 115

Let's consider the following example, which defines 3 stages:
116 117

```yaml
118 119 120 121 122 123
stages:
  - build
  - test
  - deploy
```

124
1. First, all jobs of `build` are executed in parallel.
125 126
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.
127
1. If all jobs of `deploy` succeed, the commit is marked as `passed`.
128 129
1. If any of the previous jobs fails, the commit is marked as `failed` and no
   jobs of further stage are executed.
130 131 132

There are also two edge cases worth mentioning:

133
1. If no `stages` are defined in `.gitlab-ci.yml`, then the `build`,
134
   `test` and `deploy` are allowed to be used as job's stage by default.
Mark Pundsack's avatar
Mark Pundsack committed
135
2. If a job doesn't specify a `stage`, the job is assigned the `test` stage.
136 137

### types
138

139
> Deprecated, and could be removed in one of the future releases. Use [stages](#stages) instead.
140

141 142 143 144
Alias for [stages](#stages).

### variables

145
> Introduced in GitLab Runner v0.5.0.
146

Mark Pundsack's avatar
Mark Pundsack committed
147
GitLab CI allows you to add variables to `.gitlab-ci.yml` that are set in the
148
job environment. The variables are stored in the Git repository and are meant
Mark Pundsack's avatar
Mark Pundsack committed
149
to store non-sensitive project configuration, for example:
150 151 152 153 154 155

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

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

160
These variables can be later used in all executed commands and scripts.
161
The YAML-defined variables are also set to all created service containers,
162 163
thus allowing to fine tune them. Variables can be also defined on a
[job level](#job-variables).
164

165
Except for the user defined variables, there are also the ones set up by the
166
Runner itself. One example would be `CI_COMMIT_REF_NAME` which has the value of
167 168 169
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
which can be set in GitLab's UI.
170

171
[Learn more about variables.][variables]
172

173 174
### cache

175 176 177 178 179
>
**Notes:**
- Introduced in GitLab Runner v0.7.0.
- Prior to GitLab 9.2, caches were restored after artifacts.
- From GitLab 9.2, caches are restored before artifacts.
180

181
`cache` is used to specify a list of files and directories which should be
182
cached between jobs. You can only use paths that are within the project
183
workspace.
184

185 186
**By default caching is enabled and shared between pipelines and jobs,
starting from GitLab 9.0**
187

Lin Jen-Shin's avatar
Lin Jen-Shin committed
188 189
If `cache` is defined outside the scope of jobs, it means it is set
globally and all jobs will use that definition.
190

191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
Cache all files in `binaries` and `.config`:

```yaml
rspec:
  script: test
  cache:
    paths:
    - binaries/
    - .config
```

Cache all Git untracked files:

```yaml
rspec:
  script: test
  cache:
    untracked: true
```

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

```yaml
rspec:
  script: test
  cache:
    untracked: true
    paths:
    - binaries/
```

Lin Jen-Shin's avatar
Lin Jen-Shin committed
222
Locally defined cache overrides globally defined options. The following `rspec`
223
job will cache only `binaries/`:
224 225

```yaml
226 227
cache:
  paths:
228 229 230 231 232
  - my/files

rspec:
  script: test
  cache:
Lin Jen-Shin's avatar
Lin Jen-Shin committed
233
    key: rspec
234 235
    paths:
    - binaries/
236 237
```

238
Note that since cache is shared between jobs, if you're using different
239
paths for different jobs, you should also set a different **cache:key**
240
otherwise cache content can be overwritten.
Lin Jen-Shin's avatar
Lin Jen-Shin committed
241

Mark Pundsack's avatar
Mark Pundsack committed
242 243
The cache is provided on a best-effort basis, so don't expect that the cache
will be always present. For implementation details, please check GitLab Runner.
244

245 246
#### cache:key

247
> Introduced in GitLab Runner v1.0.0.
248 249 250 251 252

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 you deem proper.

253 254
This allows you to fine tune caching, allowing you to cache data between
different jobs or even different branches.
255

256 257
The `cache:key` variable can use any of the [predefined variables](../variables/README.md).

Lin Jen-Shin's avatar
Lin Jen-Shin committed
258 259 260
The default key is **default** across the project, therefore everything is
shared between each pipelines and jobs by default, starting from GitLab 9.0.

261
>**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.
262

263 264 265
---

**Example configurations**
266 267 268

To enable per-job caching:

269 270
```yaml
cache:
271
  key: "$CI_JOB_NAME"
272 273
  untracked: true
```
274 275 276

To enable per-branch caching:

277 278
```yaml
cache:
279
  key: "$CI_COMMIT_REF_SLUG"
280 281
  untracked: true
```
282 283 284

To enable per-job and per-branch caching:

285 286
```yaml
cache:
287
  key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG"
288 289
  untracked: true
```
290 291 292

To enable per-branch and per-stage caching:

293 294
```yaml
cache:
295
  key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG"
296 297
  untracked: true
```
298

299 300
If you use **Windows Batch** to run your shell scripts you need to replace
`$` with `%`:
301

302 303
```yaml
cache:
304
  key: "%CI_JOB_STAGE%-%CI_COMMIT_REF_SLUG%"
305 306
  untracked: true
```
307

308 309 310 311 312
If you use **Windows PowerShell** to run your shell scripts you need to replace
`$` with `$env:`:

```yaml
cache:
313
  key: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_SLUG"
314 315 316
  untracked: true
```

317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363
### cache:policy

> Introduced in GitLab 9.4.

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.

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:

```yaml
stages:
  - setup
  - test

prepare:
  stage: setup
  cache:
    key: gems
    paths:
      - vendor/bundle
  script:
    - bundle install --deployment

rspec:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - bundle exec rspec ...
```

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.

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.

364
### include
365

366
> Introduced in [GitLab Edition Premium][ee] 10.5.
367

368 369 370 371
Using the `include` keyword, you can allow the inclusion of external YAML files.

In the following example, the content of`.before-script-template.yml` will be
automatically fetched and evaluated along with the content of `.gitlab-ci.yml`:
372 373 374

```yaml
# Content of https://gitlab.com/awesome-project/raw/master/.before-script-template.yml
375

376 377 378 379 380 381 382 383
before_script:
  - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
  - gem install bundler --no-ri --no-rdoc
  - bundle install --jobs $(nproc)  "${FLAGS[@]}"
```

```yaml
# Content of .gitlab-ci.yml
384

385 386 387 388 389 390 391
include: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'

rspec:
  script:
    - bundle exec rspec
```

392 393 394
You can define it either as a single string, or, in case you want to include
more than one files, an array of different values . The following examples
are both valid cases:
395

396 397
```yaml
# Single string
398

399 400
include: '/templates/.after-script-template.yml'
```
401 402

```yaml
403 404 405 406 407
# Array

include:
  - 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
  - '/templates/.after-script-template.yml'
408 409
```

410
---
411

412
`include` supports two types of files:
413

414 415
- **local** to the same repository, referenced by using full paths in the same
  repository, with `/` being the root directory. For example:
416

417 418 419 420
    ```yaml
    # Within the repository
    include: '/templates/.gitlab-ci-template.yml'
    ```
421

422 423 424 425
    NOTE: **Note:**
    You can only use files that are currently tracked by Git on the same branch
    your configuration file is. In other words, when using a **local file**, make
    sure that both `.gitlab-ci.yml` and the local file are on the same branch.
426

427 428
- **remote** in a different location, accessed using HTTP/HTTPS, referenced
  using the full URL. For example:
429

430 431 432
    ```yaml
    include: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'
    ```
433

434
---
435

436 437 438 439
Since external files defined by `include` are evaluated first, the content of
`.gitlab-ci.yml` will always take precedence over the content of the external
files, no matter of the position of the `include` keyword. This allows you to
override values and functions with local definitions. For example:
440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455

```yaml
# Content of https://company.com/autodevops-template.yml

variables:
  POSTGRES_USER: user
  POSTGRES_PASSWORD: testing_password
  POSTGRES_DB: $CI_ENVIRONMENT_SLUG

production:
  stage: production
  script:
    - install_dependencies
    - deploy
  environment:
    name: production
456
    url: https://$CI_PROJECT_PATH_SLUG.$AUTO_DEVOPS_DOMAIN
457
  only:
458
    - master
459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484
```

```yaml
# Content of .gitlab-ci.yml

include: 'https://company.com/autodevops-template.yml'

image: alpine:latest

variables:
  POSTGRES_USER: root
  POSTGRES_PASSWORD: secure_password
  POSTGRES_DB: company_database

stages:
  - build
  - test
  - production

production:
  stage: production
  script:
    - install_dependencies
    - deploy
  environment:
    name: production
485
    url: https://domain.com
486
  only:
487
    - master
488 489
```

490 491 492 493
In this case, the variables `POSTGRES_USER`, `POSTGRES_PASSWORD` and
`POSTGRES_DB` along with the `production` job defined in
`autodevops-template.yml` will be overridden by the ones defined in
`.gitlab-ci.yml`.
494

495
## Jobs
496 497

`.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job
498 499
must have a unique name, which is not one of the keywords mentioned above.
A job is defined by a list of parameters that define the job behavior.
500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516

```yaml
job_name:
  script:
    - rake spec
    - coverage
  stage: test
  only:
    - master
  except:
    - develop
  tags:
    - ruby
    - postgres
  allow_failure: true
```

517
| Keyword       | Required | Description |
518
|---------------|----------|-------------|
519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536
| 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](../../user/project/pipelines/job_artifacts.md) |
| 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 |
537
| retry         | no       | Define how many times a job can be auto-retried in case of a failure |
538 539

### script
540

541
`script` is a shell script which is executed by the Runner. For example:
542 543 544 545 546 547 548

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

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

550 551 552 553 554 555 556
```yaml
job:
  script:
    - uname -a
    - bundle exec rspec
```

557 558 559 560 561
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:
`:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.
562

563
### stage
564

565
`stage` allows to group jobs into different stages. Jobs of the same `stage`
566 567
are executed in `parallel`. For more info about the use of `stage` please check
[stages](#stages).
568

569
### only and except (simplified)
570

571 572
`only` and `except` are two parameters that set a job policy to limit when
jobs are created:
573

574
1. `only` defines the names of branches and tags for which the job will run.
575
2. `except` defines the names of branches and tags for which the job will
576
    **not** run.
577

578
There are a few rules that apply to the usage of job policy:
579 580 581 582 583 584 585

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

586 587 588 589 590 591 592 593 594 595 596 597 598 599
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**). |

600
In the example below, `job` will run only for refs that start with `issue-`,
601
whereas all branches will be skipped:
602 603 604

```yaml
job:
605
  # use regexp
606
  only:
607 608
    - /^issue-.*$/
  # use special keyword
609
  except:
610
    - branches
611 612
```

613
In this example, `job` will run only for refs that are tagged, or if a build is
614
explicitly requested via an API trigger or a [Pipeline Schedule][schedules]:
615 616 617 618 619 620 621

```yaml
job:
  # use special keywords
  only:
    - tags
    - triggers
622
    - schedules
623 624
```

625 626
The repository path can be used to have jobs executed only for the parent
repository and not forks:
627 628 629 630 631 632 633 634

```yaml
job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce
```
635 636 637

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

639 640 641
### only and except (complex)

> Introduced in GitLab 10.0
642

643 644
> This an _alpha_ feature, and it it subject to change at any time without
  prior notice!
645

646 647
Since GitLab 10.0 it is possible to define a more elaborate only/except job
policy configuration.
648 649

GitLab now supports both, simple and complex strategies, so it is possible to
650
use an array and a hash configuration scheme.
651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668

Two keys are now available: `refs` and `kubernetes`. Refs strategy equals to
simplified only/except configuration, whereas kubernetes strategy accepts only
`active` keyword.

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

669
### Job variables
670

671 672 673
It is possible to define job variables using a `variables` keyword on a job
level. It works basically the same way as its [global-level equivalent](#variables),
but allows you to define job-specific variables.
674

675 676
When the `variables` keyword is used on a job level, it overrides the global YAML
job variables and predefined ones. To turn off global defined variables
677
in your job, define an empty hash:
678

679 680
```yaml
job_name:
681
  variables: {}
682 683
```

684
Job variables priority is defined in the [variables documentation][variables].
685

686 687
### tags

688
`tags` is used to select specific Runners from the list of all Runners that are
689
allowed to run this project.
690

691
During the registration of a Runner, you can specify the Runner's tags, for
692 693
example `ruby`, `postgres`, `development`.

694
`tags` allow you to run jobs with Runners that have the specified tags
695 696 697
assigned to them:

```yaml
698 699 700 701 702 703
job:
  tags:
    - ruby
    - postgres
```

704
The specification above, will make sure that `job` is built by a Runner that
705
has both `ruby` AND `postgres` tags defined.
706

707 708
### allow_failure

709 710
`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.
711

712
When enabled and the job fails, the pipeline will be successful/green for all
713
intents and purposes, but a "CI build passed with warnings" message  will be
714 715
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)
716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739
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
```

740
### when
741 742 743

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

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

747
1. `on_success` - execute job only when all jobs from prior stages
748
    succeed. This is the default.
749
1. `on_failure` - execute job only when at least one job from prior stages
750
    fails.
751 752
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
753
    [manual actions](#manual-actions) below.
754

755 756 757
For example:

```yaml
758 759 760 761 762 763 764
stages:
- build
- cleanup_build
- test
- deploy
- cleanup

765
build_job:
766 767 768 769
  stage: build
  script:
  - make build

770
cleanup_build_job:
771 772 773 774 775
  stage: cleanup_build
  script:
  - cleanup build when failed
  when: on_failure

776
test_job:
777 778 779 780
  stage: test
  script:
  - make test

781
deploy_job:
782 783 784
  stage: deploy
  script:
  - make deploy
785
  when: manual
786

787
cleanup_job:
788 789
  stage: cleanup
  script:
790
  - cleanup after jobs
791 792 793 794
  when: always
```

The above script will:
795

796 797 798 799
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.
800 801 802

#### Manual actions

803
> Introduced in GitLab 8.10.
804 805
> Blocking manual actions were introduced in GitLab 9.0
> Protected actions were introduced in GitLab 9.2
806

807 808
Manual actions are a special type of job that are not executed automatically;
they need to be explicitly started by a user. Manual actions can be started
809
from pipeline, build, environment, and deployment views.
810

811
An example usage of manual actions is deployment to production.
812

813 814
Read more at the [environments documentation][env-manual].

815 816 817 818 819 820 821 822 823 824 825 826
Manual actions can be either optional or blocking. Blocking manual action will
block execution of the pipeline at stage this action is defined in. It is
possible to resume execution of the pipeline when someone executes a blocking
manual actions by clicking a _play_ button.

When pipeline is blocked it will not be merged if Merge When Pipeline Succeeds
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`.

827 828 829 830
Optional manual actions have `allow_failure: true` set by default.

**Statuses of optional actions do not contribute to overall pipeline status.**

831 832 833
**Manual actions are considered to be write actions, so permissions for
protected branches 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
834
pipeline is running for, user needs to have ability to merge to this branch.**
835

836 837
### environment

838 839 840 841 842
>
**Notes:**
- Introduced in GitLab 8.9.
- You can read more about environments and find more examples in the
  [documentation about environments][environment].
843

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

848
In its simplest form, the `environment` keyword can be defined like:
849

850
```yaml
851 852 853
deploy to production:
  stage: deploy
  script: git push production HEAD:master
854 855
  environment:
    name: production
856 857
```

858 859 860 861 862
In the above example, the `deploy to production` job will be marked as doing a
deployment to the `production` environment.

#### environment:name

863 864 865 866 867 868
>
**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.
869 870 871
- 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`.
872

873 874 875 876 877 878 879 880 881 882 883 884 885 886 887
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.

888 889 890 891
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`:

892
```yaml
893 894 895 896 897 898 899 900 901
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
```

#### environment:url

902 903 904 905 906
>
**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`.
907 908 909
- 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`.
910 911 912 913 914 915 916 917

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

918
```yaml
919 920 921 922 923 924 925 926 927 928
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
    url: https://prod.example.com
```

#### environment:on_stop

929 930 931 932 933 934
>
**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.
935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979

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.

#### environment:action

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

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`
980 981
- `stage` should be the same as the `review_app` in order for the environment
  to stop automatically when the branch is deleted
982

983 984
#### dynamic environments

985 986 987 988
>
**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.
989 990 991
- 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`.
992

993
For example:
994

995
```yaml
996 997
deploy as review app:
  stage: deploy
998
  script: make deploy
999
  environment:
1000
    name: review/$CI_COMMIT_REF_NAME
1001
    url: https://$CI_ENVIRONMENT_SLUG.example.com/
1002 1003
```

1004
The `deploy as review app` job will be marked as deployment to dynamically
1005
create the `review/$CI_COMMIT_REF_NAME` environment, where `$CI_COMMIT_REF_NAME`
1006 1007 1008 1009
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
1010
`https://review-pow.example.com/`.
1011

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

1015 1016
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
1017
<https://gitlab.com/gitlab-examples/review-apps-nginx/>.
1018

1019 1020
### artifacts

1021
>
1022 1023 1024
**Notes:**
- Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
- Windows support was added in GitLab Runner v.1.0.0.
1025 1026
- Prior to GitLab 9.2, caches were restored after artifacts.
- From GitLab 9.2, caches are restored before artifacts.
1027 1028
- Currently not all executors are supported.
- Job artifacts are only collected for successful jobs by default.
1029

1030
`artifacts` is used to specify a list of files and directories which should be
1031 1032
attached to the job after success. You can only use paths that are within the
project workspace. To pass artifacts between different jobs, see [dependencies](#dependencies).
1033
Below are some examples.
1034

1035
Send all files in `binaries` and `.config`:
1036

1037 1038 1039 1040 1041 1042
```yaml
artifacts:
  paths:
  - binaries/
  - .config
```
1043

1044
Send all Git untracked files:
1045

1046 1047 1048 1049 1050
```yaml
artifacts:
  untracked: true
```

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

1053 1054 1055 1056 1057 1058
```yaml
artifacts:
  untracked: true
  paths:
  - binaries/
```
1059

1060 1061 1062 1063 1064 1065 1066 1067 1068
To disable artifact passing, define the job with empty [dependencies](#dependencies):

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

1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090
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
```

1091
The artifacts will be sent to GitLab after the job finishes successfully and will
1092
be available for download in the GitLab UI.
1093

1094 1095
#### artifacts:name

1096
> Introduced in GitLab 8.6 and GitLab Runner v1.1.0.
1097

1098
The `name` directive allows you to define the name of the created artifacts
1099
archive. That way, you can have a unique name for every archive which could be
1100 1101
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).
1102
The default name is `artifacts`, which becomes `artifacts.zip` when downloaded.
1103 1104 1105 1106 1107

---

**Example configurations**

1108
To create an archive with a name of the current job:
1109 1110 1111 1112

```yaml
job:
  artifacts:
1113
    name: "$CI_JOB_NAME"
1114 1115
```

1116 1117
To create an archive with a name of the current branch or tag including only
the files that are untracked by Git:
1118 1119 1120 1121

```yaml
job:
   artifacts:
1122
     name: "$CI_COMMIT_REF_NAME"
1123 1124 1125
     untracked: true
```

1126
To create an archive with a name of the current job and the current branch or
1127
tag including only the files that are untracked by Git:
1128 1129 1130 1131

```yaml
job:
  artifacts:
1132
    name: "${CI_JOB_NAME}_${CI_COMMIT_REF_NAME}"
1133 1134 1135
    untracked: true
```

1136
To create an archive with a name of the current [stage](#stages) and branch name:
1137 1138 1139 1140

```yaml
job:
  artifacts:
1141
    name: "${CI_JOB_STAGE}_${CI_COMMIT_REF_NAME}"
1142 1143 1144
    untracked: true
```

1145 1146
---

1147 1148 1149 1150 1151 1152
If you use **Windows Batch** to run your shell scripts you need to replace
`$` with `%`:

```yaml
job:
  artifacts:
1153
    name: "%CI_JOB_STAGE%_%CI_COMMIT_REF_NAME%"
1154 1155 1156
    untracked: true
```

1157 1158 1159 1160 1161 1162 1163 1164 1165 1166
If you use **Windows PowerShell** to run your shell scripts you need to replace
`$` with `$env:`:

```yaml
job:
  artifacts:
    name: "$env:CI_JOB_STAGE_$env:CI_COMMIT_REF_NAME"
    untracked: true
```

1167 1168
#### artifacts:when

1169
> Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
1170

1171
`artifacts:when` is used to upload artifacts on job failure or despite the
1172 1173 1174 1175
failure.

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

1176 1177 1178
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.
1179 1180 1181 1182 1183

---

**Example configurations**

1184
To upload artifacts only when job fails.
1185 1186 1187 1188 1189 1190 1191

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

1192 1193
#### artifacts:expire_in

1194
> Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
1195

1196 1197 1198 1199
`artifacts:expire_in` is used to delete uploaded artifacts after the specified
time. By default, artifacts are stored on GitLab forever. `expire_in` allows you
to specify how long artifacts should live before they expire, counting from the
time they are uploaded and stored on GitLab.
1200

1201
You can use the **Keep** button on the job page to override expiration and
1202
keep artifacts forever.
1203

Mark Pundsack's avatar
Mark Pundsack committed
1204 1205
After expiry, artifacts are actually deleted hourly by default (via a cron job),
but they are not accessible after expiry.
1206

1207
The value of `expire_in` is an elapsed time. Examples of parseable values:
1208

1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219
- '3 mins 4 sec'
- '2 hrs 20 min'
- '2h20min'
- '6 mos 1 day'
- '47 yrs 6 mos and 4d'
- '3 weeks and 2 days'

---

**Example configurations**

1220
To expire artifacts 1 week after being uploaded:
1221 1222 1223 1224 1225 1226 1227

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

1228 1229
### dependencies

1230
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
1231

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

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

1237
To use this feature, define `dependencies` in context of the job and pass
1238 1239
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.
Shinya Maeda's avatar
Shinya Maeda committed
1240
An error will be shown if you define jobs from the current stage or next ones.
1241
Defining an empty array will skip downloading any artifacts for that job.
Fabio Busatto's avatar
Fabio Busatto committed
1242 1243
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.
1244 1245

---
1246

1247 1248 1249 1250 1251
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`.

1252
The job `deploy` will download artifacts from all previous jobs because of
1253
the [stage](#stages) precedence:
1254

1255
```yaml
1256 1257
build:osx:
  stage: build
1258
  script: make build:osx
1259 1260 1261
  artifacts:
    paths:
    - binaries/
1262

1263 1264
build:linux:
  stage: build
1265
  script: make build:linux
1266 1267 1268 1269 1270 1271
  artifacts:
    paths:
    - binaries/

test:osx:
  stage: test
1272
  script: make test:osx
1273 1274 1275 1276 1277
  dependencies:
  - build:osx

test:linux:
  stage: test
1278
  script: make test:linux
1279 1280 1281 1282 1283
  dependencies:
  - build:linux

deploy:
  stage: deploy
1284
  script: make deploy
1285 1286
```

1287 1288 1289
#### When a dependent job will fail

> Introduced in GitLab 10.3.
Shinya Maeda's avatar
Shinya Maeda committed
1290

1291 1292 1293 1294
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.
Shinya Maeda's avatar
Shinya Maeda committed
1295

1296 1297 1298 1299
NOTE: **Note:**
You can ask your administrator to
[flip this switch](../../administration/job_artifacts.md#validation-for-dependencies)
and bring back the old behavior.
Shinya Maeda's avatar
Shinya Maeda committed
1300

1301 1302
### before_script and after_script

1303
It's possible to overwrite the globally defined `before_script` and `after_script`:
1304 1305

```yaml
Philipp Kraus's avatar
Philipp Kraus committed
1306
before_script:
1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317
- global before script

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

1318
### coverage
1319

1320 1321 1322
**Notes:**
- [Introduced][ce-7447] in GitLab 8.17.

1323 1324
`coverage` allows you to configure how code coverage will be extracted from the
job output.
1325

1326 1327 1328 1329 1330 1331
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:
1332 1333 1334

```yaml
job1:
1335
  script: rspec
Max Raab's avatar
Max Raab committed
1336
  coverage: '/Code coverage: \d+\.\d+/'
1337 1338
```

1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349
### retry

**Notes:**
- [Introduced][ce-3442] in GitLab 9.5.

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

1350
If `retry` is set to 2, and a job succeeds in a second run (first retry), it won't be retried
1351
again. `retry` value has to be a positive integer, equal or larger than 0, but
1352
lower or equal to 2 (two retries maximum, three runs in total).
1353 1354 1355 1356 1357 1358

A simple example:

```yaml
test:
  script: rspec
1359
  retry: 2
1360 1361
```

1362 1363
## Git Strategy

Nick Thomas's avatar
Nick Thomas committed
1364 1365 1366 1367 1368 1369 1370 1371
> 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
in the global [`variables`](#variables) section or the [`variables`](#job-variables)
section for individual jobs. If left unspecified, the default from project
settings will be used.
1372

Nick Thomas's avatar
Nick Thomas committed
1373 1374 1375 1376
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.
1377

1378
```yaml
1379 1380 1381 1382
variables:
  GIT_STRATEGY: clone
```

Nick Thomas's avatar
Nick Thomas committed
1383 1384 1385
`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.
1386

1387
```yaml
1388 1389 1390 1391
variables:
  GIT_STRATEGY: fetch
```

Nick Thomas's avatar
Nick Thomas committed
1392 1393 1394 1395 1396 1397
`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.

1398
```yaml
Nick Thomas's avatar
Nick Thomas committed
1399 1400 1401 1402
variables:
  GIT_STRATEGY: none
```

1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426
## 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. Like `GIT_STRATEGY`, it can be set in either the
global [`variables`](#variables) section or the [`variables`](#job-variables)
section for individual jobs.

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
1427
  GIT_CHECKOUT: "false"
1428 1429 1430 1431 1432
script:
  - git checkout master
  - git merge $CI_BUILD_REF_NAME
```

1433 1434 1435 1436 1437 1438 1439 1440 1441
## Git Submodule Strategy

> Requires GitLab Runner v1.10+.

The `GIT_SUBMODULE_STRATEGY` variable is used to control if / how Git
submodules are included when fetching the code before a build. Like
`GIT_STRATEGY`, it can be set in either the global [`variables`](#variables)
section or the [`variables`](#job-variables) section for individual jobs.

1442
There are three possible values: `none`, `normal`, and `recursive`:
1443 1444 1445 1446 1447 1448

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

1450
    ```
1451 1452
    git submodule sync
    git submodule update --init
1453 1454 1455 1456
    ```

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

1458
    ```
1459 1460
    git submodule sync --recursive
    git submodule update --init --recursive
1461 1462 1463 1464
    ```

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

1466 1467 1468 1469 1470
- 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.


1471
## Job stages attempts
1472 1473 1474

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

1475
You can set the number for attempts the running job will try to execute each
1476 1477
of the following stages:

1478 1479 1480 1481 1482
| 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 |
1483 1484 1485 1486 1487

The default is one single attempt.

Example:

1488
```yaml
1489
variables:
1490
  GET_SOURCES_ATTEMPTS: 3
1491 1492
```

1493 1494
You can set them in the global [`variables`](#variables) section or the
[`variables`](#job-variables) section for individual jobs.
1495

1496 1497
## Shallow cloning

1498
> Introduced in GitLab 8.9 as an experimental feature. May change in future
Mark Pundsack's avatar
Mark Pundsack committed
1499
releases or be removed completely.
1500 1501

You can specify the depth of fetching and cloning using `GIT_DEPTH`. This allows
Mark Pundsack's avatar
Mark Pundsack committed
1502 1503 1504
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`.
1505

Mark Pundsack's avatar
Mark Pundsack committed
1506
>**Note:**
1507 1508
If you use a depth of 1 and have a queue of jobs or retry
jobs, jobs may fail.
Mark Pundsack's avatar
Mark Pundsack committed
1509

1510 1511 1512 1513
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
Mark Pundsack's avatar
Mark Pundsack committed
1514
it impossible to run these old commits. You will see `unresolved reference` in
1515
job logs. You should then reconsider changing `GIT_DEPTH` to a higher value.
Mark Pundsack's avatar
Mark Pundsack committed
1516

1517 1518
Jobs that rely on `git describe` may not work correctly when `GIT_DEPTH` is
set since only part of the Git history is present.
Mark Pundsack's avatar
Mark Pundsack committed
1519 1520

To fetch or clone only the last 3 commits:
1521 1522

```yaml
1523
variables:
Mark Pundsack's avatar
Mark Pundsack committed
1524
  GIT_DEPTH: "3"
1525 1526
```

1527
## Hidden keys (jobs)
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
1528

1529
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
1530

1531 1532 1533 1534 1535 1536 1537 1538
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
```
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
1539

1540 1541
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:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
1542 1543

```yaml
1544
.hidden_job:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
1545
  script:
1546
    - run test
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
1547 1548
```

1549 1550 1551
Use this feature to ignore jobs, or use the
[special YAML features](#special-yaml-features) and transform the hidden keys
into templates.
1552

1553
## Special YAML features
1554

1555 1556 1557
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`.
1558

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

1561 1562
### Anchors

1563
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
1564

1565
YAML has a handy feature called 'anchors', which lets you easily duplicate
1566
content across your document. Anchors can be used to duplicate/inherit
1567
properties, and is a perfect example to be used with [hidden keys](#hidden-keys-jobs)
1568 1569 1570 1571 1572
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:
1573 1574

```yaml
1575
.job_template: &job_definition  # Hidden key that defines an anchor named 'job_definition'
1576 1577 1578 1579 1580 1581
  image: ruby:2.1
  services:
    - postgres
    - redis

test1:
1582
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
1583
  script:
1584
    - test1 project
1585 1586

test2:
1587
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
1588
  script:
1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617
    - 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
1618 1619
```

1620 1621 1622 1623
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:
1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634

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

.postgres_services:
  services: &postgres_definition
    - postgres
    - ruby

1635
.mysql_services:
1636 1637 1638 1639 1640
  services: &mysql_definition
    - mysql
    - ruby

test:postgres:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
1641
  <<: *job_definition
1642 1643 1644
  services: *postgres_definition

test:mysql:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
1645
  <<: *job_definition
1646 1647 1648
  services: *mysql_definition
```

1649
The expanded version looks like this:
1650

1651 1652 1653 1654
```yaml
.job_template:
  script:
    - test project
1655

1656 1657 1658 1659
.postgres_services:
  services:
    - postgres
    - ruby
1660

1661 1662 1663 1664 1665 1666
.mysql_services:
  services:
    - mysql
    - ruby

test:postgres:
1667
  script:
1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678
    - test project
  services:
    - postgres
    - ruby

test:mysql:
  script:
    - test project
  services:
    - mysql
    - ruby
1679 1680
```

1681
You can see that the hidden keys are conveniently used as templates.
1682

1683 1684 1685 1686 1687 1688 1689
## 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)

1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716
### pages

`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
  script:
  - mkdir .public
  - cp -r * .public
  - mv .public public
  artifacts:
    paths:
    - public
  only:
  - master
```

1717
Read more on [GitLab Pages user documentation](../../user/project/pages/index.md).
1718

1719
## Validate the .gitlab-ci.yml
1720

1721
Each instance of GitLab CI has an embedded debug tool called Lint.
1722
You can find the link under `/ci/lint` of your gitlab instance.
1723

1724 1725 1726 1727 1728
## 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`).

1729
## Skipping jobs
1730

1731
If your commit message contains `[ci skip]` or `[skip ci]`, using any
1732
capitalization, the commit will be created but the jobs will be skipped.
1733 1734 1735 1736 1737 1738

## Examples

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

1739
[env-manual]: ../environments.md#manually-deploying-to-environments
1740
[examples]: ../examples/README.md
1741 1742
[ce-6323]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6323
[environment]: ../environments.md
1743 1744
[ce-6669]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6669
[variables]: ../variables/README.md
1745
[ce-7983]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7983
1746
[ce-7447]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7447
1747
[ce-3442]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3442
1748
[schedules]: ../../user/project/pipelines/schedules.md
1749
[ee]: https://about.gitlab.com/gitlab-ee/