# Configuration of your jobs 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 jobs.

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.

If you want a quick introduction to GitLab CI, follow our
[quick start guide](../quick_start/README.md).

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),
you may need to enable pipeline triggering in your project's
**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.

## Jobs

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.

```yaml
job1:
  script: "execute-script-for-job1"

job2:
  script: "execute-script-for-job2"
```

The above example is the simplest possible CI/CD 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.

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.

Each job must have a unique name, but there are a few **reserved `keywords` that
cannot be used as job names**:

- `image`
- `services`
- `stages`
- `types`
- `before_script`
- `after_script`
- `variables`
- `cache`

A job is defined by a list of parameters that define the job behavior.

| Keyword       | Required | Description |
|---------------|----------|-------------|
| script        | yes      | Defines a shell script which is executed by Runner |

| extends       | no       | Defines a configuration entry that this job is going to inherit from |

| 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 job stage (default: `test`) |
| type          | no       | Alias for `stage` |
| variables     | no       | Define job variables on a job level |
| only          | no       | Defines a list of git refs for which job is created |
| except        | no       | Defines a list of git refs for which job is not created |
| tags          | no       | Defines a list of tags which are used to select Runner |
| allow_failure | no       | Allow job to fail. Failed job doesn't contribute to commit status |
| when          | no       | Define when to run job. Can be `on_success`, `on_failure`, `always` or `manual` |
| dependencies  | no       | Define other jobs that a job depends on so that you can pass artifacts between them|
| artifacts     | no       | Define list of [job artifacts](#artifacts) |
| cache         | no       | Define list of files that should be cached between subsequent runs |
| before_script | no       | Override a set of commands that are executed before job |
| after_script  | no       | Override a set of commands that are executed after job |
| environment   | no       | Defines a name of environment to which deployment is done by this job |
| coverage      | no       | Define code coverage settings for a given job |

| retry         | no       | Define when and how many times a job can be auto-retried in case of a failure |

| parallel      | no       | Defines how many instances of a job should be run in parallel |

### `extends`

> Introduced in GitLab 11.3.

`extends` defines an entry name that a job that uses `extends` is going to

inherit from.

It is an alternative to using [YAML anchors](#anchors) and is a little
more flexible and readable:

```yaml
.tests:

  script: rake test
  stage: test

  only:
    refs:
      - branches

rspec:
  extends: .tests
  script: rake rspec
  only:
    variables:
      - $RSPEC
```

In the example above, the `rspec` job inherits from the `.tests` template job.

GitLab will perform a reverse deep merge based on the keys. GitLab will:

- Merge the `rspec` contents into `.tests` recursively.
- Not merge the values of the keys.

This results in the following `rspec` job:

```yaml
rspec:
  script: rake rspec
  stage: test
  only:
    refs:
      - branches
    variables:
      - $RSPEC
```

NOTE: **Note:**
Note that `script: rake test` has been overwritten by `script: rake rspec`.

If you do want to include the `rake test`, have a look at [before_script-and-after_script](#before_script-and-after_script).

`.tests` in this example is a [hidden key](#hidden-keys-jobs), but it's

possible to inherit from regular jobs as well.

`extends` supports multi-level inheritance, however it is not recommended to

use more than three levels. The maximum nesting level that is supported is 10.
The following example has two levels of inheritance:

```yaml
.tests:
  only:

    - pushes

.rspec:
  extends: .tests
  script: rake rspec

rspec 1:

  variables:
    RSPEC_SUITE: '1'

  extends: .rspec

rspec 2:

  variables:
    RSPEC_SUITE: '2'

  extends: .rspec

spinach:
  extends: .tests
  script: rake spinach
```

`extends` works across configuration files combined with [`include`](#include).

### `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
requirements below must be met:

1. Any static content must be placed under a `public/` directory
1. `artifacts` with a path to the `public/` directory must be defined

The example below simply moves all files from the root of the project to the
`public/` directory. The `.public` workaround is so `cp` doesn't also copy
`public/` to itself in an infinite loop:

```yaml

pages:
  stage: deploy

  script:

    - mkdir .public
    - cp -r * .public
    - mv .public public

  artifacts:
    paths:

      - public

  only:

    - master

```

Read more on [GitLab Pages user documentation](../../user/project/pages/index.md).

## `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

`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).
This can be an array or a multi-line string.

`after_script` is used to define the command that will be run after for all

jobs, including failed ones. This has to be an array or a multi-line string.

The `before_script` and the main `script` are concatenated and run in a single context/container.
The `after_script` is run separately, so depending on the executor, changes done
outside of the working tree might not be visible, e.g. software installed in the
`before_script`.

It's possible to overwrite the globally defined `before_script` and `after_script`
if you set it per-job:

```yaml
before_script:

  - global before script

job:
  before_script:

    - execute this instead of global before script

  script:

    - my command

  after_script:

    - execute this after my script

```

## `stages`

`stages` is used to define stages that can be used by jobs and is defined
globally.

The specification of `stages` allows for having flexible multi stage pipelines.

The ordering of elements in `stages` defines the ordering of jobs' execution:

1. Jobs of the same stage are run in parallel.
1. Jobs 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:

```yaml

stages:
  - build
  - test
  - deploy
```

1. First, all jobs of `build` are executed in parallel.

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 `passed`.

1. If any of the previous jobs fails, the commit is marked as `failed` and no
   jobs of further stage are executed.

There are also two edge cases worth mentioning:

1. If no `stages` are defined in `.gitlab-ci.yml`, then the `build`,
   `test` and `deploy` are allowed to be used as job's stage by default.
2. If a job doesn't specify a `stage`, the job is assigned the `test` 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
`stage` are executed in `parallel`. For example:

```yaml

stages:
  - build
  - test
  - deploy

job 1:
  stage: build
  script: make build dependencies

job 2:
  stage: build
  script: make build artifacts

job 3:

  stage: test

  script: make test

job 4:
  stage: deploy
  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: "bundle exec rspec"
```

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:
`:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.

## `only` and `except` (simplified)

`only` and `except` are two parameters that set a job policy to limit when
jobs are created:

1. `only` defines the names of branches and tags for which the job will run.

2. `except` defines the names of branches and tags for which the job will

    **not** run.

There are a few rules that apply to the usage of job 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.
* `only` and `except` allow to specify a repository path to filter jobs for
   forks.

In addition, `only` and `except` allow the use of special keywords:

| **Value** |  **Description**  |
| --------- |  ---------------- |
| `branches`  | When a branch is pushed.  |
| `tags`      | When a tag is pushed.  |
| `api`       | When pipeline has been triggered by a second pipelines API (not triggers API).  |
| `external`  | When using CI services other than GitLab. |
| `pipelines` | For multi-project triggers, created using the API with `CI_JOB_TOKEN`. |
| `pushes`    | Pipeline is triggered by a `git push` by the user. |
| `schedules` | For [scheduled pipelines][schedules]. |
| `triggers`  | For pipelines created using a trigger token. |
| `web`       | For pipelines created using **Run pipeline** button in GitLab UI (under your project's **Pipelines**). |

In the example below, `job` will run only for refs that start with `issue-`,

whereas all branches will be skipped:

```yaml
job:

  # use regexp

  only:

    - /^issue-.*$/
  # use special keyword

  except:

    - branches

```

In this example, `job` will run only for refs that are tagged, or if a build is

explicitly requested via an API trigger or a [Pipeline Schedule][schedules]:

```yaml
job:
  # use special keywords
  only:
    - tags
    - triggers

    - schedules

```

The repository path can be used to have jobs executed only for the parent
repository and not forks:

```yaml
job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce
```

The above example will run `job` for all branches on `gitlab-org/gitlab-ce`,
except master.

## `only` and `except` (complex)

> `refs` and `kubernetes` policies introduced in GitLab 10.0

>

> `variables` policy introduced in 10.7

>

> `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in 11.4

CAUTION: **Warning:**
This an _alpha_ feature, and it it subject to change at any time without
prior notice!

Since GitLab 10.0 it is possible to define a more elaborate only/except job
policy configuration.

GitLab now supports both, simple and complex strategies, so it is possible to

use an array and a hash configuration scheme.

Four keys are now available: `refs`, `kubernetes` and `variables` and `changes`.

### `refs` and `kubernetes`

Refs strategy equals to simplified only/except configuration, whereas
kubernetes strategy accepts only `active` keyword.

### `only:variables`

`variables` keyword is used to define variables expressions. In other words

you can use predefined variables / project / group or

environment-scoped variables to define an expression GitLab is going to
evaluate in order to decide whether a job should be created or not.

See the example below. Job is going to be created only when pipeline has been
scheduled or runs for a `master` branch, and only if kubernetes service is
active in the project.

```yaml
job:
  only:
    refs:
      - master
      - schedules
    kubernetes: active
```

Examples of using variables expressions:

```yaml
deploy:

  script: cap staging deploy

  only:
    refs:
      - branches
    variables:
      - $RELEASE == "staging"
      - $STAGING
```

Another use case is exluding jobs depending on a commit message _(added in 11.0)_:

```yaml
end-to-end:
  script: rake test:end-to-end
  except:
    variables:
      - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/
```

Learn more about variables expressions on [a separate page][variables-expressions].

### `only:changes`

Using `changes` keyword with `only` or `except` makes it possible to define if

a job should be created based on files modified by a git push event.

For example:

```yaml
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  only:
    changes:
      - Dockerfile
      - docker/scripts/*

      - dockerfiles/**/*

```

In the scenario above, if you are pushing multiple commits to GitLab to an
existing branch, GitLab creates and triggers `docker build` job, provided that
one of the commits contains changes to either:

- The `Dockerfile` file.
- Any of the files inside `docker/scripts/` directory.

- Any of the files and subfolders inside `dockerfiles` directory.

CAUTION: **Warning:**

There are some caveats when using this feature with new branches and tags. See
the section below.

#### Using `changes` with new branches and tags

If you are pushing a **new** branch or a **new** tag to GitLab, the policy

always evaluates to true and GitLab will create a job. This feature is not

connected with merge requests yet, and because GitLab is creating pipelines

before an user can create a merge request we don't know a target branch at

this point.

Without a target branch, it is not possible to know what the common ancestor is,
thus we always create a job in that case. This feature works best for stable
branches like `master` because in that case GitLab uses the previous commit
that is present in a branch to compare against the latest SHA that was pushed.

## `tags`

`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

example `ruby`, `postgres`, `development`.

`tags` allow you to run jobs with Runners that have the specified tags

assigned to them:

```yaml

job:
  tags:
    - ruby
    - postgres
```

The specification above, will make sure that `job` is built by a Runner that

has both `ruby` AND `postgres` tags defined.

Tags are also a great way to run different jobs on different platforms, for
example, given an OS X Runner with tag `osx` and Windows Runner with tag
`windows`, the following jobs run on respective platforms:

```yaml
windows job:
  stage:
    - build
  tags:
    - windows
  script:
    - echo Hello, %USERNAME%!

osx job:
  stage:
    - build
  tags:
    - osx
  script:
    - echo "Hello, $USER!"
```

## `allow_failure`

`allow_failure` is used when you want to allow a job to fail without impacting
the rest of the CI suite. Failed jobs don't contribute to the commit status.

The default value is `false`.

When enabled and the job fails, the pipeline will be successful/green for all

intents and purposes, but a "CI build passed with warnings" message  will be

displayed on the merge request or commit or job page. This is to be used by
jobs that are allowed to fail, but where failure indicates some other (manual)

steps should be taken elsewhere.

In the example below, `job1` and `job2` will run in parallel, but if `job1`
fails, it will not stop the next stage from running, since it's marked with
`allow_failure: true`:

```yaml
job1:
  stage: test
  script:

    - execute_script_that_will_fail

  allow_failure: true

job2:
  stage: test
  script:

    - execute_script_that_will_succeed

job3:
  stage: deploy
  script:

    - deploy_to_staging

```

## `when`

`when` is used to implement jobs that are run in case of failure or despite the
failure.

`when` can be set to one of the following values:

1. `on_success` - execute job only when all jobs from prior stages

    succeed. This is the default.

1. `on_failure` - execute job only when at least one job from prior stages

    fails.

1. `always` - execute job regardless of the status of jobs from prior stages.
1. `manual` - execute job manually (added in GitLab 8.10). Read about

    [manual actions](#when-manual) below.

For example:

```yaml

stages:

  - build
  - cleanup_build
  - test
  - deploy
  - cleanup

build_job:

  stage: build
  script:

    - make build

cleanup_build_job:

  stage: cleanup_build
  script:

    - cleanup build when failed

  when: on_failure

test_job:

  stage: test
  script:

    - make test

deploy_job:

  stage: deploy
  script:

    - make deploy

  when: manual

cleanup_job:

  stage: cleanup
  script:

    - cleanup after jobs

  when: always
```

The above script will:

1. Execute `cleanup_build_job` only when `build_job` fails.
2. Always execute `cleanup_job` as the last step in pipeline regardless of
   success or failure.
3. Allow you to manually execute `deploy_job` from GitLab's UI.

### `when:manual`

> **Notes:**

>
> - Introduced in GitLab 8.10.
> - Blocking manual actions were introduced in GitLab 9.0.
> - Protected actions were introduced in GitLab 9.2.

Manual actions are a special type of job that are not executed automatically,
they need to be explicitly started by a user. An example usage of manual actions
would be a deployment to a production environment. Manual actions can be started
from the pipeline, job, environment, and deployment views. Read more at the
[environments documentation][env-manual].

Manual actions can be either optional or blocking. Blocking manual actions will
block the execution of the pipeline at the stage this action is defined in. It's

possible to resume execution of the pipeline when someone executes a blocking

manual action by clicking a _play_ button.

When a pipeline is blocked, it will not be merged if Merge When Pipeline Succeeds

is set. Blocked pipelines also do have a special status, called _manual_.
Manual actions are non-blocking by default. If you want to make manual action
blocking, it is necessary to add `allow_failure: false` to the job's definition
in `.gitlab-ci.yml`.

Optional manual actions have `allow_failure: true` set by default and their
Statuses do not contribute to the overall pipeline status. So, if a manual
action fails, the pipeline will eventually succeed.

Manual actions are considered to be write actions, so permissions for
[protected branches](../../user/project/protected_branches.md) are used when
user wants to trigger an action. In other words, in order to trigger a manual
action assigned to a branch that the pipeline is running for, user needs to
have ability to merge to this branch.

### `when:delayed`

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21767) in GitLab 11.4.

Delayed job are for executing scripts after a certain period.
This is useful if you want to avoid jobs entering `pending` state immediately.

You can set the period with `start_in` key. The value of `start_in` key is an elapsed time in seconds, unless a unit is

provided. `start_in` key must be less than or equal to one hour. Examples of valid values include:

- `10 seconds`
- `30 minutes`
- `1 hour`

When there is a delayed job in a stage, the pipeline will not progress until the delayed job has finished.
This means this keyword can also be used for inserting delays between different stages.

The timer of a delayed job starts immediately after the previous stage has completed.
Similar to other types of jobs, a delayed job's timer will not start unless the previous stage passed.

The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage has completed:

```yaml
timed rollout 10%:
  stage: deploy
  script: echo 'Rolling out 10% ...'
  when: delayed
  start_in: 30 minutes
```

You can stop the active timer of a delayed job by clicking the **Unschedule** button.
This job will never be executed in the future unless you execute the job manually.

You can start a delayed job immediately by clicking the **Play** button.
GitLab runner will pick your job soon and start the job.