README.md 36.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 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:
D
Douwe Maan 已提交
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.
D
Douwe Maan 已提交
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.
D
Douwe Maan 已提交
36

37 38
The YAML syntax allows for using more complex job specifications than in the
above example:
D
Douwe Maan 已提交
39 40

```yaml
J
James Lopez 已提交
41
image: ruby:2.1
D
Douwe Maan 已提交
42 43 44 45
services:
  - postgres

before_script:
F
frodsan 已提交
46
  - bundle install
D
Douwe Maan 已提交
47

48 49 50
after_script:
  - rm secrets

D
Douwe Maan 已提交
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:
D
Douwe Maan 已提交
67

68
| Keyword       | Required | Description |
D
Douwe Maan 已提交
69
|---------------|----------|-------------|
70 71 72 73 74
| 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 |
| types         | no | Alias for `stages` |
| 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 |
D
Douwe Maan 已提交
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).
D
Douwe Maan 已提交
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.
D
Douwe Maan 已提交
90

91 92
### after_script

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

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

D
Douwe Maan 已提交
98
### stages
99

100
`stages` is used to define stages that can be used by jobs.
D
Douwe Maan 已提交
101 102
The specification of `stages` allows for having flexible multi stage pipelines.

103
The ordering of elements in `stages` defines the ordering of jobs' execution:
D
Douwe Maan 已提交
104

105 106
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
107
   complete successfully.
D
Douwe Maan 已提交
108 109

Let's consider the following example, which defines 3 stages:
110 111

```yaml
D
Douwe Maan 已提交
112 113 114 115 116 117
stages:
  - build
  - test
  - deploy
```

118
1. First, all jobs of `build` are executed in parallel.
119 120 121
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.
1. If all jobs of `deploy` succeed, the commit is marked as `success`.
122 123
1. If any of the previous jobs fails, the commit is marked as `failed` and no
   jobs of further stage are executed.
D
Douwe Maan 已提交
124 125 126

There are also two edge cases worth mentioning:

127
1. If no `stages` are defined in `.gitlab-ci.yml`, then the `build`,
128
   `test` and `deploy` are allowed to be used as job's stage by default.
M
Mark Pundsack 已提交
129
2. If a job doesn't specify a `stage`, the job is assigned the `test` stage.
D
Douwe Maan 已提交
130 131

### types
132

D
Douwe Maan 已提交
133 134 135 136
Alias for [stages](#stages).

### variables

137
> Introduced in GitLab Runner v0.5.0.
138

M
Mark Pundsack 已提交
139
GitLab CI allows you to add variables to `.gitlab-ci.yml` that are set in the
140
job environment. The variables are stored in the Git repository and are meant
M
Mark Pundsack 已提交
141
to store non-sensitive project configuration, for example:
D
Douwe Maan 已提交
142 143 144 145 146 147 148

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

These variables can be later used in all executed commands and scripts.
149
The YAML-defined variables are also set to all created service containers,
150 151
thus allowing to fine tune them. Variables can be also defined on a
[job level](#job-variables).
D
Douwe Maan 已提交
152

153 154 155 156 157
Except for the user defined variables, there are also the ones set up by the
Runner itself. One example would be `CI_BUILD_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
which can be set in GitLab's UI.
158

159
[Learn more about variables.][variables]
160

161 162
### cache

163
> Introduced in GitLab Runner v0.7.0.
164

165
`cache` is used to specify a list of files and directories which should be
166
cached between jobs. You can only use paths that are within the project
167
workspace.
168 169

**By default the caching is enabled per-job and per-branch.**
170 171 172

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

174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
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/
```

205 206
Locally defined cache overwrites globally defined options. The following `rspec`
job will cache only `binaries/`:
207 208

```yaml
209 210
cache:
  paths:
211 212 213 214 215 216 217
  - my/files

rspec:
  script: test
  cache:
    paths:
    - binaries/
