@@ -11,11 +11,11 @@ description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Inte
CI/CD is a vast area, so GitLab provides documentation for all levels of expertise. Consult the following table to find the right documentation for you:
| New to the concepts of CI and CD | For a high-level overview, read an [introduction to CI/CD with GitLab](introduction/index.md). |
| Familiar with GitLab CI/CD concepts | After getting familiar with GitLab CI/CD, let us walk you through a simple example in our [quick start guide](quick_start/README.md). |
| A GitLab CI/CD expert | Jump straight to our [`.gitlab.yml`](yaml/README.md) reference. |
| New to the concepts of CI and CD | For a high-level overview, read an [introduction to CI/CD with GitLab](introduction/index.md). |
| Familiar with GitLab CI/CD concepts | After getting familiar with GitLab CI/CD, let us walk you through a simple example in our [quick start guide](quick_start/README.md). |
| A GitLab CI/CD expert | Jump straight to our [`.gitlab.yml`](yaml/README.md) reference. |
NOTE: **Note:**
Within the [DevOps lifecycle](../README.md#the-entire-devops-lifecycle), GitLab CI/CD spans
...
...
@@ -25,12 +25,12 @@ the [Verify (CI)](../README.md#verify) and [Release (CD)](../README.md#release)
The following documentation provides the minimum required knowledge for making use of GitLab CI/CD:
| [Getting started with GitLab CI/CD](quick_start/README.md)| Outlines the first steps for configuring GitLab CI/CD. |
| [Introduction to pipelines and jobs](pipelines.md)| Provides an overview of GitLab CI/CD and jobs. |
| [Configuration of your pipelines with `.gitlab-ci.yml`](yaml/README.md)| A comprehensive reference for the `.gitlab-ci.yml` file. |
| [`.gitlab-ci.yml` introduction](../user/project/pages/getting_started_part_four.md)| A step-by-step introduction to writing a GitLab CI/CD configuration file (`.gitlab-ci.yml`) for the first time. |
| [Getting started with GitLab CI/CD](quick_start/README.md) | Outlines the first steps for configuring GitLab CI/CD. |
| [Introduction to pipelines and jobs](pipelines.md) | Provides an overview of GitLab CI/CD and jobs. |
| [Configuration of your pipelines with `.gitlab-ci.yml`](yaml/README.md) | A comprehensive reference for the `.gitlab-ci.yml` file. |
| [`.gitlab-ci.yml` introduction](../user/project/pages/getting_started_part_four.md) | A step-by-step introduction to writing a GitLab CI/CD configuration file (`.gitlab-ci.yml`) for the first time. |
NOTE: **Note:**
Familiarity with [GitLab Runner](https://docs.gitlab.com/runner/) is useful because it is
# Configuration of your pipelines with .gitlab-ci.yml
# GitLab CI/CD Pipeline Configuration Reference
This document describes the usage of `.gitlab-ci.yml`, the file that is used by
GitLab Runner to manage your project's pipelines.
GitLab CI/CD [pipelines](../pipelines.md) are configured using a YAML file called `.gitlab-ci.yml` within each project.
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 `.gitlab-ci.yml` file defines the structure and order of the pipelines and determines:
If you want a quick introduction to GitLab CI, follow our
[quick start guide](../quick_start/README.md).
- What to execute using [GitLab Runner](https://docs.gitlab.com/runner/).
- What decisions to make when specific conditions are encountered. For example, when a process succeeds or fails.
This topic covers CI/CD pipeline configuration. For other CI/CD configuration information, see:
-[GitLab CI/CD Variables](../variables/README.md), for configuring the environment the pipelines run in.
-[GitLab Runner advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html), for configuring GitLab Runner.
We have complete examples of configuring pipelines:
- For a quick introduction to GitLab CI, follow our [quick start guide](../quick_start/README.md).
- For a collection of examples, see [GitLab CI/CD Examples](../examples/README.md).
- To see a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab-ce`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml).
NOTE: **Note:**
If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository-starter),
you may need to enable pipeline triggering in your project's
**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.
## Jobs
## Introduction
Pipeline configuration begins with jobs. Jobs are the most fundamental element of a `.gitlab-ci.yml` file.
The YAML file defines a set of jobs with constraints stating when they should
be run. You can specify an unlimited number of jobs which are defined as
top-level elements with an arbitrary name and always have to contain at least
the `script` clause.
Jobs are:
- Defined with constraints stating under what conditions they should be executed.
- Top-level elements with an arbitrary name and must contain at least the [`script`](#script) clause.
- Not limited in how many can be defined.
For example:
```yaml
job1:
...
...
@@ -39,6 +52,14 @@ Jobs are 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 other.
### Validate the .gitlab-ci.yml
Each instance of GitLab CI has an embedded debug tool called Lint, which validates the
content of your `.gitlab-ci.yml` files. You can find the Lint under the page `ci/lint` of your
project namespace. For example, `http://gitlab.example.com/gitlab-org/project-123/-/ci/lint`.
### Unavailable names for jobs
Each job must have a unique name, but there are a few **reserved `keywords` that
cannot be used as job names**:
...
...
@@ -51,42 +72,137 @@ cannot be used as job names**:
-`variables`
-`cache`
A job is defined by a list of parameters that define the job behavior.
| Keyword | Required | Description |
|---------------|----------|-------------|
| [script](#script) | yes | Defines a shell script which is executed by Runner |
| [extends](#extends) | no | Defines a configuration entry that this job is going to inherit from |
| [include](#include) | no | Defines a configuration entry that allows this job to include external YAML files |
| [image](#image-and-services) | no | Use docker image, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
| [services](#image-and-services) | no | Use docker services, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
| [stage](#stage) | no | Defines a job stage (default: `test`) |
| type | no | Alias for `stage` |
| [variables](#variables) | no | Define job variables on a job level |
| [only](#only-and-except-simplified) | no | Defines a list of git refs for which job is created |
| [except](#only-and-except-simplified) | no | Defines a list of git refs for which job is not created |
| [tags](#tags) | no | Defines a list of tags which are used to select Runner |
| [allow_failure](#allow_failure) | no | Allow job to fail. Failed job doesn't contribute to commit status |
| [when](#when) | no | Define when to run job. Can be `on_success`, `on_failure`, `always` or `manual` |
| [dependencies](#dependencies) | no | Define other jobs that a job depends on so that you can pass artifacts between them|
| [artifacts](#artifacts) | no | Define list of [job artifacts](#artifacts) |
| [cache](#cache) | no | Define list of files that should be cached between subsequent runs |
| [before_script](#before_script-and-after_script) | no | Override a set of commands that are executed before job |
| [after_script](#before_script-and-after_script) | no | Override a set of commands that are executed after job |
| [environment](#environment) | no | Defines a name of environment to which deployment is done by this job |
| [coverage](#coverage) | no | Define code coverage settings for a given job |
| [retry](#retry) | no | Define when and how many times a job can be auto-retried in case of a failure |
| [parallel](#parallel) | no | Defines how many instances of a job should be run in parallel |
## `image` and `services`
This allows to specify a custom Docker image and a list of services that can be
used for time of the job. The configuration of this feature is covered in
[a separate document](../docker/README.md).
## `before_script` and `after_script`
> Introduced in GitLab 8.7 and requires GitLab Runner v1.2
### Using reserved keywords
If you get validation error when using specific values (for example, `true` or `false`), try to:
- Quote them.
- Change them to a different form. For example, `/bin/true`.
## Configuration parameters
A job is defined as a list of parameters that define the job's behavior.
The following table lists available parameters for jobs:
| [`script`](#script) | Shell script which is executed by Runner. |
| [`image`](#image) | Use docker images. Also available: `image:name` and `image:entrypoint`. |
| [`services`](#services) | Use docker services images. Also available: `services:name`, `services:alias`, `services:entrypoint`, and `services:command`. |
| [`before_script`](#before_script-and-after_script) | Override a set of commands that are executed before job. |
| [`after_script`](#before_script-and-after_script) | Override a set of commands that are executed after job. |
| [`stages`](#stages) | Define stages in a pipeline. |
| [`stage`](#stage) | Defines a job stage (default: `test`). |
| [`only`](#onlyexcept-basic) | Limit when jobs are created. Also available: [`only:refs`, `only:kubernetes`, `only:variables`, and `only:changes`](#onlyexcept-advanced). |
| [`except`](#onlyexcept-basic) | Limit when jobs are not created. Also available: [`except:refs`, `except:kubernetes`, `except:variables`, and `except:changes`](#onlyexcept-advanced). |
| [`tags`](#tags) | List of tags which are used to select Runner. |
| [`allow_failure`](#allow_failure) | Allow job to fail. Failed job doesn't contribute to commit status. |
| [`when`](#when) | When to run job. Also available: `when:manual` and `when:delayed`. |
| [`environment`](#environment) | Name of an environment to which the job deploys. Also available: `environment:name`, `environment:url`, `environment:on_stop`, and `environment:action`. |
| [`cache`](#cache) | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, and `cache:policy`. |
| [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, `artifacts:reports`, and `artifacts:reports:junit`.<br><br>In GitLab [Enterprise Edition](https://about.gitlab.com/pricing/), these are available: `artifacts:reports:codequality`, `artifacts:reports:sast`, `artifacts:reports:dependency_scanning`, `artifacts:reports:container_scanning`, `artifacts:reports:dast`, `artifacts:reports:license_management`, and `artifacts:reports:performance`. |
| [`dependencies`](#dependencies) | Other jobs that a job depends on so that you can pass artifacts between them. |
| [`coverage`](#coverage) | Code coverage settings for a given job. |
| [`retry`](#retry) | When and how many times a job can be auto-retried in case of a failure. |
| [`parallel`](#parallel) | How many instances of a job should be run in parallel. |
| [`trigger`](#trigger-premium) | Defines a downstream pipeline trigger. |
| [`include`](#include) | Allows this job to include external YAML files. Also available: `include:local`, `include:file`, `include:template`, and `include:remote`. |
| [`extends`](#extends) | Configuration entry that this job is going to inherit from. |
| [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. |
| [`variables`](#variables) | Define job variables on a job level. |
NOTE: **Note:**
Parameters `types` and `type` are [deprecated](#deprecated-parameters).
## Parameter details
The following are detailed explanations for parameters used to configure CI/CD pipelines.
### `script`
`script` is the only required keyword that a job needs. It's a shell script
which is executed by the Runner. For example:
```yaml
job:
script:"bundleexecrspec"
```
This parameter can also contain several commands using an array:
```yaml
job:
script:
-uname -a
-bundle exec rspec
```
NOTE: **Note:**
Sometimes, `script` commands will need to be wrapped in single or double quotes.
For example, commands that contain a colon (`:`) need to be wrapped in quotes so
that the YAML parser knows to interpret the whole thing as a string rather than
a "key: value" pair. Be careful when using special characters:
Used to specify [a Docker image](../docker/using_docker_images.md#what-is-an-image) to use for the job.
For:
- Simple definition examples, see [Define `image` and `services` from .gitlab-ci.yml](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml).
- Detailed usage information, refer to [Docker integration](../docker/README.md) documentation.
#### `image:name`
An [extended docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
For more information, see [Available settings for `image`](../docker/using_docker_images.md#available-settings-for-image).
#### `image:entrypoint`
An [extended docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
For more information, see [Available settings for `image`](../docker/using_docker_images.md#available-settings-for-image).
### `services`
Used to specify a [service Docker image](../docker/using_docker_images.md#what-is-a-service), linked to a base image specified in [`image`](#image).
For:
- Simple definition examples, see [Define `image` and `services` from .gitlab-ci.yml](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml).
- Detailed usage information, refer to [Docker integration](../docker/README.md) documentation.
- For example services, see [GitLab CI Services](../services/README.md).
#### `services:name`
An [extended docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
For more information, see see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services).
#### `services:alias`
An [extended docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
For more information, see see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services).
#### `services:entrypoint`
An [extended docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
For more information, see see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services).
#### `services:command`
An [extended docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
For more information, see see [Available settings for `services`](../docker/using_docker_images.md#available-settings-for-services).
### `before_script` and `after_script`
> Introduced in GitLab 8.7 and requires GitLab Runner v1.2.
`before_script` is used to define the command that should be run before all
jobs, including deploy jobs, but after the restoration of [artifacts](#artifacts).
...
...
@@ -116,7 +232,7 @@ job:
-execute this after my script
```
## `stages`
### `stages`
`stages` is used to define stages that can be used by jobs and is defined
globally.
...
...
@@ -150,7 +266,7 @@ There are also two edge cases worth mentioning:
`test` and `deploy` are allowed to be used as job's stage by default.
1. If a job doesn't specify a `stage`, the job is assigned the `test` stage.
## `stage`
### `stage`
`stage` is defined per-job and relies on [`stages`](#stages) which is defined
globally. It allows to group jobs into different stages, and jobs of the same
...
...
@@ -179,38 +295,7 @@ job 4:
script:make deploy
```
## `types`
CAUTION: **Deprecated:**
`types` is deprecated, and could be removed in one of the future releases.
Use [stages](#stages) instead.
## `script`
`script` is the only required keyword that a job needs. It's a shell script
which is executed by the Runner. For example:
```yaml
job:
script:"bundleexecrspec"
```
This parameter can also contain several commands using an array:
```yaml
job:
script:
-uname -a
-bundle exec rspec
```
Sometimes, `script` commands will need to be wrapped in single or double quotes.
For example, commands that contain a colon (`:`) need to be wrapped in quotes so
that the YAML parser knows to interpret the whole thing as a string rather than
a "key: value" pair. Be careful when using special characters:
@@ -1528,7 +1597,7 @@ Possible values for `when` are:
-`missing_dependency_failure`: Retry if a dependency was missing.
-`runner_unsupported`: Retry if the runner was unsupported.
## `parallel`
### `parallel`
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22631) in GitLab 11.5.
...
...
@@ -1548,7 +1617,49 @@ test:
parallel:5
```
## `include`
### `trigger` **[PREMIUM]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8997) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8.
`trigger` allows you to define downstream pipeline trigger. When a job created
from `trigger` definition is started by GitLab, a downstream pipeline gets
created.
Learn more about [multi-project pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipelines.html#creating-cross-project-pipelines-from-gitlab-ci-yml).
#### Simple `trigger` syntax
The most simple way to configure a downstream trigger to use `trigger` keyword
with a full path to a downstream project:
```yaml
rspec:
stage:test
script:bundle exec rspec
staging:
stage:deploy
trigger:my/deployment
```
#### Complex `trigger` syntax
It is possible to configure a branch name that GitLab will use to create
a downstream pipeline with:
```yaml
rspec:
stage:test
script:bundle exec rspec
staging:
stage:deploy
trigger:
project:my/deployment
branch:stable
```
### `include`
> - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5.
> - Available for Starter, Premium and Ultimate since 10.6.
...
...
@@ -1585,7 +1696,7 @@ of using YAML anchors, you can use the [`extends` keyword](#extends).
See [usage examples](#include-examples).
### `include:local`
#### `include:local`
`include:local` includes a file from the same repository as `.gitlab-ci.yml`.
It's referenced using full paths relative to the root directory (`/`).
...
...
@@ -1607,7 +1718,7 @@ include:
-local:'/templates/.gitlab-ci-template.yml'
```
### `include:file`
#### `include:file`
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/53903) in GitLab 11.7.
...
...
@@ -1638,11 +1749,11 @@ include:
file:'/templates/.gitlab-ci-template.yml'
```
All nested includes will be executed in the scope of the target project,
All [nested includes](#nested-includes) will be executed in the scope of the target project,
so it is possible to used local (relative to target project), project, remote
or template includes.
### `include:template`
#### `include:template`
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/53445) in GitLab 11.7.
...
...
@@ -1657,10 +1768,10 @@ include:
-template:Auto-DevOps.gitlab-ci.yml
```
All nested includes will be executed only with the permission of the user,
All [nested includes](#nested-includes) will be executed only with the permission of the user,
so it is possible to use project, remote or template includes.
### `include:remote`
#### `include:remote`
`include:remote` can be used to include a file from a different location,
using HTTP/HTTPS, referenced by using the full URL. The remote file must be
...
...
@@ -1675,7 +1786,7 @@ include:
All nested includes will be executed without context as public user, so only another remote,
or public project, or template is allowed.
### Nested includes
#### Nested includes
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/53903) in GitLab 11.7.
...
...
@@ -1683,11 +1794,11 @@ Nested includes allow you to compose a set of includes.
A total of 50 includes is allowed.
Duplicate includes are considered a configuration error.
### `include` examples
#### `include` examples
Here are a few more `include` examples.
#### Single string or array of multiple values
##### Single string or array of multiple values
You can include your extra YAML file(s) either as a single string or
an array of multiple values. The following examples are all valid.
...
...
@@ -1741,7 +1852,7 @@ include:
file:'/templates/.gitlab-ci-template.yml'
```
#### Re-using a `before_script` template
##### Re-using a `before_script` template
In the following example, the content of `.before-script-template.yml` will be
automatically fetched and evaluated along with the content of `.gitlab-ci.yml`.
...
...
@@ -1765,7 +1876,7 @@ rspec:
-bundle exec rspec
```
#### Overriding external template values
##### Overriding external template values
The following example shows specific YAML-defined variables and details of the
`production` job from an include file being customized in `.gitlab-ci.yml`.
...
...
@@ -1850,7 +1961,7 @@ In this case, if `install_dependencies` and `deploy` were not repeated in
`.gitlab-ci.yml`, they would not be part of the script for the `production`
job in the combined CI configuration.
#### Using nested includes
##### Using nested includes
The examples below show how includes can be nested from different sources
using a combination of different methods.
...
...
@@ -1895,7 +2006,7 @@ docker-test:
script:docker run my-image /run/tests.sh
```
## `extends`
### `extends`
> Introduced in GitLab 11.3.
...
...
@@ -1976,7 +2087,7 @@ spinach:
script:rake spinach
```
## Using `extends` and `include` together
### Using `extends` and `include` together
`extends` works across configuration files combined with `include`.
...
...
@@ -2001,7 +2112,7 @@ useTemplate:
This will run a job called `useTemplate` that runs `echo Hello!` as defined in
the `.template` job, and uses the `alpine` Docker image as defined in the local job.
## `pages`
### `pages`
`pages` is a special job that is used to upload static content to GitLab that
can be used to serve your website. It has a special syntax, so the two
...
...
@@ -2030,7 +2141,7 @@ pages:
Read more on [GitLab Pages user documentation](../../user/project/pages/index.md).
## `variables`
### `variables`
> Introduced in GitLab Runner v0.5.0.
...
...
@@ -2063,9 +2174,9 @@ you can set in `.gitlab-ci.yml`, there are also the so called
[Variables](../variables/README.md#variables)
which can be set in GitLab's UI.
[Learn more about variables and their priority.][variables]
Learn more about [variables and their priority][variables].
### Git strategy
#### Git strategy
> Introduced in GitLab 8.9 as an experimental feature. May change or be removed
> completely in future releases. `GIT_STRATEGY=none` requires GitLab Runner
...
...
@@ -2110,7 +2221,7 @@ NOTE: **Note:** `GIT_STRATEGY` is not supported for
but may be in the future. See the [support Git strategy with Kubernetes executor feature proposal](https://gitlab.com/gitlab-org/gitlab-runner/issues/3847)
for updates.
### Git submodule strategy
#### Git submodule strategy
> Requires GitLab Runner v1.10+.
...
...
@@ -2148,9 +2259,9 @@ Note that for this feature to work correctly, the submodules must be configured
- a relative path to another repository on the same GitLab server. See the
