parent
595aba54af
commit
072b9c2c8f
|
@ -1,5 +1,47 @@
|
|||
# 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
|
||||
has both `ruby` AND `postgres` tags defined.
|
||||
|
||||
### when
|
||||
|
|
Loading…
Reference in New Issue