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

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

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
Jobs are used to create builds, which are then picked up by
34 35
[Runners](../runners/README.md) and executed within the environment of the
Runner. What is important, is that each job is run independently from each
36
other.
D
Douwe Maan 已提交
37

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

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

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

49 50 51
after_script:
  - rm secrets

D
Douwe Maan 已提交
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
stages:
  - build
  - test
  - deploy

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

67
There are a few reserved `keywords` that **cannot** be used as job names:
D
Douwe Maan 已提交
68

69
| Keyword       | Required | Description |
D
Douwe Maan 已提交
70
|---------------|----------|-------------|
71 72 73 74 75
| 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 |
76
| after_script  | no | Define commands that run after each job's script |
77 78
| variables     | no | Define build variables |
| cache         | no | Define list of files that should be cached between subsequent runs |
D
Douwe Maan 已提交
79 80

### image and services
81 82 83

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

### before_script
87 88 89

`before_script` is used to define the command that should be run before all
builds, including deploy builds. 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 96 97
`after_script` is used to define the command that will be run after for all
builds. This has to be an array or a multi-line string.

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

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

The ordering of elements in `stages` defines the ordering of builds' execution:

1. Builds of the same stage are run in parallel.
106 107
1. Builds of the next stage are run after the jobs from the previous stage
   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 118
stages:
  - build
  - test
  - deploy
```

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 by default 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
build 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 167
cached between builds. You can only use paths that are within the project
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 205 206
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/
```

Locally defined cache overwrites globally defined options. This 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 284 285

`.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job
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 build 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
| script        | yes | Defines a shell script which is executed by Runner |
P
Pat Turner 已提交
306 307
| 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) |
308
| stage         | no | Defines a build stage (default: `test`) |
309
| type          | no | Alias for `stage` |
310
| variables     | no | Define build variables on a job level |
311 312
| only          | no | Defines a list of git refs for which build is created |
| except        | no | Defines a list of git refs for which build is not created |
313
| tags          | no | Defines a list of tags which are used to select Runner |
314
| allow_failure | no | Allow build to fail. Failed build doesn't contribute to commit status |
315
| when          | no | Define when to run build. Can be `on_success`, `on_failure`, `always` or `manual` |
316
| dependencies  | no | Define other builds that a build depends on so that you can pass artifacts between them|
A
Aurelio Jargas 已提交
317
| artifacts     | no | Define list of build artifacts |
318
| cache         | no | Define list of files that should be cached between subsequent runs |
319 320
| before_script | no | Override a set of commands that are executed before build |
| after_script  | no | Override a set of commands that are executed after build |
321
| environment   | no | Defines a name of environment to which deployment is done by this build |
D
Douwe Maan 已提交
322 323

### script
324

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

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

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

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

M
Mark Pundsack 已提交
341
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 (`:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``).
342

D
Douwe Maan 已提交
343
### stage
344 345 346 347

