2015-08-25 21:42:46 -04:00
# Configuration of your builds with .gitlab-ci.yml
2016-04-14 08:40:05 -04:00
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 )
- [image and services ](#image-and-services )
- [before_script ](#before_script )
- [stages ](#stages )
- [types ](#types )
- [variables ](#variables )
- [cache ](#cache )
- [cache:key ](#cache-key )
- [Jobs ](#jobs )
- [script ](#script )
- [stage ](#stage )
- [only and except ](#only-and-except )
- [tags ](#tags )
- [when ](#when )
- [artifacts ](#artifacts )
- [artifacts:name ](#artifacts-name )
- [dependencies ](#dependencies )
- [Hidden jobs ](#hidden-jobs )
- [Special YAML features ](#special-yaml-features )
- [Anchors ](#anchors )
- [Validate the .gitlab-ci.yml ](#validate-the-gitlab-ci-yml )
- [Skipping builds ](#skipping-builds )
- [Examples ](#examples )
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
---
## .gitlab-ci.yml
2015-12-10 08:56:20 -05:00
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
to contain the `script` clause:
2015-08-25 21:42:46 -04:00
```yaml
job1:
script: "execute-script-for-job1"
job2:
script: "execute-script-for-job2"
```
2015-12-10 08:56:20 -05:00
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.
2015-08-25 21:42:46 -04:00
2015-12-10 08:56:20 -05:00
Jobs are used to create builds, which are then picked up by
2016-04-14 08:40:05 -04:00
[Runners ](../runners/README.md ) and executed within the environment of the
Runner. What is important, is that each job is run independently from each
2015-12-10 08:56:20 -05:00
other.
2015-08-25 21:42:46 -04:00
2015-12-10 08:56:20 -05:00
The YAML syntax allows for using more complex job specifications than in the
above example:
2015-08-25 21:42:46 -04:00
```yaml
2016-02-19 09:59:46 -05:00
image: ruby:2.1
2015-08-25 21:42:46 -04:00
services:
- postgres
before_script:
2016-04-06 18:45:56 -04:00
- bundle install
2015-08-25 21:42:46 -04:00
stages:
- build
- test
- deploy
job1:
stage: build
script:
- execute-script-for-job1
only:
- master
tags:
- docker
```
2015-12-10 08:56:20 -05:00
There are a few reserved `keywords` that **cannot** be used as job names:
2015-08-25 21:42:46 -04:00
2015-12-10 08:56:20 -05:00
| Keyword | Required | Description |
2015-08-25 21:42:46 -04:00
|---------------|----------|-------------|
2015-12-10 08:56:20 -05:00
| 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 |
| variables | no | Define build variables |
| cache | no | Define list of files that should be cached between subsequent runs |
2015-08-25 21:42:46 -04:00
### image and services
2015-12-10 08:56:20 -05:00
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
2016-04-14 08:40:05 -04:00
[a separate document ](../docker/README.md ).
2015-08-25 21:42:46 -04:00
### before_script
2015-12-10 08:56:20 -05:00
`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.
2015-08-25 21:42:46 -04:00
### stages
2015-12-10 08:56:20 -05:00
2015-08-25 21:42:46 -04:00
`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.
2016-04-14 08:40:05 -04:00
1. Builds of the next stage are run after the jobs from the previous stage
complete successfully.
2015-08-25 21:42:46 -04:00
Let's consider the following example, which defines 3 stages:
2015-12-10 08:56:20 -05:00
```yaml
2015-08-25 21:42:46 -04:00
stages:
- build
- test
- deploy
```
1. First all jobs of `build` are executed in parallel.
2016-04-14 08:40:05 -04:00
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` .
2015-12-10 08:56:20 -05:00
1. If any of the previous jobs fails, the commit is marked as `failed` and no
jobs of further stage are executed.
2015-08-25 21:42:46 -04:00
There are also two edge cases worth mentioning:
2015-12-10 08:56:20 -05:00
1. If no `stages` is defined in `.gitlab-ci.yml` , then by default the `build` ,
`test` and `deploy` are allowed to be used as job's stage by default.
2015-08-25 21:42:46 -04:00
2. If a job doesn't specify `stage` , the job is assigned the `test` stage.
### types
2015-12-10 08:56:20 -05:00
2015-08-25 21:42:46 -04:00
Alias for [stages ](#stages ).
### variables
2016-03-12 13:22:38 -05:00
>**Note:**
Introduced in GitLab Runner v0.5.0.
2015-12-10 08:56:20 -05:00
GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in build
environment. The variables are stored in the git repository and are meant to
store non-sensitive project configuration, for example:
2015-08-25 21:42:46 -04:00
```yaml
variables:
DATABASE_URL: "postgres://postgres@postgres/my_database"
```
These variables can be later used in all executed commands and scripts.
2015-12-10 08:56:20 -05:00
The YAML-defined variables are also set to all created service containers,
thus allowing to fine tune them.
2015-08-25 21:42:46 -04:00
2015-11-10 16:48:13 -05:00
### cache
2016-03-14 13:28:23 -04:00
>**Note:**
Introduced in GitLab Runner v0.7.0.
2015-12-10 08:56:20 -05:00
`cache` is used to specify a list of files and directories which should be
2016-01-14 11:52:59 -05:00
cached between builds.
**By default the caching is enabled per-job and per-branch.**
2015-12-10 08:56:20 -05:00
If `cache` is defined outside the scope of the jobs, it means it is set
globally and all jobs will use its definition.
2015-11-10 16:48:13 -05:00
2016-03-14 13:28:23 -04:00
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/` :
2015-12-10 08:56:20 -05:00
```yaml
2015-11-10 16:48:13 -05:00
cache:
paths:
2016-03-14 13:28:23 -04:00
- my/files
rspec:
script: test
cache:
paths:
- binaries/
2015-11-10 16:48:13 -05:00
```
2016-03-14 13:28:23 -04:00
The cache is provided on best effort basis, so don't expect that cache will be
always present. For implementation details please check GitLab Runner.
2016-01-14 11:52:59 -05:00
#### cache:key
2016-03-14 13:28:23 -04:00
>**Note:**
Introduced in GitLab Runner v1.0.0.
2016-01-14 11:52:59 -05:00
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.
2016-01-22 06:33:37 -05:00
This allows you to fine tune caching, allowing you to cache data between
different jobs or even different branches.
2016-01-14 11:52:59 -05:00
2016-01-22 06:33:37 -05:00
The `cache:key` variable can use any of the [predefined variables ](../variables/README.md ).
---
**Example configurations**
2016-01-14 11:52:59 -05:00
To enable per-job caching:
2016-01-22 06:33:37 -05:00
```yaml
cache:
key: "$CI_BUILD_NAME"
untracked: true
```
2016-01-14 11:52:59 -05:00
To enable per-branch caching:
2016-01-22 06:33:37 -05:00
```yaml
cache:
key: "$CI_BUILD_REF_NAME"
untracked: true
```
2016-01-14 11:52:59 -05:00
To enable per-job and per-branch caching:
2016-01-22 06:33:37 -05:00
```yaml
cache:
key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME"
untracked: true
```
2016-01-14 11:52:59 -05:00
To enable per-branch and per-stage caching:
2016-01-22 06:33:37 -05:00
```yaml
cache:
key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME"
untracked: true
```
2016-01-14 11:52:59 -05:00
2016-01-22 06:33:37 -05:00
If you use **Windows Batch** to run your shell scripts you need to replace
`$` with `%` :
2016-01-14 11:52:59 -05:00
2016-01-22 06:33:37 -05:00
```yaml
cache:
key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%"
untracked: true
```
2016-01-14 11:52:59 -05:00
2015-08-25 21:42:46 -04:00
## Jobs
2015-12-10 08:56:20 -05:00
`.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.
2015-08-25 21:42:46 -04:00
```yaml
job_name:
script:
- rake spec
- coverage
stage: test
only:
- master
except:
- develop
tags:
- ruby
- postgres
allow_failure: true
```
2015-12-10 08:56:20 -05:00
| Keyword | Required | Description |
2015-08-25 21:42:46 -04:00
|---------------|----------|-------------|
2016-04-14 08:40:05 -04:00
| script | yes | Defines a shell script which is executed by Runner |
2016-03-18 07:46:19 -04:00
| 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 ) |
2016-03-13 03:57:36 -04:00
| stage | no | Defines a build stage (default: `test` ) |
2015-12-10 08:56:20 -05:00
| type | no | Alias for `stage` |
| 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 |
2016-04-14 08:40:05 -04:00
| tags | no | Defines a list of tags which are used to select Runner |
2015-12-10 08:56:20 -05:00
| 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` |
2016-03-13 03:57:36 -04:00
| dependencies | no | Define other builds that a build depends on so that you can pass artifacts between them|
2015-12-10 08:56:20 -05:00
| artifacts | no | Define list build artifacts |
| cache | no | Define list of files that should be cached between subsequent runs |
2015-08-25 21:42:46 -04:00
### script
2015-12-10 08:56:20 -05:00
2016-04-14 08:40:05 -04:00
`script` is a shell script which is executed by the Runner. For example:
2015-08-25 21:42:46 -04:00
```yaml
job:
script: "bundle exec rspec"
```
This parameter can also contain several commands using an array:
2015-12-10 08:56:20 -05:00
2015-08-25 21:42:46 -04:00
```yaml
job:
script:
- uname -a
- bundle exec rspec
```
### stage
2015-12-10 08:56:20 -05:00
`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 ).
2015-08-25 21:42:46 -04:00
### only and except
2015-12-10 08:56:20 -05:00
`only` and `except` are two parameters that set a refs policy to limit when
jobs are built:
2015-08-25 21:42:46 -04:00
2015-12-10 08:56:20 -05:00
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.
2016-03-15 09:46:09 -04:00
* `only` and `except` allow the use of special keywords: `branches` , `tags` , and `triggers` .
2015-12-10 08:56:20 -05:00
* `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.
2015-08-25 21:42:46 -04:00
```yaml
job:
2015-12-10 08:56:20 -05:00
# use regexp
2015-08-25 21:42:46 -04:00
only:
2015-12-10 08:56:20 -05:00
- /^issue-.*$/
# use special keyword
2015-08-25 21:42:46 -04:00
except:
2015-12-10 08:56:20 -05:00
- branches
2015-08-25 21:42:46 -04:00
```
2016-03-15 09:46:09 -04:00
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
```
2015-12-10 08:56:20 -05:00
The repository path can be used to have jobs executed only for the parent
repository and not forks:
2015-11-02 08:44:06 -05:00
```yaml
job:
only:
- branches@gitlab-org/gitlab-ce
except:
- master@gitlab-org/gitlab-ce
```
2015-12-10 08:56:20 -05:00
The above example will run `job` for all branches on `gitlab-org/gitlab-ce` ,
except master.
2015-11-02 08:44:06 -05:00
2015-08-25 21:42:46 -04:00
### tags
2016-04-14 08:40:05 -04:00
`tags` is used to select specific Runners from the list of all Runners that are
2015-12-10 08:56:20 -05:00
allowed to run this project.
2015-08-25 21:42:46 -04:00
2016-04-14 08:40:05 -04:00
During the registration of a Runner, you can specify the Runner's tags, for
2015-12-10 08:56:20 -05:00
example `ruby` , `postgres` , `development` .
2016-04-14 08:40:05 -04:00
`tags` allow you to run builds with Runners that have the specified tags
2015-12-10 08:56:20 -05:00
assigned to them:
```yaml
2015-08-25 21:42:46 -04:00
job:
tags:
- ruby
- postgres
```
2016-04-14 08:40:05 -04:00
The specification above, will make sure that `job` is built by a Runner that
2015-12-10 08:56:20 -05:00
has both `ruby` AND `postgres` tags defined.
2015-08-25 21:42:46 -04:00
2015-10-15 09:08:31 -04:00
### when
2015-12-10 08:56:20 -05:00
`when` is used to implement jobs that are run in case of failure or despite the
failure.
2015-10-15 09:08:31 -04:00
2015-10-15 19:46:01 -04:00
`when` can be set to one of the following values:
2015-12-10 08:56:20 -05:00
1. `on_success` - execute build only when all builds from prior stages
succeeded. This is the default.
1. `on_failure` - execute build only when at least one build from prior stages
failed.
2015-10-15 09:08:31 -04:00
1. `always` - execute build despite the status of builds from prior stages.
2015-12-10 08:56:20 -05:00
For example:
```yaml
2015-10-15 09:08:31 -04:00
stages:
- build
- cleanup_build
- test
- deploy
- cleanup
2015-12-10 08:56:20 -05:00
build_job:
2015-10-15 09:08:31 -04:00
stage: build
script:
- make build
2015-12-10 08:56:20 -05:00
cleanup_build_job:
2015-10-15 09:08:31 -04:00
stage: cleanup_build
script:
- cleanup build when failed
when: on_failure
2015-12-10 08:56:20 -05:00
test_job:
2015-10-15 09:08:31 -04:00
stage: test
script:
- make test
2015-12-10 08:56:20 -05:00
deploy_job:
2015-10-15 09:08:31 -04:00
stage: deploy
script:
- make deploy
2015-12-10 08:56:20 -05:00
cleanup_job:
2015-10-15 09:08:31 -04:00
stage: cleanup
script:
- cleanup after builds
when: always
```
The above script will:
2015-12-10 08:56:20 -05:00
1. Execute `cleanup_build_job` only when `build_job` fails
2. Always execute `cleanup_job` as the last step in pipeline.
2015-10-15 09:08:31 -04:00
2015-10-12 17:47:32 -04:00
### artifacts
2016-03-12 13:22:38 -05:00
>**Notes:**
>
> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
2016-03-15 06:46:21 -04:00
> - Windows support was added in GitLab Runner v.1.0.0.
2016-03-12 13:22:38 -05:00
> - Currently not all executors are supported.
> - Build artifacts are only collected for successful builds.
2015-11-21 14:25:07 -05:00
2015-12-10 08:56:20 -05:00
`artifacts` is used to specify list of files and directories which should be
2016-03-13 03:57:36 -04:00
attached to build after success. To pass artifacts between different builds,
see [dependencies ](#dependencies ).
Below are some examples.
2015-11-09 06:18:00 -05:00
2015-12-10 08:56:20 -05:00
Send all files in `binaries` and `.config` :
2015-11-21 14:25:07 -05:00
2015-12-10 08:56:20 -05:00
```yaml
artifacts:
paths:
- binaries/
- .config
```
2015-11-09 06:18:00 -05:00
2016-03-17 09:56:44 -04:00
Send all Git untracked files:
2015-11-21 14:25:07 -05:00
2015-12-10 08:56:20 -05:00
```yaml
artifacts:
untracked: true
```
2016-03-17 09:56:44 -04:00
Send all Git untracked files and files in `binaries` :
2015-10-12 17:47:32 -04:00
2015-12-10 08:56:20 -05:00
```yaml
artifacts:
untracked: true
paths:
- binaries/
```
2015-10-12 17:47:32 -04:00
2016-01-29 05:44:25 -05:00
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
```
2016-02-03 05:45:07 -05:00
The artifacts will be sent to GitLab after a successful build and will
be available for download in the GitLab UI.
2015-10-12 17:47:32 -04:00
2016-03-11 07:43:57 -05:00
#### artifacts:name
2016-03-12 13:22:38 -05:00
>**Note:**
Introduced in GitLab 8.6 and GitLab Runner v1.1.0.
2016-03-11 07:43:57 -05:00
2016-03-13 03:33:10 -04:00
The `name` directive allows you to define the name of the created artifacts
archive. That way, you can have a unique name of every archive which could be
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 ).
2016-03-11 07:43:57 -05:00
---
**Example configurations**
2016-03-13 03:33:10 -04:00
To create an archive with a name of the current build:
2016-03-11 07:43:57 -05:00
```yaml
job:
artifacts:
name: "$CI_BUILD_NAME"
```
2016-03-13 03:33:10 -04:00
To create an archive with a name of the current branch or tag including only
the files that are untracked by Git:
2016-03-11 07:43:57 -05:00
```yaml
job:
artifacts:
name: "$CI_BUILD_REF_NAME"
untracked: true
```
2016-03-13 03:33:10 -04:00
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:
2016-03-11 07:43:57 -05:00
```yaml
job:
artifacts:
name: "${CI_BUILD_NAME}_${CI_BUILD_REF_NAME}"
untracked: true
```
2016-03-13 03:33:10 -04:00
To create an archive with a name of the current [stage ](#stages ) and branch name:
2016-03-11 07:43:57 -05:00
```yaml
job:
artifacts:
name: "${CI_BUILD_STAGE}_${CI_BUILD_REF_NAME}"
untracked: true
```
2016-03-13 03:33:10 -04:00
---
2016-03-11 07:43:57 -05:00
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
```
2016-03-11 08:15:13 -05:00
### dependencies
2016-03-12 13:22:38 -05:00
>**Note:**
Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
2016-03-11 08:15:13 -05:00
2016-03-13 03:57:36 -04:00
This feature should be used in conjunction with [`artifacts` ](#artifacts ) and
allows you to define the artifacts to pass between different builds.
2016-03-11 08:15:13 -05:00
2016-03-13 03:57:36 -04:00
Note that `artifacts` from previous [stages ](#stages ) are passed by default.
2016-03-11 08:15:13 -05:00
2016-03-13 03:57:36 -04:00
To use this feature, define `dependencies` in context of the job and pass
2016-03-11 08:15:13 -05:00
a list of all previous builds from which the artifacts should be downloaded.
2016-03-13 03:57:36 -04:00
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.
---
2016-03-11 08:15:13 -05:00
2016-03-13 03:57:36 -04:00
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:
2016-03-11 08:15:13 -05:00
2016-03-14 04:14:32 -04:00
```yaml
2016-03-11 08:15:13 -05:00
build:osx:
stage: build
2016-03-13 03:57:36 -04:00
script: make build:osx
2016-03-11 08:15:13 -05:00
artifacts:
paths:
- binaries/
2016-03-12 13:22:38 -05:00
2016-03-11 08:15:13 -05:00
build:linux:
stage: build
2016-03-13 03:57:36 -04:00
script: make build:linux
2016-03-11 08:15:13 -05:00
artifacts:
paths:
- binaries/
test:osx:
stage: test
2016-03-13 03:57:36 -04:00
script: make test:osx
2016-03-11 08:15:13 -05:00
dependencies:
- build:osx
test:linux:
stage: test
2016-03-13 03:57:36 -04:00
script: make test:linux
2016-03-11 08:15:13 -05:00
dependencies:
- build:linux
deploy:
stage: deploy
2016-03-13 03:57:36 -04:00
script: make deploy
2016-03-11 08:15:13 -05:00
```
2016-03-13 03:35:40 -04:00
## 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
```
2016-03-13 03:34:46 -04:00
## Special YAML features
2016-03-11 07:39:11 -05:00
2016-03-13 03:34:46 -04:00
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` .
2016-03-11 07:39:11 -05:00
2016-03-13 03:34:46 -04:00
Read more about the various [YAML features ](https://learnxinyminutes.com/docs/yaml/ ).
2016-03-11 07:39:11 -05:00
2016-03-13 03:34:46 -04:00
### 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:
2016-03-11 07:39:11 -05:00
```yaml
2016-03-13 03:34:46 -04:00
.job_template: & job_definition # Hidden job that defines an anchor named 'job_definition'
2016-03-11 07:39:11 -05:00
image: ruby:2.1
services:
- postgres
- redis
test1:
2016-03-13 03:34:46 -04:00
< < : * job_definition # Merge the contents of the ' job_definition ' alias
2016-03-11 07:39:11 -05:00
script:
2016-03-13 03:34:46 -04:00
- test1 project
2016-03-11 07:39:11 -05:00
test2:
2016-03-13 03:34:46 -04:00
< < : * job_definition # Merge the contents of the ' job_definition ' alias
2016-03-11 07:39:11 -05:00
script:
2016-03-13 03:34:46 -04:00
- 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
2016-03-11 07:39:11 -05:00
```
2016-03-13 03:34:46 -04:00
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:
2016-03-11 07:39:11 -05:00
```yaml
.job_template: & job_definition
script:
- test project
.postgres_services:
services: & postgres_definition
- postgres
- ruby
2016-03-12 13:22:38 -05:00
.mysql_services:
2016-03-11 07:39:11 -05:00
services: & mysql_definition
- mysql
- ruby
test:postgres:
< < *job_definition
services: *postgres_definition
test:mysql:
< < *job_definition
services: *mysql_definition
```
2016-03-13 03:34:46 -04:00
The expanded version looks like this:
2016-03-11 07:39:11 -05:00
2016-03-13 03:34:46 -04:00
```yaml
.job_template:
script:
- test project
2016-03-11 07:39:11 -05:00
2016-03-13 03:34:46 -04:00
.postgres_services:
services:
- postgres
- ruby
2016-03-11 07:39:11 -05:00
2016-03-13 03:34:46 -04:00
.mysql_services:
services:
- mysql
- ruby
test:postgres:
2016-03-11 07:39:11 -05:00
script:
2016-03-13 03:34:46 -04:00
- test project
services:
- postgres
- ruby
test:mysql:
script:
- test project
services:
- mysql
- ruby
2016-03-11 07:39:11 -05:00
```
2016-03-13 03:34:46 -04:00
You can see that the hidden jobs are conveniently used as templates.
2016-03-11 07:39:11 -05:00
2015-08-25 21:42:46 -04:00
## Validate the .gitlab-ci.yml
2015-12-10 08:56:20 -05:00
2015-08-25 21:42:46 -04:00
Each instance of GitLab CI has an embedded debug tool called Lint.
2015-12-10 08:56:20 -05:00
You can find the link under `/ci/lint` of your gitlab instance.
2015-08-25 21:42:46 -04:00
## Skipping builds
2015-12-10 08:56:20 -05:00
If your commit message contains `[ci skip]` , the commit will be created but the
builds will be skipped.
2016-02-29 07:50:08 -05:00
## Examples
Visit the [examples README][examples] to see a list of examples using GitLab
CI with various languages.
[examples]: ../examples/README.md