# Configuration of your builds with .gitlab-ci.yml
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
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.
...
...
@@ -23,12 +65,10 @@ Of course a command can execute code directly (`./configure;make;make install`)
or run a script (`test.sh`) in the repository.
Jobs are used to create builds, which are then picked up by
[runners](../runners/README.md) and executed within the environment of the
runner. What is important, is that each job is run independently from each
[Runners](../runners/README.md) and executed within the environment of the
Runner. What is important, is that each job is run independently from each
other.
## .gitlab-ci.yml
The YAML syntax allows for using more complex job specifications than in the
above example:
...
...
@@ -71,7 +111,7 @@ There are a few reserved `keywords` that **cannot** be used as job names:
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
separate document: [Use Docker](../docker/README.md).
[a separate document](../docker/README.md).
### before_script
...
...
@@ -86,7 +126,8 @@ 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.
1. Builds of next stage are run after success.
1. Builds of the next stage are run after the jobs from the previous stage
complete successfully.
Let's consider the following example, which defines 3 stages:
...
...
@@ -98,9 +139,9 @@ stages:
```
1. First all jobs of `build` are executed in parallel.
1. If all jobs of `build` succeeds, the `test` jobs are executed in parallel.
1. If all jobs of `test` succeeds, the `deploy` jobs are executed in parallel.
1. If all jobs of `deploy` succeeds, the commit is marked as `success`.
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`.
1. If any of the previous jobs fails, the commit is marked as `failed` and no
jobs of further stage are executed.
...
...
@@ -278,14 +319,14 @@ job_name:
| Keyword | Required | Description |
|---------------|----------|-------------|
| script | yes | Defines a shell script which is executed by runner |
| script | yes | Defines a shell script which is executed by Runner |
| image | no | Use docker image, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
| services | no | Use docker services, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
| stage | no | Defines a build stage (default: `test`) |
| 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 |
| tags | no | Defines a list of tags which are used to select runner |
| tags | no | Defines a list of tags which are used to select Runner |
| 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` |
| dependencies | no | Define other builds that a build depends on so that you can pass artifacts between them|
...
...
@@ -294,7 +335,7 @@ job_name:
### script
`script` is a shell script which is executed by the runner. For example:
`script` is a shell script which is executed by the Runner. For example:
```yaml
job:
...
...
@@ -375,13 +416,13 @@ except master.
### tags
`tags` is used to select specific runners from the list of all runners that are
`tags` is used to select specific Runners from the list of all Runners that are
allowed to run this project.
During the registration of a runner, you can specify the runner's tags, for
During the registration of a Runner, you can specify the Runner's tags, for
example `ruby`, `postgres`, `development`.
`tags` allow you to run builds with runners that have the specified tags
`tags` allow you to run builds with Runners that have the specified tags
assigned to them:
```yaml
...
...
@@ -391,7 +432,7 @@ job:
-postgres
```
The specification above, will make sure that `job` is built by a runner that
The specification above, will make sure that `job` is built by a Runner that