`stage` allows to group build into different stages. Builds of the same `stage`
are executed in `parallel`. For more info about the use of `stage` please check
[stages](#stages).
D
Douwe Maan 已提交
348 349 350

### only and except

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

354 355 356 357 358 359 360 361 362 363
1. `only` defines the names of branches and tags for which the job will be
    built.
2. `except` defines the names of branches and tags for which the job will
    **not** be built.

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.
364
* `only` and `except` allow the use of special keywords: `branches`, `tags`, and `triggers`.
365 366 367 368 369
* `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 已提交
370 371 372

```yaml
job:
373
  # use regexp
D
Douwe Maan 已提交
374
  only:
375 376
    - /^issue-.*$/
  # use special keyword
D
Douwe Maan 已提交
377
  except:
378
    - branches
D
Douwe Maan 已提交
379 380
```

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

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

392 393
The repository path can be used to have jobs executed only for the parent
repository and not forks:
394 395 396 397 398 399 400 401

```yaml
job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce
```
402 403 404

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

406 407 408
### job variables

It is possible to define build variables using a `variables` keyword on a job
409 410
level. It works basically the same way as its global-level equivalent but
allows you to define job-specific build variables.
411

412
When the `variables` keyword is used on a job level, it overrides global YAML
413 414
build variables and predefined variables.

415 416
Build variables priority is defined in
[variables documentation](../variables/README.md).
417

D
Douwe Maan 已提交
418 419
### tags

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

423
During the registration of a Runner, you can specify the Runner's tags, for
424 425
example `ruby`, `postgres`, `development`.

426
`tags` allow you to run builds with Runners that have the specified tags
427 428 429
assigned to them:

```yaml
D
Douwe Maan 已提交
430 431 432 433 434 435
job:
  tags:
    - ruby
    - postgres
```

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

439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471
### allow_failure

`allow_failure` is used when you want to allow a build to fail without impacting
the rest of the CI suite. Failed builds don't contribute to the commit status.

When enabled and the build fails, the pipeline will be successful/green for all
intents and purposes, but a "CI build passed with warnings" message  will be
displayed on the merge request or commit or build page. This is to be used by
builds that are allowed to fail, but where failure indicates some other (manual)
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
```

472
### when
473 474 475

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

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

479
1. `on_success` - execute build only when all builds from prior stages
480
    succeed. This is the default.
481
1. `on_failure` - execute build only when at least one build from prior stages
482 483
    fails.
1. `always` - execute build regardless of the status of builds from prior stages.
484 485
1. `manual` - execute build manually (added in GitLab 8.10). Read about
    [manual actions](#manual-actions) below.
486

487 488 489
For example:

```yaml
490 491 492 493 494 495 496
stages:
- build
- cleanup_build
- test
- deploy
- cleanup

497
build_job:
498 499 500 501
  stage: build
  script:
  - make build

502
cleanup_build_job:
503 504 505 506 507
  stage: cleanup_build
  script:
  - cleanup build when failed
  when: on_failure

508
test_job:
509 510 511 512
  stage: test
  script:
  - make test

513
deploy_job:
514 515 516
  stage: deploy
  script:
  - make deploy
517
  when: manual
518

519
cleanup_job:
520 521 522 523 524 525 526
  stage: cleanup
  script:
  - cleanup after builds
  when: always
```

The above script will:
527

528 529 530 531
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.
532 533 534

#### Manual actions

535
> Introduced in GitLab 8.10.
536

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

542
An example usage of manual actions is deployment to production.
543

544 545
Read more at the [environments documentation][env-manual].

546 547
### environment

548
> Introduced in GitLab 8.9.
549

550 551
> You can read more about environments and find more examples in the
[documentation about environments][environment].
552

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

557
In its simplest form, the `environment` keyword can be defined like:
558 559 560 561 562

```
deploy to production:
  stage: deploy
  script: git push production HEAD:master
563 564
  environment:
    name: production
565 566
```

567 568 569 570 571 572 573 574 575 576 577 578
In the above example, the `deploy to production` job will be marked as doing a
deployment to the `production` environment.

#### environment:name

> Introduced in GitLab 8.11.

>**Note:**
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.

579 580 581 582 583 584 585 586 587 588 589 590 591 592 593
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.

594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631
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`:

```
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
```

#### environment:url

> Introduced in GitLab 8.11.

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

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

```
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
    url: https://prod.example.com
```

#### environment:on_stop

632 633 634 635 636 637
>
**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.
638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682

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

684 685
#### dynamic environments

686
> [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6.
687 688

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

692 693 694 695 696 697 698
>**Note:**
Be aware than if the branch name contains special characters and you use the
`$CI_BUILD_REF_NAME` variable to dynamically create environments, there might
be complications during deployment. Follow the
[issue 22849](https://gitlab.com/gitlab-org/gitlab-ce/issues/22849) for more
information.

699
For example:
700 701 702 703

```
deploy as review app:
  stage: deploy
704
  script: make deploy
705
  environment:
706 707 708 709
    name: review-apps/$CI_BUILD_REF_NAME
    url: https://$CI_BUILD_REF_NAME.review.example.com/
```

710
The `deploy as review app` job will be marked as deployment to dynamically
711 712 713 714
create the `review-apps/$CI_BUILD_REF_NAME` environment, which `$CI_BUILD_REF_NAME`
is an [environment variable][variables] set by the Runner. If for example the
`deploy as review app` job was run in a branch named `pow`, this environment
should be accessible under `https://pow.review.example.com/`.
715

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

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

K
Kamil Trzcinski 已提交
723 724
### artifacts

725 726 727
>**Notes:**
>
> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
728
> - Windows support was added in GitLab Runner v.1.0.0.
729
> - Currently not all executors are supported.
730
> - Build artifacts are only collected for successful builds by default.
731

732
`artifacts` is used to specify a list of files and directories which should be
733 734
attached to the build after success. You can only use paths that are within the
project workspace. To pass artifacts between different builds, see [dependencies](#dependencies).
735 736

Below are some examples.
737

738
Send all files in `binaries` and `.config`:
739

740 741 742 743 744 745
```yaml
artifacts:
  paths:
  - binaries/
  - .config
```
746

747
Send all Git untracked files:
748

749 750 751 752 753
```yaml
artifacts:
  untracked: true
```

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

756 757 758 759 760 761
```yaml
artifacts:
  untracked: true
  paths:
  - binaries/
```
K
Kamil Trzcinski 已提交
762

763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784
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
```

785 786
The artifacts will be sent to GitLab after a successful build and will
be available for download in the GitLab UI.
K
Kamil Trzcinski 已提交
787

788 789
#### artifacts:name

790
> Introduced in GitLab 8.6 and GitLab Runner v1.1.0.
791

A
Achilleas Pipinellis 已提交
792
The `name` directive allows you to define the name of the created artifacts
793
archive. That way, you can have a unique name for every archive which could be
A
Achilleas Pipinellis 已提交
794 795
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).
796
The default name is `artifacts`, which becomes `artifacts.zip` when downloaded.
797 798 799 800 801

---

**Example configurations**

A
Achilleas Pipinellis 已提交
802
To create an archive with a name of the current build:
803 804 805 806 807 808 809

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

A
Achilleas Pipinellis 已提交
810 811
To create an archive with a name of the current branch or tag including only
the files that are untracked by Git:
812 813 814 815 816 817 818 819

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

A
Achilleas Pipinellis 已提交
820 821
To create an archive with a name of the current build and the current branch or
tag including only the files that are untracked by Git:
822 823 824 825 826 827 828 829

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

A
Achilleas Pipinellis 已提交
830
To create an archive with a name of the current [stage](#stages) and branch name:
831 832 833 834 835 836 837 838

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

A
Achilleas Pipinellis 已提交
839 840
---

841 842 843 844 845 846 847 848 849 850
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
```

851 852
#### artifacts:when

853
> Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
854 855 856 857 858 859

`artifacts:when` is used to upload artifacts on build failure or despite the
failure.

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

860 861 862
1. `on_success` - upload artifacts only when the build succeeds. This is the default.
1. `on_failure` - upload artifacts only when the build fails.
1. `always` - upload artifacts regardless of the build status.
863 864 865 866 867

---

**Example configurations**

K
Kamil Trzcinski 已提交
868
To upload artifacts only when build fails.
869 870 871 872 873 874 875

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

876 877
#### artifacts:expire_in

878
> Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
879

880 881 882 883
`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.
884

885 886
You can use the **Keep** button on the build page to override expiration and
keep artifacts forever.
887

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

891
The value of `expire_in` is an elapsed time. Examples of parseable values:
892 893 894 895 896 897 898 899 900 901 902
- '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**

903
To expire artifacts 1 week after being uploaded:
904 905 906 907 908 909 910

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

911 912
### dependencies

913
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
914

915 916
This feature should be used in conjunction with [`artifacts`](#artifacts) and
allows you to define the artifacts to pass between different builds.
917

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

920
To use this feature, define `dependencies` in context of the job and pass
921
a list of all previous builds from which the artifacts should be downloaded.
922 923
You can only define builds from stages that are executed before the current one.
An error will be shown if you define builds from the current stage or next ones.
924
Defining an empty array will skip downloading any artifacts for that job.
925 926

---
927

928 929 930 931 932 933 934
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`.

The job `deploy` will download artifacts from all previous builds because of
the [stage](#stages) precedence:
935

936
```yaml
937 938
build:osx:
  stage: build
939
  script: make build:osx
940 941 942
  artifacts:
    paths:
    - binaries/
943

944 945
build:linux:
  stage: build
946
  script: make build:linux
947 948 949 950 951 952
  artifacts:
    paths:
    - binaries/

test:osx:
  stage: test
953
  script: make test:osx
954 955 956 957 958
  dependencies:
  - build:osx

test:linux:
  stage: test
959
  script: make test:linux
960 961 962 963 964
  dependencies:
  - build:linux

deploy:
  stage: deploy
965
  script: make deploy
966 967
```

968 969 970 971 972
### before_script and after_script

It's possible to overwrite globally defined `before_script` and `after_script`:

```yaml
P
Philipp Kraus 已提交
973
before_script:
974 975 976 977 978 979 980 981 982 983 984
- global before script

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

M
Mark Pundsack 已提交
985 986
## Git Strategy

N
Nick Thomas 已提交
987 988 989 990 991 992 993 994
> 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 已提交
995

N
Nick Thomas 已提交
996 997 998 999
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 已提交
1000 1001 1002 1003 1004 1005

```
variables:
  GIT_STRATEGY: clone
```

N
Nick Thomas 已提交
1006 1007 1008
`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 已提交
1009 1010 1011 1012 1013 1014

```
variables:
  GIT_STRATEGY: fetch
```

N
Nick Thomas 已提交
1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025
`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.

```
variables:
  GIT_STRATEGY: none
```

M
Mark Pundsack 已提交
1026 1027
## Shallow cloning

1028
> Introduced in GitLab 8.9 as an experimental feature. May change in future
M
Mark Pundsack 已提交
1029
releases or be removed completely.
M
Mark Pundsack 已提交
1030 1031

You can specify the depth of fetching and cloning using `GIT_DEPTH`. This allows
M
Mark Pundsack 已提交
1032 1033 1034
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 已提交
1035

M
Mark Pundsack 已提交
1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050
>**Note:**
If you use a depth of 1 and have a queue of builds or retry
builds, jobs may fail.

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 builds in the queue, or
you are retrying an old build, 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
it impossible to run these old commits. You will see `unresolved reference` in
build logs. You should then reconsider changing `GIT_DEPTH` to a higher value.

Builds that rely on `git describe` may not work correctly when `GIT_DEPTH` is
set since only part of the git history is present.

To fetch or clone only the last 3 commits:
M
Mark Pundsack 已提交
1051 1052
```
variables:
M
Mark Pundsack 已提交
1053
  GIT_DEPTH: "3"
M
Mark Pundsack 已提交
1054 1055
```

1056
## Hidden keys
A
Achilleas Pipinellis 已提交
1057

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

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

1065
In the following example, `.key_name` will be ignored:
A
Achilleas Pipinellis 已提交
1066 1067

```yaml
1068
.key_name:
A
Achilleas Pipinellis 已提交
1069 1070 1071 1072
  script:
    - rake spec
```

1073 1074 1075
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.

1076
## Special YAML features
1077

1078 1079 1080
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`.
1081

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

1084 1085
### Anchors

1086
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
1087 1088 1089

YAML also has a handy feature called 'anchors', which let you easily duplicate
content across your document. Anchors can be used to duplicate/inherit
1090
properties, and is a perfect example to be used with [hidden keys](#hidden-keys)
1091 1092 1093 1094 1095
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:
1096 1097

```yaml
1098
.job_template: &job_definition  # Hidden key that defines an anchor named 'job_definition'
1099 1100 1101 1102 1103 1104
  image: ruby:2.1
  services:
    - postgres
    - redis

test1:
1105
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
1106
  script:
1107
    - test1 project
1108 1109

test2:
1110
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
1111
  script:
1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140
    - 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
1141 1142
```

1143 1144 1145 1146
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:
1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157

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

.postgres_services:
  services: &postgres_definition
    - postgres
    - ruby

1158
.mysql_services:
1159 1160 1161 1162 1163
  services: &mysql_definition
    - mysql
    - ruby

test:postgres:
A
Achilleas Pipinellis 已提交
1164
  <<: *job_definition
1165 1166 1167
  services: *postgres_definition

test:mysql:
A
Achilleas Pipinellis 已提交
1168
  <<: *job_definition
1169 1170 1171
  services: *mysql_definition
```

1172
The expanded version looks like this:
1173

1174 1175 1176 1177
```yaml
.job_template:
  script:
    - test project
1178

1179 1180 1181 1182
.postgres_services:
  services:
    - postgres
    - ruby
1183

1184 1185 1186 1187 1188 1189
.mysql_services:
  services:
    - mysql
    - ruby

test:postgres:
1190
  script:
1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201
    - test project
  services:
    - postgres
    - ruby

test:mysql:
  script:
    - test project
  services:
    - mysql
    - ruby
1202 1203
```

1204
You can see that the hidden keys are conveniently used as templates.
1205

1206 1207 1208 1209 1210 1211 1212
## 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)

D
Douwe Maan 已提交
1213
## Validate the .gitlab-ci.yml
1214

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

## Skipping builds
1219

S
Simon Welsh 已提交
1220 1221
If your commit message contains `[ci skip]` or `[skip ci]`, using any
capitalization, the commit will be created but the builds will be skipped.
A
Achilleas Pipinellis 已提交
1222 1223 1224 1225 1226 1227

## Examples

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

1228
[env-manual]: ../environments.md#manually-deploying-to-environments
A
Achilleas Pipinellis 已提交
1229
[examples]: ../examples/README.md
1230 1231
[ce-6323]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6323
[environment]: ../environments.md
1232 1233
[ce-6669]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6669
[variables]: ../variables/README.md