218 219
```

M
Mark Pundsack 已提交
220 221
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.
222

223 224
#### cache:key

225
> Introduced in GitLab Runner v1.0.0.
226 227 228 229 230

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.

231 232
This allows you to fine tune caching, allowing you to cache data between
different jobs or even different branches.
233

234 235 236 237 238
The `cache:key` variable can use any of the [predefined variables](../variables/README.md).

---

**Example configurations**
239 240 241

To enable per-job caching:

242 243 244 245 246
```yaml
cache:
  key: "$CI_BUILD_NAME"
  untracked: true
```
247 248 249

To enable per-branch caching:

250 251 252 253 254
```yaml
cache:
  key: "$CI_BUILD_REF_NAME"
  untracked: true
```
255 256 257

To enable per-job and per-branch caching:

258 259 260 261 262
```yaml
cache:
  key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME"
  untracked: true
```
263 264 265

To enable per-branch and per-stage caching:

266 267 268 269 270
```yaml
cache:
  key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME"
  untracked: true
```
271

272 273
If you use **Windows Batch** to run your shell scripts you need to replace
`$` with `%`:
274

275 276 277 278 279
```yaml
cache:
  key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%"
  untracked: true
```
280

D
Douwe Maan 已提交
281
## Jobs
282 283

`.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job
284 285
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.
D
Douwe Maan 已提交
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302

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

303
| Keyword       | Required | Description |
D
Douwe Maan 已提交
304
|---------------|----------|-------------|
305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322
| 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 |
D
Douwe Maan 已提交
323 324

### script
325

326
`script` is a shell script which is executed by the Runner. For example:
D
Douwe Maan 已提交
327 328 329 330 331 332 333

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

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

D
Douwe Maan 已提交
335 336 337 338 339 340 341
```yaml
job:
  script:
    - uname -a
    - bundle exec rspec
```

342 343 344 345 346
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:
`:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.
347

D
Douwe Maan 已提交
348
### stage
349

350
`stage` allows to group jobs into different stages. Jobs of the same `stage`
351 352
are executed in `parallel`. For more info about the use of `stage` please check
[stages](#stages).
D
Douwe Maan 已提交
353 354 355

### only and except

356 357
`only` and `except` are two parameters that set a refs policy to limit when
jobs are built:
D
Douwe Maan 已提交
358

359
1. `only` defines the names of branches and tags for which the job will run.
360
2. `except` defines the names of branches and tags for which the job will
361
    **not** run.
362 363 364 365 366 367

There are a few rules that apply to the usage of refs policy:

* `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.
368
* `only` and `except` allow the use of special keywords: `branches`, `tags`, and `triggers`.
369 370 371 372 373
* `only` and `except` allow to specify a repository path to filter jobs for
   forks.

In the example below, `job` will run only for refs that start with `issue-`,
whereas all branches will be skipped.
D
Douwe Maan 已提交
374 375 376

```yaml
job:
377
  # use regexp
D
Douwe Maan 已提交
378
  only:
379 380
    - /^issue-.*$/
  # use special keyword
D
Douwe Maan 已提交
381
  except:
382
    - branches
D
Douwe Maan 已提交
383 384
```

385 386
In this example, `job` will run only for refs that are tagged, or if a build is
explicitly requested via an API trigger.
387 388 389 390 391 392 393 394 395

```yaml
job:
  # use special keywords
  only:
    - tags
    - triggers
```

396 397
The repository path can be used to have jobs executed only for the parent
repository and not forks:
398 399 400 401 402 403 404 405

```yaml
job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce
```
406 407 408

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

410
### Job variables
411

412 413 414
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.
415

416 417
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
A
Achilleas Pipinellis 已提交
418
in your job, define an empty array:
419

A
Achilleas Pipinellis 已提交
420 421 422 423 424
```yaml
job_name:
  variables: []
```

425
Job variables priority is defined in the [variables documentation][variables].
426

D
Douwe Maan 已提交
427 428
### tags

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

432
During the registration of a Runner, you can specify the Runner's tags, for
433 434
example `ruby`, `postgres`, `development`.

435
`tags` allow you to run jobs with Runners that have the specified tags
436 437 438
assigned to them:

