<commit_before># 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](#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 |
| [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 |

### `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<commit_msg>Fix typo for after_script in README.md<commit_after># 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](#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 |
| [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 |

### `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 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
{'fraction_non_alphanumeric': 0.09379403295962752, 'fraction_numerical': 0.0026955829198064083, 'mean_word_length': 2.7717190388170057, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 13, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 36, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4080684', 'n_tokens_mistral': 4711, 'n_tokens_neox': 4438, 'n_words': 2021}