Skip to content

G
gitlab-ce
Commit 062b151a authored by Marcel Amirault's avatar Marcel Amirault Committed by Suzanne Selhorn
Browse files
Options

First phase of keyword documenation revamp 

Make the difference between job and global keywords
clearer, and fix incorrect nesting and placement
of some keywords
parent d2f77e36
Hide whitespace changes
Inline Side-by-side
Showing with 145 additions and 143 deletions
doc/ci/troubleshooting.md
View file @ 062b151a
...@@ -141,7 +141,7 @@ be checked to make sure the jobs are added to the correct pipeline type. For ...@@ -141,7 +141,7 @@ be checked to make sure the jobs are added to the correct pipeline type. For
example, if a merge request pipeline did not run, the jobs may have been added to example, if a merge request pipeline did not run, the jobs may have been added to
a branch pipeline instead. a branch pipeline instead.
It's also possible that your [`workflow: rules`](yaml/README.md#workflowrules) configuration It's also possible that your [`workflow: rules`](yaml/README.md#workflow) configuration
blocked the pipeline, or allowed the wrong pipeline type. blocked the pipeline, or allowed the wrong pipeline type.
### A job runs unexpectedly ### A job runs unexpectedly
...@@ -259,7 +259,7 @@ clause, multiple pipelines may run. Usually this occurs when you push a commit t ...@@ -259,7 +259,7 @@ clause, multiple pipelines may run. Usually this occurs when you push a commit t
a branch that has an open merge request associated with it. a branch that has an open merge request associated with it.
To [prevent duplicate pipelines](yaml/README.md#avoid-duplicate-pipelines), use To [prevent duplicate pipelines](yaml/README.md#avoid-duplicate-pipelines), use
[`workflow: rules`](yaml/README.md#workflowrules) or rewrite your rules to control [`workflow: rules`](yaml/README.md#workflow) or rewrite your rules to control
which pipelines can run. which pipelines can run.
### Console workaround if job using resource_group gets stuck ### Console workaround if job using resource_group gets stuck
......
doc/ci/yaml/README.md
View file @ 062b151a
...@@ -26,41 +26,43 @@ A job is defined as a list of keywords that define the job's behavior. ...@@ -26,41 +26,43 @@ A job is defined as a list of keywords that define the job's behavior.
The keywords available for jobs are: The keywords available for jobs are:
| Keyword | Description | | Keyword | Description |
|:---------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | :-----------------------------------|:------------|
| [`script`](#script) | Shell script that is executed by a runner. | | [`after_script`](#after_script) | Override a set of commands that are executed after job. |
| [`after_script`](#after_script) | Override a set of commands that are executed after job. | | [`allow_failure`](#allow_failure) | Allow job to fail. A failed job does not cause the pipeline to fail. |
| [`allow_failure`](#allow_failure) | Allow job to fail. A failed job does not cause the pipeline to fail. | | [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. |
| [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:exclude`, `artifacts:expose_as`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, and `artifacts:reports`. | | [`before_script`](#before_script) | Override a set of commands that are executed before job. |
| [`before_script`](#before_script) | Override a set of commands that are executed before job. | | [`cache`](#cache) | List of files that should be cached between subsequent runs. |
| [`cache`](#cache) | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, `cache:when`, and `cache:policy`. | | [`coverage`](#coverage) | Code coverage settings for a given job. |
| [`coverage`](#coverage) | Code coverage settings for a given job. | | [`dependencies`](#dependencies) | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from. |
| [`dependencies`](#dependencies) | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from. | | [`environment`](#environment) | Name of an environment to which the job deploys. |
| [`environment`](#environment) | Name of an environment to which the job deploys. Also available: `environment:name`, `environment:url`, `environment:on_stop`, `environment:auto_stop_in`, and `environment:action`. | | [`except`](#onlyexcept-basic) | Limit when jobs are not created. |
| [`except`](#onlyexcept-basic) | Limit when jobs are not created. Also available: [`except:refs`, `except:kubernetes`, `except:variables`, and `except:changes`](#onlyexcept-advanced). | | [`extends`](#extends) | Configuration entries that this job inherits from. |
| [`extends`](#extends) | Configuration entries that this job inherits from. | | [`image`](#image) | Use Docker images. |
| [`image`](#image) | Use Docker images. Also available: `image:name` and `image:entrypoint`. | | [`include`](#include) | Include external YAML files. |
| [`include`](#include) | Include external YAML files. Also available: `include:local`, `include:file`, `include:template`, and `include:remote`. | | [`inherit`](#inherit) | Select which global defaults all jobs inherit. |
| [`interruptible`](#interruptible) | Defines if a job can be canceled when made redundant by a newer run. | | [`interruptible`](#interruptible) | Defines if a job can be canceled when made redundant by a newer run. |
| [`only`](#onlyexcept-basic) | Limit when jobs are created. Also available: [`only:refs`, `only:kubernetes`, `only:variables`, and `only:changes`](#onlyexcept-advanced). | | [`needs`](#needs) | Execute jobs earlier than the stage ordering. |
| [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. | | [`only`](#onlyexcept-basic) | Limit when jobs are created. |
| [`parallel`](#parallel) | How many instances of a job should be run in parallel. | | [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. |
| [`release`](#release) | Instructs the runner to generate a [Release](../../user/project/releases/index.md) object. | | [`parallel`](#parallel) | How many instances of a job should be run in parallel. |
| [`resource_group`](#resource_group) | Limit job concurrency. | | [`release`](#release) | Instructs the runner to generate a [Release](../../user/project/releases/index.md) object. |
| [`retry`](#retry) | When and how many times a job can be auto-retried in case of a failure. | | [`resource_group`](#resource_group) | Limit job concurrency. |
| [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. | | [`retry`](#retry) | When and how many times a job can be auto-retried in case of a failure. |
| [`services`](#services) | Use Docker services images. Also available: `services:name`, `services:alias`, `services:entrypoint`, and `services:command`. | | [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. |
| [`stage`](#stage) | Defines a job stage (default: `test`). | | [`script`](#script) | Shell script that is executed by a runner. |
| [`tags`](#tags) | List of tags that are used to select a runner. | | [`secrets`](#secrets) | The CI/CD secrets the job needs. |
| [`timeout`](#timeout) | Define a custom job-level timeout that takes precedence over the project-wide setting. | | [`services`](#services) | Use Docker services images. |
| [`trigger`](#trigger) | Defines a downstream pipeline trigger. | | [`stage`](#stage) | Defines a job stage. |
| [`variables`](#variables) | Define job variables on a job level. | | [`tags`](#tags) | List of tags that are used to select a runner. |
| [`when`](#when) | When to run job. Also available: `when:manual` and `when:delayed`. | | [`timeout`](#timeout) | Define a custom job-level timeout that takes precedence over the project-wide setting. |
| [`trigger`](#trigger) | Defines a downstream pipeline trigger. |
| [`variables`](#variables) | Define job variables on a job level. |
| [`when`](#when) | When to run job. |
### Unavailable names for jobs ### Unavailable names for jobs
Each job must have a unique name, but there are a few reserved `keywords` that You can't use these keywords as job names:
can't be used as job names:
- `image` - `image`
- `services` - `services`
...@@ -72,38 +74,27 @@ can't be used as job names: ...@@ -72,38 +74,27 @@ can't be used as job names:
- `cache` - `cache`
- `include` - `include`
### Reserved keywords ### Custom default keyword values
If you get a validation error when you use specific values (for example, `true` or `false`), try to: 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.
- Quote them. The following job keywords can be defined inside a `default:` section:
- Change them to a different form. For example, `/bin/true`.
## Global keywords
Some keywords are defined at a global level and affect all jobs in the pipeline.
### Global defaults
Some keywords can be set globally as the default for all jobs with the
`default:` keyword. Default keywords can then be overridden by job-specific
configuration.
The following job keywords can be defined inside a `default:` block:
- [`image`](#image)
- [`services`](#services)
- [`before_script`](#before_script)
- [`after_script`](#after_script) - [`after_script`](#after_script)
- [`tags`](#tags)
- [`cache`](#cache)
- [`artifacts`](#artifacts) - [`artifacts`](#artifacts)
- [`before_script`](#before_script)
- [`cache`](#cache)
- [`image`](#image)
- [`interruptible`](#interruptible)
- [`retry`](#retry) - [`retry`](#retry)
- [`services`](#services)
- [`tags`](#tags)
- [`timeout`](#timeout) - [`timeout`](#timeout)
- [`interruptible`](#interruptible)
In the following example, the `ruby:2.5` image is set as the default for all This example sets the `ruby:2.5` image as the default for all jobs in the pipeline.
jobs except the `rspec 2.6` job, which uses the `ruby:2.6` image: The `rspec 2.6` job does not use the default, because it overrides the default with
a job-specific `image:` section:
```yaml ```yaml
default: default:
...@@ -117,87 +108,16 @@ rspec 2.6: ...@@ -117,87 +108,16 @@ rspec 2.6:
script: bundle exec rspec script: bundle exec rspec
``` ```
#### `inherit` ## Global keywords
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9.
You can disable inheritance of globally defined defaults
and variables with the `inherit:` keyword.
To enable or disable the inheritance of all `default:` or `variables:` keywords, use:
- `default: true` or `default: false`
- `variables: true` or `variables: false`
To inherit only a subset of `default:` keywords or `variables:`, specify what
you wish to inherit. Anything not listed is **not** inherited. Use
one of the following formats:
```yaml
inherit:
default: [keyword1, keyword2]
variables: [VARIABLE1, VARIABLE2]
```
Or:
```yaml
inherit:
default:
- keyword1
- keyword2
variables:
- VARIABLE1
- VARIABLE2
```
In the example below:
- `rubocop`:
- inherits: Nothing.
- `rspec`:
- inherits: the default `image` and the `WEBHOOK_URL` variable.
- does **not** inherit: the default `before_script` and the `DOMAIN` variable.
- `capybara`:
- inherits: the default `before_script` and `image`.
- does **not** inherit: the `DOMAIN` and `WEBHOOK_URL` variables.
- `karma`:
- inherits: the default `image` and `before_script`, and the `DOMAIN` variable.
- does **not** inherit: `WEBHOOK_URL` variable.
```yaml
default:
image: 'ruby:2.4'
before_script:
- echo Hello World
variables:
DOMAIN: example.com
WEBHOOK_URL: https://my-webhook.example.com
rubocop:
inherit:
default: false
variables: false
script: bundle exec rubocop
rspec:
inherit:
default: [image]
variables: [WEBHOOK_URL]
script: bundle exec rspec
capybara: Some keywords are not defined within a job. These keywords control pipeline behavior
inherit: or import additional pipeline configuration:
variables: false
script: bundle exec capybara
karma: | Keyword | Description |
inherit: |-------------------------|:------------|
default: true | [`stages`](#stages) | The names and order of the pipeline stages. |
variables: [DOMAIN] | [`workflow`](#workflow) | Control what types of pipeline run. |
script: karma | [`include`](#include) | Import configuration from other YAML files. |
```
### `stages` ### `stages`
...@@ -235,7 +155,7 @@ If a job does not specify a [`stage`](#stage), the job is assigned the `test` st ...@@ -235,7 +155,7 @@ If a job does not specify a [`stage`](#stage), the job is assigned the `test` st
To make a job start earlier and ignore the stage order, use To make a job start earlier and ignore the stage order, use
the [`needs`](#needs) keyword. the [`needs`](#needs) keyword.
### `workflow:rules` ### `workflow`
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5
...@@ -1183,7 +1103,7 @@ causes duplicated pipelines. ...@@ -1183,7 +1103,7 @@ causes duplicated pipelines.
There are multiple ways to avoid duplicate pipelines: There are multiple ways to avoid duplicate pipelines:
- Use [`workflow: rules`](#workflowrules) to specify which types of pipelines - Use [`workflow`](#workflow) to specify which types of pipelines
can run. can run.
- Rewrite the rules to run the job only in very specific cases, - Rewrite the rules to run the job only in very specific cases,
and avoid a final `when:` rule: and avoid a final `when:` rule:
...@@ -2347,7 +2267,7 @@ The valid values of `when` are: ...@@ -2347,7 +2267,7 @@ The valid values of `when` are:
Added in GitLab 11.14. Added in GitLab 11.14.
1. `never`: 1. `never`:
- With [`rules`](#rules), don't execute job. - With [`rules`](#rules), don't execute job.
- With [`workflow:rules`](#workflowrules), don't run pipeline. - With [`workflow`](#workflow), don't run pipeline.
For example: For example:
...@@ -4301,6 +4221,88 @@ pages: ...@@ -4301,6 +4221,88 @@ pages:
Read more on [GitLab Pages user documentation](../../user/project/pages/index.md). Read more on [GitLab Pages user documentation](../../user/project/pages/index.md).
### `inherit`
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9.
You can disable inheritance of globally defined defaults
and variables with the `inherit:` keyword.
To enable or disable the inheritance of all `default:` or `variables:` keywords, use:
- `default: true` or `default: false`
- `variables: true` or `variables: false`
To inherit only a subset of `default:` keywords or `variables:`, specify what
you wish to inherit. Anything not listed is **not** inherited. Use
one of the following formats:
```yaml
inherit:
default: [keyword1, keyword2]
variables: [VARIABLE1, VARIABLE2]
```
Or:
```yaml
inherit:
default:
- keyword1
- keyword2
variables:
- VARIABLE1
- VARIABLE2
```
In the example below:
- `rubocop`:
- inherits: Nothing.
- `rspec`:
- inherits: the default `image` and the `WEBHOOK_URL` variable.
- does **not** inherit: the default `before_script` and the `DOMAIN` variable.
- `capybara`:
- inherits: the default `before_script` and `image`.
- does **not** inherit: the `DOMAIN` and `WEBHOOK_URL` variables.
- `karma`:
- inherits: the default `image` and `before_script`, and the `DOMAIN` variable.
- does **not** inherit: `WEBHOOK_URL` variable.
```yaml
default:
image: 'ruby:2.4'
before_script:
- echo Hello World
variables:
DOMAIN: example.com
WEBHOOK_URL: https://my-webhook.example.com
rubocop:
inherit:
default: false
variables: false
script: bundle exec rubocop
rspec:
inherit:
default: [image]
variables: [WEBHOOK_URL]
script: bundle exec rspec
capybara:
inherit:
variables: false
script: bundle exec capybara
karma:
inherit:
default: true
variables: [DOMAIN]
script: karma
```
## `variables` ## `variables`
> Introduced in GitLab Runner v0.5.0. > Introduced in GitLab Runner v0.5.0.
...@@ -4720,7 +4722,7 @@ Defining `image`, `services`, `cache`, `before_script`, and ...@@ -4720,7 +4722,7 @@ Defining `image`, `services`, `cache`, `before_script`, and
`after_script` globally is deprecated. Support could be removed `after_script` globally is deprecated. Support could be removed
from a future release. from a future release.
Use [`default:`](#global-defaults) instead. For example: Use [`default:`](#custom-default-keyword-values) instead. For example:
```yaml ```yaml
default: default:
......
doc/development/pipelines.md
View file @ 062b151a
...@@ -19,7 +19,7 @@ as much as possible. ...@@ -19,7 +19,7 @@ as much as possible.
## Overview ## Overview
Pipelines for the GitLab project are created using the [`workflow:rules` keyword](../ci/yaml/README.md#workflowrules) Pipelines for the GitLab project are created using the [`workflow:rules` keyword](../ci/yaml/README.md#workflow)
feature of the GitLab CI/CD. feature of the GitLab CI/CD.
Pipelines are always created for the following scenarios: Pipelines are always created for the following scenarios:
......
doc/user/project/merge_requests/code_quality.md
View file @ 062b151a
...@@ -267,7 +267,7 @@ code_quality: ...@@ -267,7 +267,7 @@ code_quality:
- if: '$CI_COMMIT_TAG || $CI_COMMIT_BRANCH' - if: '$CI_COMMIT_TAG || $CI_COMMIT_BRANCH'
``` ```
If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/README.md#workflowrules)) If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/README.md#workflow))
might look like this example: might look like this example:
```yaml ```yaml
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7