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

3 4 5 6 7 8 9 10 11 12 13 14 15
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).

---

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [.gitlab-ci.yml](#gitlab-ci-yml)
M
Mark Pundsack 已提交
16 17 18 19 20 21 22 23
  - [image and services](#image-and-services)
  - [before_script](#before_script)
  - [after_script](#after_script)
  - [stages](#stages)
  - [types](#types)
  - [variables](#variables)
  - [cache](#cache)
    - [cache:key](#cache-key)
24
- [Jobs](#jobs)
M
Mark Pundsack 已提交
25 26 27 28 29 30 31 32 33 34 35 36 37
  - [script](#script)
  - [stage](#stage)
  - [only and except](#only-and-except)
  - [job variables](#job-variables)
  - [tags](#tags)
  - [when](#when)
  - [environment](#environment)
  - [artifacts](#artifacts)
    - [artifacts:name](#artifactsname)
    - [artifacts:when](#artifactswhen)
    - [artifacts:expire_in](#artifactsexpire_in)
  - [dependencies](#dependencies)
  - [before_script and after_script](#before_script-and-after_script)
M
Mark Pundsack 已提交
38 39
- [Git Strategy](#git-strategy)
- [Shallow cloning](#shallow-cloning)
40 41
- [Hidden jobs](#hidden-jobs)
- [Special YAML features](#special-yaml-features)
M
Mark Pundsack 已提交
42 43
  - [Anchors](#anchors)
- [Validate the .gitlab-ci.yml](#validate-the-gitlab-ciyml)
44 45 46 47 48 49 50 51 52
- [Skipping builds](#skipping-builds)
- [Examples](#examples)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

---

## .gitlab-ci.yml

53 54 55 56 57 58
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
59
to contain at least the `script` clause:
D
Douwe Maan 已提交
60 61 62 63 64 65 66 67 68

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

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

69 70 71 72 73
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 已提交
74

75
Jobs are used to create builds, which are then picked up by
76 77
[Runners](../runners/README.md) and executed within the environment of the
Runner. What is important, is that each job is run independently from each
78
other.
D
Douwe Maan 已提交
79

80 81
The YAML syntax allows for using more complex job specifications than in the
above example:
D
Douwe Maan 已提交
82 83

```yaml
J
James Lopez 已提交
84
image: ruby:2.1
D
Douwe Maan 已提交
85 86 87 88
services:
  - postgres

before_script:
F
frodsan 已提交
89
  - bundle install
D
Douwe Maan 已提交
90

91 92 93
after_script:
  - rm secrets

D
Douwe Maan 已提交
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
stages:
  - build
  - test
  - deploy

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

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

111
| Keyword       | Required | Description |
D
Douwe Maan 已提交
112
|---------------|----------|-------------|
113 114 115 116 117
| 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 |
118
| after_script  | no | Define commands that run after each job's script |
119 120
| variables     | no | Define build variables |
| cache         | no | Define list of files that should be cached between subsequent runs |
D
Douwe Maan 已提交
121 122

### image and services
123 124 125

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
126
[a separate document](../docker/README.md).
D
Douwe Maan 已提交
127 128

### before_script
129 130 131

`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 已提交
132

133 134
### after_script

K
Kamil Trzcinski 已提交
135
>**Note:**
M
Max Raab 已提交
136
Introduced in GitLab 8.7 and requires Gitlab Runner v1.2
K
Kamil Trzcinski 已提交
137

138 139 140
`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 已提交
141
### stages
142

D
Douwe Maan 已提交
143 144 145 146 147 148
`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.
149 150
1. Builds of the next stage are run after the jobs from the previous stage
   complete successfully.
D
Douwe Maan 已提交
151 152

Let's consider the following example, which defines 3 stages:
153 154

```yaml
D
Douwe Maan 已提交
155 156 157 158 159 160 161
stages:
  - build
  - test
  - deploy
```

1. First all jobs of `build` are executed in parallel.
162 163 164
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`.
165 166
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 已提交
167 168 169

There are also two edge cases worth mentioning:

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

### types
175

D
Douwe Maan 已提交
176 177 178 179
Alias for [stages](#stages).

### variables

180 181
>**Note:**
Introduced in GitLab Runner v0.5.0.
182

M
Mark Pundsack 已提交
183 184 185
GitLab CI allows you to add variables to `.gitlab-ci.yml` that are set in the
build environment. The variables are stored in the git repository and are meant
to store non-sensitive project configuration, for example:
D
Douwe Maan 已提交
186 187 188 189 190 191 192 193

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

These variables can be later used in all executed commands and scripts.

194 195
The YAML-defined variables are also set to all created service containers,
thus allowing to fine tune them.
D
Douwe Maan 已提交
196

197 198
Variables can be also defined on [job level](#job-variables).

199 200
### cache

201 202 203
>**Note:**
Introduced in GitLab Runner v0.7.0.

204
`cache` is used to specify a list of files and directories which should be
205 206 207
cached between builds.

**By default the caching is enabled per-job and per-branch.**
208 209 210

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

212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244
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/`:
245 246

```yaml
247 248
cache:
  paths:
249 250 251 252 253 254 255
  - my/files

rspec:
  script: test
  cache:
    paths:
    - binaries/
256 257
```

M
Mark Pundsack 已提交
258 259
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.
260

261 262
#### cache:key

263 264
>**Note:**
Introduced in GitLab Runner v1.0.0.
265 266 267 268 269

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.

270 271
This allows you to fine tune caching, allowing you to cache data between
different jobs or even different branches.
272

273 274 275 276 277
The `cache:key` variable can use any of the [predefined variables](../variables/README.md).

---

**Example configurations**
278 279 280

To enable per-job caching:

281 282 283 284 285
```yaml
cache:
  key: "$CI_BUILD_NAME"
  untracked: true
```
286 287 288

To enable per-branch caching:

289 290 291 292 293
```yaml
cache:
  key: "$CI_BUILD_REF_NAME"
  untracked: true
```
294 295 296

To enable per-job and per-branch caching:

297 298 299 300 301
```yaml
cache:
  key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME"
  untracked: true
```
302 303 304

To enable per-branch and per-stage caching:

305 306 307 308 309
```yaml
cache:
  key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME"
  untracked: true
```
310

311 312
If you use **Windows Batch** to run your shell scripts you need to replace
`$` with `%`:
313

314 315 316 317 318
```yaml
cache:
  key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%"
  untracked: true
```
319

D
Douwe Maan 已提交
320
## Jobs
321 322 323 324

`.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 已提交
325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341

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

342
| Keyword       | Required | Description |
D
Douwe Maan 已提交
343
|---------------|----------|-------------|
344
| script        | yes | Defines a shell script which is executed by Runner |
P
Pat Turner 已提交
345 346
| 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) |
347
| stage         | no | Defines a build stage (default: `test`) |
348
| type          | no | Alias for `stage` |
349
| variables     | no | Define build variables on a job level |
350 351
| 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 |
352
| tags          | no | Defines a list of tags which are used to select Runner |
353 354
| allow_failure | no | Allow build to fail. Failed build doesn't contribute to commit status |
| when          | no | Define when to run build. Can be `on_success`, `on_failure` or `always` |
355
| dependencies  | no | Define other builds that a build depends on so that you can pass artifacts between them|
A
Aurelio Jargas 已提交
356
| artifacts     | no | Define list of build artifacts |
357
| cache         | no | Define list of files that should be cached between subsequent runs |
358 359
| 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 |
360
| environment   | no | Defines a name of environment to which deployment is done by this build |
D
Douwe Maan 已提交
361 362

### script
363

364
`script` is a shell script which is executed by the Runner. For example:
D
Douwe Maan 已提交
365 366 367 368 369 370 371

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

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

D
Douwe Maan 已提交
373 374 375 376 377 378 379 380
```yaml
job:
  script:
    - uname -a
    - bundle exec rspec
```

### stage
381 382 383 384

`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 已提交
385 386 387

### only and except

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

391 392 393 394 395 396 397 398 399 400
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.
401
* `only` and `except` allow the use of special keywords: `branches`, `tags`, and `triggers`.
402 403 404 405 406
* `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 已提交
407 408 409

```yaml
job:
410
  # use regexp
D
Douwe Maan 已提交
411
  only:
412 413
    - /^issue-.*$/
  # use special keyword
D
Douwe Maan 已提交
414
  except:
415
    - branches
D
Douwe Maan 已提交
416 417
```

418 419 420 421 422 423 424 425 426 427 428
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
```

429 430
The repository path can be used to have jobs executed only for the parent
repository and not forks:
431 432 433 434 435 436 437 438

```yaml
job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce
```
439 440 441

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

443 444 445
### job variables

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

449
When the `variables` keyword is used on a job level, it overrides global YAML
450 451
build variables and predefined variables.

452 453
Build variables priority is defined in
[variables documentation](../variables/README.md).
454

D
Douwe Maan 已提交
455 456
### tags

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

460
During the registration of a Runner, you can specify the Runner's tags, for
461 462
example `ruby`, `postgres`, `development`.

463
`tags` allow you to run builds with Runners that have the specified tags
464 465 466
assigned to them:

```yaml
D
Douwe Maan 已提交
467 468 469 470 471 472
job:
  tags:
    - ruby
    - postgres
```

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

476
### when
477 478 479

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

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

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

491 492 493
For example:

```yaml
494 495 496 497 498 499 500
stages:
- build
- cleanup_build
- test
- deploy
- cleanup

501
build_job:
502 503 504 505
  stage: build
  script:
  - make build

506
cleanup_build_job:
507 508 509 510 511
  stage: cleanup_build
  script:
  - cleanup build when failed
  when: on_failure

512
test_job:
513 514 515 516
  stage: test
  script:
  - make test

517
deploy_job:
518 519 520
  stage: deploy
  script:
  - make deploy
521
  when: manual
522

523
cleanup_job:
524 525 526 527 528 529 530
  stage: cleanup
  script:
  - cleanup after builds
  when: always
```

The above script will:
531

532 533 534 535
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.
536 537 538 539 540 541

#### Manual actions

>**Note:**
Introduced in GitLab 8.10.

542 543 544 545
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.
546

547
An example usage of manual actions is deployment to production.
548

549 550 551
### environment

>**Note:**
M
Mark Pundsack 已提交
552
Introduced in GitLab 8.9.
553

M
Mark Pundsack 已提交
554 555 556
`environment` is used to define that a job deploys to a specific environment.
This allows easy tracking of all deployments to your environments straight from
GitLab.
557

M
Mark Pundsack 已提交
558 559
If `environment` is specified and no environment under that name exists, a new
one will be created automatically.
560

M
Mark Pundsack 已提交
561 562 563
The `environment` name must contain only letters, digits, '-' and '_'. Common
names are `qa`, `staging`, and `production`, but you can use whatever name works
with your workflow.
564 565 566 567 568 569 570 571 572 573 574 575

---

**Example configurations**

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

M
Mark Pundsack 已提交
576 577
The `deploy to production` job will be marked as doing deployment to
`production` environment.
578

K
Kamil Trzcinski 已提交
579 580
### artifacts

581 582 583
>**Notes:**
>
> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
584
> - Windows support was added in GitLab Runner v.1.0.0.
585
> - Currently not all executors are supported.
586
> - Build artifacts are only collected for successful builds by default.
587

588 589
`artifacts` is used to specify a list of files and directories which should be
attached to the build after success. To pass artifacts between different builds,
590 591 592
see [dependencies](#dependencies).

Below are some examples.
593

594
Send all files in `binaries` and `.config`:
595

596 597 598 599 600 601
```yaml
artifacts:
  paths:
  - binaries/
  - .config
```
602

603
Send all Git untracked files:
604

605 606 607 608 609
```yaml
artifacts:
  untracked: true
```

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

612 613 614 615 616 617
```yaml
artifacts:
  untracked: true
  paths:
  - binaries/
```
K
Kamil Trzcinski 已提交
618

619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640
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
```

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

644 645
#### artifacts:name

646 647
>**Note:**
Introduced in GitLab 8.6 and GitLab Runner v1.1.0.
648

A
Achilleas Pipinellis 已提交
649
The `name` directive allows you to define the name of the created artifacts
650
archive. That way, you can have a unique name for every archive which could be
A
Achilleas Pipinellis 已提交
651 652
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).
653
The default name is `artifacts`, which becomes `artifacts.zip` when downloaded.
654 655 656 657 658

---

**Example configurations**

A
Achilleas Pipinellis 已提交
659
To create an archive with a name of the current build:
660 661 662 663 664 665 666

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

A
Achilleas Pipinellis 已提交
667 668
To create an archive with a name of the current branch or tag including only
the files that are untracked by Git:
669 670 671 672 673 674 675 676

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

A
Achilleas Pipinellis 已提交
677 678
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:
679 680 681 682 683 684 685 686

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

A
Achilleas Pipinellis 已提交
687
To create an archive with a name of the current [stage](#stages) and branch name:
688 689 690 691 692 693 694 695

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

A
Achilleas Pipinellis 已提交
696 697
---

698 699 700 701 702 703 704 705 706 707
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
```

708 709 710 711 712 713 714 715 716 717
#### artifacts:when

>**Note:**
Introduced in GitLab 8.9 and GitLab Runner v1.3.0.

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

718 719 720
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.
721 722 723 724 725

---

**Example configurations**

K
Kamil Trzcinski 已提交
726
To upload artifacts only when build fails.
727 728 729 730 731 732 733

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

734 735 736 737 738
#### artifacts:expire_in

>**Note:**
Introduced in GitLab 8.9 and GitLab Runner v1.3.0.

739 740 741 742
`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.
743

744 745
You can use the **Keep** button on the build page to override expiration and
keep artifacts forever.
746

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

750
The value of `expire_in` is an elapsed time. Examples of parseable values:
751 752 753 754 755 756 757 758 759 760 761
- '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**

762
To expire artifacts 1 week after being uploaded:
763 764 765 766 767 768 769

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

770 771
### dependencies

772 773
>**Note:**
Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
774

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

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

780
To use this feature, define `dependencies` in context of the job and pass
781
a list of all previous builds from which the artifacts should be downloaded.
782 783
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.
784
Defining an empty array will skip downloading any artifacts for that job.
785 786

---
787

788 789 790 791 792 793 794
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:
795

796
```yaml
797 798
build:osx:
  stage: build
799
  script: make build:osx
800 801 802
  artifacts:
    paths:
    - binaries/
803

804 805
build:linux:
  stage: build
806
  script: make build:linux
807 808 809 810 811 812
  artifacts:
    paths:
    - binaries/

test:osx:
  stage: test
813
  script: make test:osx
814 815 816 817 818
  dependencies:
  - build:osx

test:linux:
  stage: test
819
  script: make test:linux
820 821 822 823 824
  dependencies:
  - build:linux

deploy:
  stage: deploy
825
  script: make deploy
826 827
```

828 829 830 831 832
### before_script and after_script

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

```yaml
P
Philipp Kraus 已提交
833
before_script:
834 835 836 837 838 839 840 841 842 843 844
- 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 已提交
845 846 847
## Git Strategy

>**Note:**
M
Mark Pundsack 已提交
848 849
Introduced in GitLab 8.9 as an experimental feature. May change in future
releases or be removed completely.
M
Mark Pundsack 已提交
850 851 852

You can set the `GIT_STRATEGY` used for getting recent application code. `clone`
is slower, but makes sure you have a clean directory before every build. `fetch`
M
Mark Pundsack 已提交
853 854 855
is faster. `GIT_STRATEGY` can be specified in the global `variables` section or
in the `variables` section for individual jobs. If it's not specified, then the
default from project settings will be used.
M
Mark Pundsack 已提交
856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871

```
variables:
  GIT_STRATEGY: clone
```

or

```
variables:
  GIT_STRATEGY: fetch
```

## Shallow cloning

>**Note:**
M
Mark Pundsack 已提交
872 873
Introduced in GitLab 8.9 as an experimental feature. May change in future
releases or be removed completely.
M
Mark Pundsack 已提交
874 875

You can specify the depth of fetching and cloning using `GIT_DEPTH`. This allows
M
Mark Pundsack 已提交
876 877 878
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 已提交
879

M
Mark Pundsack 已提交
880 881 882 883 884 885 886 887 888 889 890 891 892 893 894
>**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 已提交
895 896
```
variables:
M
Mark Pundsack 已提交
897
  GIT_DEPTH: "3"
M
Mark Pundsack 已提交
898 899
```

A
Achilleas Pipinellis 已提交
900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917
## Hidden jobs

>**Note:**
Introduced in GitLab 8.6 and GitLab Runner v1.1.1.

Jobs that start with a dot (`.`) will be not processed by GitLab CI. You can
use this feature to ignore jobs, or use the
[special YAML features](#special-yaml-features) and transform the hidden jobs
into templates.

In the following example, `.job_name` will be ignored:

```yaml
.job_name:
  script:
    - rake spec
```

918
## Special YAML features
919

920 921 922
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`.
923

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

926 927 928 929 930 931 932 933 934 935 936 937 938
### Anchors

>**Note:**
Introduced in GitLab 8.6 and GitLab Runner v1.1.1.

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

```yaml
941
.job_template: &job_definition  # Hidden job that defines an anchor named 'job_definition'
942 943 944 945 946 947
  image: ruby:2.1
  services:
    - postgres
    - redis

test1:
948
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
949
  script:
950
    - test1 project
951 952

test2:
953
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
954
  script:
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 980 981 982 983
    - 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
984 985
```

986 987 988 989
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:
990 991 992 993 994 995 996 997 998 999 1000

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

.postgres_services:
  services: &postgres_definition
    - postgres
    - ruby

1001
.mysql_services:
1002 1003 1004 1005 1006
  services: &mysql_definition
    - mysql
    - ruby

test:postgres:
A
Achilleas Pipinellis 已提交
1007
  <<: *job_definition
1008 1009 1010
  services: *postgres_definition

test:mysql:
A
Achilleas Pipinellis 已提交
1011
  <<: *job_definition
1012 1013 1014
  services: *mysql_definition
```

1015
The expanded version looks like this:
1016

1017 1018 1019 1020
```yaml
.job_template:
  script:
    - test project
1021

1022 1023 1024 1025
.postgres_services:
  services:
    - postgres
    - ruby
1026

1027 1028 1029 1030 1031 1032
.mysql_services:
  services:
    - mysql
    - ruby

test:postgres:
1033
  script:
1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044
    - test project
  services:
    - postgres
    - ruby

test:mysql:
  script:
    - test project
  services:
    - mysql
    - ruby
1045 1046
```

1047
You can see that the hidden jobs are conveniently used as templates.
1048

D
Douwe Maan 已提交
1049
## Validate the .gitlab-ci.yml
1050

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

## Skipping builds
1055

S
Simon Welsh 已提交
1056 1057
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 已提交
1058 1059 1060 1061 1062 1063 1064

## Examples

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

[examples]: ../examples/README.md