```yaml
D
Douwe Maan 已提交
439 440 441 442 443 444
job:
  tags:
    - ruby
    - postgres
```

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

448 449
### allow_failure

450 451
`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.
452

453
When enabled and the job fails, the pipeline will be successful/green for all
454
intents and purposes, but a "CI build passed with warnings" message  will be
455 456
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)
457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480
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
```

481
### when
482 483 484

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

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

488
1. `on_success` - execute job only when all jobs from prior stages
489
    succeed. This is the default.
490
1. `on_failure` - execute job only when at least one job from prior stages
491
    fails.
492 493
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
494
    [manual actions](#manual-actions) below.
495

496 497 498
For example:

```yaml
499 500 501 502 503 504 505
stages:
- build
- cleanup_build
- test
- deploy
- cleanup

506
build_job:
507 508 509 510
  stage: build
  script:
  - make build

511
cleanup_build_job:
512 513 514 515 516
  stage: cleanup_build
  script:
  - cleanup build when failed
  when: on_failure

517
test_job:
518 519 520 521
  stage: test
  script:
  - make test

522
deploy_job:
523 524 525
  stage: deploy
  script:
  - make deploy
526
  when: manual
527

528
cleanup_job:
529 530
  stage: cleanup
  script:
531
  - cleanup after jobs
532 533 534 535
  when: always
```

The above script will:
536

537 538 539 540
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.
541 542 543

#### Manual actions

544
> Introduced in GitLab 8.10.
545

546 547 548 549
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
from pipeline, build, environment, and deployment views. You can execute the
same manual action multiple times.
550

551
An example usage of manual actions is deployment to production.
552

553 554
Read more at the [environments documentation][env-manual].

555 556
### environment

557 558 559 560 561
>
**Notes:**
- Introduced in GitLab 8.9.
- You can read more about environments and find more examples in the
  [documentation about environments][environment].
562

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

567
In its simplest form, the `environment` keyword can be defined like:
568

569
```yaml
570 571 572
deploy to production:
  stage: deploy
  script: git push production HEAD:master
573 574
  environment:
    name: production
575 576
```

577 578 579 580 581
In the above example, the `deploy to production` job will be marked as doing a
deployment to the `production` environment.

#### environment:name

582 583 584 585 586 587
>
**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.
588

589 590 591 592 593 594 595 596 597 598 599 600 601 602 603
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.

604 605 606 607
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`:

608
```yaml
609 610 611 612 613 614 615 616 617
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
```

#### environment:url

618 619 620 621 622
>
**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`.
623 624 625 626 627 628 629 630

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

631
```yaml
632 633 634 635 636 637 638 639 640 641
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
    url: https://prod.example.com
```

#### environment:on_stop

642 643 644 645 646 647
>
**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.
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

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

696 697
#### dynamic environments

698 699 700 701
>
**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.
702 703

`environment` can also represent a configuration hash with `name` and `url`.
704
These parameters can use any of the defined [CI variables](#variables)
705
(including predefined, secure variables and `.gitlab-ci.yml` variables).
706

707
For example:
708

709
```yaml
710 711
deploy as review app:
  stage: deploy
712
  script: make deploy
713
  environment:
714 715
    name: review/$CI_BUILD_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com/
716 717
```

718
The `deploy as review app` job will be marked as deployment to dynamically
719 720 721 722 723
create the `review/$CI_BUILD_REF_NAME` environment, where `$CI_BUILD_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
724
`https://review-pow.example.com/`.
725

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

729 730
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
731
<https://gitlab.com/gitlab-examples/review-apps-nginx/>.
732

K
Kamil Trzcinski 已提交
733 734
### artifacts

735
>
736 737 738 739 740
**Notes:**
- Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
- Windows support was added in GitLab Runner v.1.0.0.
- Currently not all executors are supported.
- Job artifacts are only collected for successful jobs by default.
741

742
`artifacts` is used to specify a list of files and directories which should be
743 744
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).
745
Below are some examples.
746

747
Send all files in `binaries` and `.config`:
748

749 750 751 752 753 754
```yaml
artifacts:
  paths:
  - binaries/
  - .config
```
755

756
Send all Git untracked files:
757

758 759 760 761 762
```yaml
artifacts:
  untracked: true
```

763
Send all Git untracked files and files in `binaries`:
K
Kamil Trzcinski 已提交
764

765 766 767 768 769 770
```yaml
artifacts:
  untracked: true
  paths:
  - binaries/
```
K
Kamil Trzcinski 已提交
771

772 773 774 775 776 777 778 779 780
To disable artifact passing, define the job with empty [dependencies](#dependencies):

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

781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802
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
```

803
The artifacts will be sent to GitLab after the job finishes successfully and will
804
be available for download in the GitLab UI.
K
Kamil Trzcinski 已提交
805

806 807
#### artifacts:name

808
> Introduced in GitLab 8.6 and GitLab Runner v1.1.0.
809

A
Achilleas Pipinellis 已提交
810
The `name` directive allows you to define the name of the created artifacts
811
archive. That way, you can have a unique name for every archive which could be
A
Achilleas Pipinellis 已提交
812 813
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).
814
The default name is `artifacts`, which becomes `artifacts.zip` when downloaded.
815 816 817 818 819

---

**Example configurations**

820
To create an archive with a name of the current job:
821 822 823 824 825 826 827

```yaml
job:
  artifacts:
    name: "$CI_BUILD_NAME"
```

A
Achilleas Pipinellis 已提交
828 829
To create an archive with a name of the current branch or tag including only
the files that are untracked by Git:
830 831 832 833 834 835 836 837

```yaml
job:
   artifacts:
     name: "$CI_BUILD_REF_NAME"
     untracked: true
```

838
To create an archive with a name of the current job and the current branch or
A
Achilleas Pipinellis 已提交
839
tag including only the files that are untracked by Git:
840 841 842 843 844 845 846 847

```yaml
job:
  artifacts:
    name: "${CI_BUILD_NAME}_${CI_BUILD_REF_NAME}"
    untracked: true
```

A
Achilleas Pipinellis 已提交
848
To create an archive with a name of the current [stage](#stages) and branch name:
849 850 851 852 853 854 855 856

```yaml
job:
  artifacts:
    name: "${CI_BUILD_STAGE}_${CI_BUILD_REF_NAME}"
    untracked: true
```

A
Achilleas Pipinellis 已提交
857 858
---

859 860 861 862 863 864 865 866 867 868
If you use **Windows Batch** to run your shell scripts you need to replace
`$` with `%`:

```yaml
job:
  artifacts:
    name: "%CI_BUILD_STAGE%_%CI_BUILD_REF_NAME%"
    untracked: true
```

869 870
#### artifacts:when

871
> Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
872

873
`artifacts:when` is used to upload artifacts on job failure or despite the
874 875 876 877
failure.

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

878 879 880
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.
881 882 883 884 885

---

**Example configurations**

886
To upload artifacts only when job fails.
887 888 889 890 891 892 893

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

894 895
#### artifacts:expire_in

896
> Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
897

898 899 900 901
`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.
902

903
You can use the **Keep** button on the job page to override expiration and
904
keep artifacts forever.
905

M
Mark Pundsack 已提交
906 907
After expiry, artifacts are actually deleted hourly by default (via a cron job),
but they are not accessible after expiry.
908

909
The value of `expire_in` is an elapsed time. Examples of parseable values:
910

911 912 913 914 915 916 917 918 919 920 921
- '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**

922
To expire artifacts 1 week after being uploaded:
923 924 925 926 927 928 929

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

930 931
### dependencies

932
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
933

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

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

939
To use this feature, define `dependencies` in context of the job and pass
940 941 942
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.
An error will be shown if you define jobs from the current stage or next ones.
943
Defining an empty array will skip downloading any artifacts for that job.
944 945

---
946

947 948 949 950 951
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`.

952
The job `deploy` will download artifacts from all previous jobs because of
953
the [stage](#stages) precedence:
954

955
```yaml
956 957
build:osx:
  stage: build
958
  script: make build:osx
959 960 961
  artifacts:
    paths:
    - binaries/
962

963 964
build:linux:
  stage: build
965
  script: make build:linux
966 967 968 969 970 971
  artifacts:
    paths:
    - binaries/

test:osx:
  stage: test
972
  script: make test:osx
973 974 975 976 977
  dependencies:
  - build:osx

test:linux:
  stage: test
978
  script: make test:linux
979 980 981 982 983
  dependencies:
  - build:linux

deploy:
  stage: deploy
984
  script: make deploy
985 986
```

987 988
### before_script and after_script

989
It's possible to overwrite the globally defined `before_script` and `after_script`:
990 991

```yaml
P
Philipp Kraus 已提交
992
before_script:
993 994 995 996 997 998 999 1000 1001 1002 1003
- global before script

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

1004
### coverage
1005

1006 1007
`coverage` allows you to configure how code coverage will be extracted from the
job output.
1008

1009 1010 1011 1012 1013 1014
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:
1015 1016 1017

```yaml
job1:
1018
  coverage: /Code coverage: \d+\.\d+/
1019 1020
```

M
Mark Pundsack 已提交
1021 1022
## Git Strategy

N
Nick Thomas 已提交
1023 1024 1025 1026 1027 1028 1029 1030
> 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.
M
Mark Pundsack 已提交
1031

N
Nick Thomas 已提交
1032 1033 1034 1035
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 已提交
1036

1037
```yaml
M
Mark Pundsack 已提交
1038 1039 1040 1041
variables:
  GIT_STRATEGY: clone
```

N
Nick Thomas 已提交
1042 1043 1044
`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 已提交
1045

1046
```yaml
M
Mark Pundsack 已提交
1047 1048 1049 1050
variables:
  GIT_STRATEGY: fetch
```

N
Nick Thomas 已提交
1051 1052 1053 1054 1055 1056
`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.

1057
```yaml
N
Nick Thomas 已提交
1058 1059 1060 1061
variables:
  GIT_STRATEGY: none
```

1062 1063 1064 1065 1066 1067 1068 1069 1070
## 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.

1071
There are three possible values: `none`, `normal`, and `recursive`:
1072 1073 1074 1075 1076 1077

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

1079
    ```
1080 1081
    git submodule sync
    git submodule update --init
1082 1083 1084 1085
    ```

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

1087
    ```
1088 1089
    git submodule sync --recursive
    git submodule update --init --recursive
1090 1091 1092 1093
    ```

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

1095 1096 1097 1098 1099
- 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.


1100
## Job stages attempts
1101 1102 1103

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

1104
You can set the number for attempts the running job will try to execute each
1105 1106
of the following stages:

1107 1108 1109 1110 1111
| 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 |
1112 1113 1114 1115 1116

The default is one single attempt.

Example:

1117
```yaml
1118 1119 1120 1121
variables:
  GET_SOURCES_ATTEMPTS: "3"
```

1122 1123
You can set them in the global [`variables`](#variables) section or the
[`variables`](#job-variables) section for individual jobs.
1124

M
Mark Pundsack 已提交
1125 1126
## Shallow cloning

1127
> Introduced in GitLab 8.9 as an experimental feature. May change in future
M
Mark Pundsack 已提交
1128
releases or be removed completely.
M
Mark Pundsack 已提交
1129 1130

You can specify the depth of fetching and cloning using `GIT_DEPTH`. This allows
M
Mark Pundsack 已提交
1131 1132 1133
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 已提交
1134

M
Mark Pundsack 已提交
1135
>**Note:**
1136 1137
If you use a depth of 1 and have a queue of jobs or retry
jobs, jobs may fail.
M
Mark Pundsack 已提交
1138

1139 1140 1141 1142
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 已提交
1143
it impossible to run these old commits. You will see `unresolved reference` in
1144
job logs. You should then reconsider changing `GIT_DEPTH` to a higher value.
M
Mark Pundsack 已提交
1145

1146 1147
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 已提交
1148 1149

To fetch or clone only the last 3 commits:
1150 1151

```yaml
M
Mark Pundsack 已提交
1152
variables:
M
Mark Pundsack 已提交
1153
  GIT_DEPTH: "3"
M
Mark Pundsack 已提交
1154 1155
```

1156
## Hidden keys
A
Achilleas Pipinellis 已提交
1157

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

1160
Keys that start with a dot (`.`) will be not processed by GitLab CI. You can
A
Achilleas Pipinellis 已提交
1161
use this feature to ignore jobs, or use the
1162
[special YAML features](#special-yaml-features) and transform the hidden keys
A
Achilleas Pipinellis 已提交
1163 1164
into templates.

1165
In the following example, `.key_name` will be ignored:
A
Achilleas Pipinellis 已提交
1166 1167

```yaml
1168
.key_name:
A
Achilleas Pipinellis 已提交
1169 1170 1171 1172
  script:
    - rake spec
```

1173 1174 1175
Hidden keys can be hashes like normal CI jobs, but you are also allowed to use
different types of structures to leverage special YAML features.

1176
## Special YAML features
1177

1178 1179 1180
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`.
1181

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

1184 1185
### Anchors

1186
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
1187

1188
YAML has a handy feature called 'anchors', which lets you easily duplicate
1189
content across your document. Anchors can be used to duplicate/inherit
1190
properties, and is a perfect example to be used with [hidden keys](#hidden-keys)
1191 1192 1193 1194 1195
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:
1196 1197

```yaml
1198
.job_template: &job_definition  # Hidden key that defines an anchor named 'job_definition'
1199 1200 1201 1202 1203 1204
  image: ruby:2.1
  services:
    - postgres
    - redis

test1:
1205
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
1206
  script:
1207
    - test1 project
1208 1209

test2:
1210
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
1211
  script:
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
    - 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
1241 1242
```

1243 1244 1245 1246
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:
1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257

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

.postgres_services:
  services: &postgres_definition
    - postgres
    - ruby

1258
.mysql_services:
1259 1260 1261 1262 1263
  services: &mysql_definition
    - mysql
    - ruby

test:postgres:
A
Achilleas Pipinellis 已提交
1264
  <<: *job_definition
1265 1266 1267
  services: *postgres_definition

test:mysql:
A
Achilleas Pipinellis 已提交
1268
  <<: *job_definition
1269 1270 1271
  services: *mysql_definition
```

1272
The expanded version looks like this:
1273

1274 1275 1276 1277
```yaml
.job_template:
  script:
    - test project
1278

1279 1280 1281 1282
.postgres_services:
  services:
    - postgres
    - ruby
1283

1284 1285 1286 1287 1288 1289
.mysql_services:
  services:
    - mysql
    - ruby

test:postgres:
1290
  script:
1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301
    - test project
  services:
    - postgres
    - ruby

test:mysql:
  script:
    - test project
  services:
    - mysql
    - ruby
1302 1303
```

1304
You can see that the hidden keys are conveniently used as templates.
1305

1306 1307 1308 1309 1310 1311 1312
## 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)

1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339
### 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
```

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

D
Douwe Maan 已提交
1342
## Validate the .gitlab-ci.yml
1343

D
Douwe Maan 已提交
1344
Each instance of GitLab CI has an embedded debug tool called Lint.
1345
You can find the link under `/ci/lint` of your gitlab instance.
D
Douwe Maan 已提交
1346

1347
## Skipping jobs
1348

S
Simon Welsh 已提交
1349
If your commit message contains `[ci skip]` or `[skip ci]`, using any
1350
capitalization, the commit will be created but the jobs will be skipped.
A
Achilleas Pipinellis 已提交
1351 1352 1353 1354 1355 1356

## Examples

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

1357
[env-manual]: ../environments.md#manually-deploying-to-environments
A
Achilleas Pipinellis 已提交
1358
[examples]: ../examples/README.md
1359 1360
[ce-6323]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6323
[environment]: ../environments.md
1361 1362
[ce-6669]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6669
[variables]: ../variables/README.md
1363
[ce-7983]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7983