parent
595aba54af
commit
072b9c2c8f
|
@ -1,5 +1,47 @@
|
||||||
# Configuration of your builds with .gitlab-ci.yml
|
# 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)
|
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
|
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.
|
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.
|
or run a script (`test.sh`) in the repository.
|
||||||
|
|
||||||
Jobs are used to create builds, which are then picked up by
|
Jobs are used to create builds, which are then picked up by
|
||||||
[runners](../runners/README.md) and executed within the environment of the
|
[Runners](../runners/README.md) and executed within the environment of the
|
||||||
runner. What is important, is that each job is run independently from each
|
Runner. What is important, is that each job is run independently from each
|
||||||
other.
|
other.
|
||||||
|
|
||||||
## .gitlab-ci.yml
|
|
||||||
|
|
||||||
The YAML syntax allows for using more complex job specifications than in the
|
The YAML syntax allows for using more complex job specifications than in the
|
||||||
above example:
|
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
|
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
|
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
|
### 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:
|
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 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:
|
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. 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 `build` succeed, 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 `test` succeed, 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 `deploy` succeed, the commit is marked as `success`.
|
||||||
1. If any of the previous jobs fails, the commit is marked as `failed` and no
|
1. If any of the previous jobs fails, the commit is marked as `failed` and no
|
||||||
jobs of further stage are executed.
|
jobs of further stage are executed.
|
||||||
|
|
||||||
|
@ -278,14 +319,14 @@ job_name:
|
||||||
|
|
||||||
| Keyword | Required | Description |
|
| 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) |
|
| 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) |
|
| 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`) |
|
| stage | no | Defines a build stage (default: `test`) |
|
||||||
| type | no | Alias for `stage` |
|
| type | no | Alias for `stage` |
|
||||||
| only | no | Defines a list of git refs for which build is created |
|
| 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 |
|
| 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 |
|
| 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` |
|
| 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|
|
| 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
|
||||||
|
|
||||||
`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
|
```yaml
|
||||||
job:
|
job:
|
||||||
|
@ -375,13 +416,13 @@ except master.
|
||||||
|
|
||||||
### tags
|
### 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.
|
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`.
|
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:
|
assigned to them:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
@ -391,7 +432,7 @@ job:
|
||||||
- postgres
|
- 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
|
||||||
has both `ruby` AND `postgres` tags defined.
|
has both `ruby` AND `postgres` tags defined.
|
||||||
|
|
||||||
### when
|
### when
|
||||||
|
|
Loading…
Reference in New Issue