| [`retry`](#retry) | When and how many times a job can be auto-retried in case of a failure. |
| [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. |
...
...
@@ -79,7 +79,7 @@ You can't use these keywords as job names:
You can set global defaults for some keywords. Jobs that do not define one or more
of the listed keywords use the value defined in the `default:` section.
The following job keywords can be defined inside a `default:` section:
These job keywords can be defined inside a `default:` section:
-[`after_script`](#after_script)
-[`artifacts`](#artifacts)
...
...
@@ -92,7 +92,7 @@ The following job keywords can be defined inside a `default:` section:
-[`tags`](#tags)
-[`timeout`](#timeout)
This example sets the `ruby:2.5` image as the default for all jobs in the pipeline.
The following example sets the `ruby:2.5` image as the default for all jobs in the pipeline.
The `rspec 2.6` job does not use the default, because it overrides the default with
a job-specific `image:` section:
...
...
@@ -159,9 +159,9 @@ the [`needs`](#needs) keyword.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5
The top-level `workflow:` keyword determines whether or not a pipeline is created.
It accepts a single `rules:` keyword that is similar to [`rules:` defined in jobs](#rules).
Use it to define what can trigger a new pipeline.
Use `workflow:` to determine whether or not a pipeline is created.
Define this keyword at the top level, with a single `rules:` keyword that
is similar to [`rules:` defined in jobs](#rules).
You can use the [`workflow:rules` templates](#workflowrules-templates) to import
a preconfigured `workflow: rules` entry.
...
...
@@ -186,7 +186,7 @@ Some example `if` clauses for `workflow: rules`:
See the [common `if` clauses for `rules`](#common-if-clauses-for-rules) for more examples.
For example, in the following configuration, pipelines run for all `push` events (changes to
In the following example, pipelines run for all `push` events (changes to
branches and new tags). Pipelines for push events with `-draft` in the commit message
don't run, because they are set to `when: never`. Pipelines for schedules or merge requests
don't run either, because no rules evaluate to true for them:
...
...
@@ -226,7 +226,7 @@ If your rules match both branch pipelines and merge request pipelines,
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0.
We provide templates that set up `workflow: rules`
GitLab provides templates that set up `workflow: rules`
for common scenarios. These templates help prevent duplicate pipelines.
The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml)
...
...
@@ -234,12 +234,12 @@ makes your pipelines run for branches and tags.
Branch pipeline status is displayed in merge requests that use the branch
as a source. However, this pipeline type does not support any features offered by
[Merge Request Pipelines](../merge_request_pipelines/), like
[Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results)
or [Merge Trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/).
Use this template if you are intentionally avoiding those features.
[merge request pipelines](../merge_request_pipelines/), like
[pipelines for merge results](../merge_request_pipelines/#pipelines-for-merged-results)
or [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/).
This template intentionally avoids those features.
It is [included](#include) as follows:
To [include](#include) it:
```yaml
include:
...
...
@@ -249,10 +249,9 @@ include:
The [`MergeRequest-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/MergeRequest-Pipelines.gitlab-ci.yml)
makes your pipelines run for the default branch, tags, and
all types of merge request pipelines. Use this template if you use any of the
the [Pipelines for Merge Requests features](../merge_request_pipelines/), as mentioned
above.
the [pipelines for merge requests features](../merge_request_pipelines/).
It is [included](#include) as follows:
To [include](#include) it:
```yaml
include:
...
...
@@ -317,7 +316,7 @@ does not block triggered pipelines.
> - Available for Starter, Premium, and Ultimate in GitLab 10.6 and later.
> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Free in 11.4.
Use the `include` keyword to include external YAML files in your CI/CD configuration.
Use `include` to include external YAML files in your CI/CD configuration.
You can break down one long `gitlab-ci.yml` file into multiple files to increase readability,
or reduce duplication of the same configuration in multiple places.
...
...
@@ -339,11 +338,11 @@ YAML files, use [`!reference` tags](#reference-tags) or the [`extends` keyword](
| [`remote`](#includeremote) | Include a file from a remote URL. Must be publicly accessible. |
| [`template`](#includetemplate) | Include templates that are provided by GitLab. |
The `.gitlab-ci.yml` file configuration included by all methods is evaluated when the pipeline is created.
The configuration is a snapshot in time and persisted in the database. Any changes to
the referenced `.gitlab-ci.yml` file configuration is not reflected in GitLab until the next pipeline is created.
When the pipeline starts, the `.gitlab-ci.yml` file configuration included by all methods is evaluated.
The configuration is a snapshot in time and persists in the database. GitLab does not reflect any changes to
the referenced `.gitlab-ci.yml` file configuration until the next pipeline starts.
The files defined by `include` are:
The `include` files are:
- Deep merged with those in the `.gitlab-ci.yml` file.
- Always evaluated first and merged with the content of the `.gitlab-ci.yml` file,
...
...
@@ -367,13 +366,13 @@ include:
file:'.compliance-gitlab-ci.yml'
```
For an example of how you can include these predefined variables, and their impact on CI jobs,
see the following[CI/CD variable demo](https://youtu.be/4XR8gw3Pkos).
For an example of how you can include these predefined variables, and the variables' impact on CI/CD jobs,
see this[CI/CD variable demo](https://youtu.be/4XR8gw3Pkos).
#### `include:local`
`include:local` includes a file that is in the same repository as the `.gitlab-ci.yml` file.
It's referenced with full paths relative to the root directory (`/`).
Use `include:local` to include a file that is in the same repository as the `.gitlab-ci.yml` file.
Use a full path relative to the root directory (`/`).
If you use `include:local`, make sure that both the `.gitlab-ci.yml` file and the local file
are on the same branch.
...
...
@@ -390,7 +389,7 @@ include:
-local:'/templates/.gitlab-ci-template.yml'
```
This can be defined as a short local include:
You can also use shorter syntax to define the path:
```yaml
include:'.gitlab-ci-production.yml'
...
...
@@ -404,8 +403,9 @@ Use local includes instead of symbolic links.
To include files from another private project on the same GitLab instance,
use `include:file`. You can use `include:file` in combination with `include:project` only.
Use a full path, relative to the root directory (`/`).
The included file is referenced with a full path, relative to the root directory (`/`). For example:
For example:
```yaml
include:
...
...
@@ -413,7 +413,7 @@ include:
file:'/templates/.gitlab-ci-template.yml'
```
You can also specify a `ref`. If not specified, it defaults to the `HEAD` of the project:
You can also specify a `ref`. If you do not specify a value, the ref defaults to the `HEAD` of the project:
```yaml
include:
...
...
@@ -502,15 +502,15 @@ to resolve all files is 30 seconds.
#### Additional `includes` examples
There is a list of [additional `includes` examples](includes.md) available.
The following are detailed explanations for keywords used to configure CI/CD pipelines.
The following topics explain how to use keywords to configure CI/CD pipelines.
### `image`
Used to specify [a Docker image](../docker/using_docker_images.md#what-is-an-image) to use for the job.
Use`image` to specify [a Docker image](../docker/using_docker_images.md#what-is-an-image) to use for the job.
For:
...
...
@@ -531,13 +531,13 @@ For more information, see [Available settings for `image`](../docker/using_docke
#### `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).
Use`services` 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:
- Usage 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/index.md) documentation.
-For example services, see [GitLab CI/CD Services](../services/index.md).
-Example services, see [GitLab CI/CD Services](../services/index.md).
##### `services:name`
...
...
@@ -565,8 +565,11 @@ For more information, see [Available settings for `services`](../docker/using_do
### `script`
`script` is the only required keyword that a job needs. It's a shell script
that is executed by the runner. For example:
Use `script` to specify a shell script for the runner to execute.
All jobs except [trigger jobs](#trigger) require a `script` keyword.
For example:
```yaml
job:
...
...
@@ -575,7 +578,7 @@ job:
You can use [YAML anchors with `script`](#yaml-anchors-for-scripts).
This keyword can also contain several commands in an array:
The `script` keyword can also contain several commands in an array:
```yaml
job:
...
...
@@ -609,7 +612,7 @@ job:
You can verify the syntax is valid with the [CI Lint](../lint.md) tool.
Be careful when using these special characters as well:
Combining the individual examples given above for `release` results in the following
code snippets. There are two options, depending on how you generate the
If you combine the previous examples for `release`, you get two options, depending on how you generate the
tags. You can't use these options together, so choose one:
- To create a release when you push a Git tag, or when you add a Git tag
...
...
@@ -4145,7 +4137,7 @@ The entries under the `release` node are transformed into a `bash` command line
to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli).
You can also call the `release-cli` directly from a `script` entry.
For example, using the YAML described above:
For example, if you use the YAML described previously:
```shell
release-cli create --name"Release $CI_COMMIT_SHA"--description"Created using the release-cli $EXTRA_DESCRIPTION"--tag-name"v${MAJOR}.${MINOR}.${REVISION}"--ref"$CI_COMMIT_SHA"--released-at"2020-07-15T08:00:00Z"--milestone"m1"--milestone"m2"--milestone"m3"
You can use the `value` and `description` keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines)
Use the `value` and `description` keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines)
when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually):
```yaml
...
...
@@ -4379,7 +4371,7 @@ variables:
### Configure runner behavior with variables
You can use [CI/CD variables](../variables/README.md) to configure runner Git behavior:
You can use [CI/CD variables](../variables/README.md) to configure how the runner processes Git requests:
