Skip to content

G
gitlab-ce
Commit 5c70072b authored by Suzanne Selhorn's avatar Suzanne Selhorn
Browse files
Options

Merge branch 'docs-yaml-default-keywords' into 'master' 

Update default keyword and adjust yaml reference

See merge request gitlab-org/gitlab!73911
parents c5fbcdd5 59bb9f08
Show whitespace changes
Inline Side-by-side
Showing with 112 additions and 90 deletions
doc/ci/jobs/index.md
View file @ 5c70072b
......@@ -82,6 +82,20 @@ For example:
![Pipeline mini graph sorting](img/pipelines_mini_graph_sorting.png)
## Unavailable names for jobs
You can't use these keywords as job names:
- `image`
- `services`
- `stages`
- `types`
- `before_script`
- `after_script`
- `variables`
- `cache`
- `include`
## Group jobs in a pipeline
If you have many similar jobs, your [pipeline graph](../pipelines/index.md#visualize-pipelines) becomes long and hard
......
doc/ci/quick_start/index.md
View file @ 5c70072b
......@@ -141,7 +141,7 @@ The pipeline starts when the commit is committed.
- You can also use [CI/CD configuration visualization](../pipeline_editor/index.md#visualize-ci-configuration) to
view a graphical representation of your `.gitlab-ci.yml` file.
- Each job contains scripts and stages:
- The [`default`](../yaml/index.md#custom-default-keyword-values) keyword is for
- The [`default`](../yaml/index.md#default) keyword is for
custom defaults, for example with [`before_script`](../yaml/index.md#before_script)
and [`after_script`](../yaml/index.md#after_script).
- [`stage`](../yaml/index.md#stage) describes the sequential execution of jobs.
......
doc/ci/yaml/includes.md
View file @ 5c70072b
......@@ -69,7 +69,7 @@ You can include an array of configuration files:
## Use `default` configuration from an included configuration file
You can define a [`default`](index.md#custom-default-keyword-values) section in a
You can define a [`default`](index.md#default) section in a
configuration file. When you use a `default` section with the `include` keyword, the defaults apply to
all jobs in the pipeline.
......
doc/ci/yaml/index.md
View file @ 5c70072b
......@@ -16,66 +16,68 @@ This document lists the configuration options for your GitLab `.gitlab-ci.yml` f
When you are editing your `.gitlab-ci.yml` file, you can validate it with the
[CI Lint](../lint.md) tool.
## Job keywords
## Keywords
A GitLab CI/CD pipeline configuration includes:
- [Global keywords](#global-keywords) that configure pipeline behavior:
| Keyword | Description |
|-------------------------|:------------|
| [`default`](#default) | Custom default values for job keywords. |
| [`stages`](#stages) | The names and order of the pipeline stages. |
| [`workflow`](#workflow) | Control what types of pipeline run. |
| [`include`](#include) | Import configuration from other YAML files. |
- [Jobs](../jobs/index.md) configured with [job keywords](#job-keywords):
| Keyword | Description |
| :-------------------------------------------|:------------|
| [`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. |
| [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. |
| [`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. |
| [`coverage`](#coverage) | Code coverage settings for a given job. |
| [`dast_configuration`](#dast_configuration) | Use configuration from DAST profiles on a job level. |
| [`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. |
| [`except`](#only--except) | Control when jobs are not created. |
| [`extends`](#extends) | Configuration entries that this job inherits from. |
| [`image`](#image) | Use Docker images. |
| [`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. |
| [`needs`](#needs) | Execute jobs earlier than the stage ordering. |
| [`only`](#only--except) | Control when jobs are created. |
| [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. |
| [`parallel`](#parallel) | How many instances of a job should be run in parallel. |
| [`release`](#release) | Instructs the runner to generate a [release](../../user/project/releases/index.md) object. |
| [`resource_group`](#resource_group) | Limit job concurrency. |
| [`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. |
| [`script`](#script) | Shell script that is executed by a runner. |
| [`secrets`](#secrets) | The CI/CD secrets the job needs. |
| [`services`](#services) | Use Docker services images. |
| [`stage`](#stage) | Defines a job stage. |
| [`tags`](#tags) | List of tags that are used to select a runner. |
| [`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. |
A job is defined as a list of keywords that define the job's behavior.
The keywords available for jobs are:
| Keyword | Description |
| :-------------------------------------------|:------------|
| [`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. |
| [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. |
| [`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. |
| [`coverage`](#coverage) | Code coverage settings for a given job. |
| [`dast_configuration`](#dast_configuration) | Use configuration from DAST profiles on a job level. |
| [`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. |
| [`except`](#only--except) | Control when jobs are not created. |
| [`extends`](#extends) | Configuration entries that this job inherits from. |
| [`image`](#image) | Use Docker images. |
| [`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. |
| [`needs`](#needs) | Execute jobs earlier than the stage ordering. |
| [`only`](#only--except) | Control when jobs are created. |
| [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. |
| [`parallel`](#parallel) | How many instances of a job should be run in parallel. |
| [`release`](#release) | Instructs the runner to generate a [release](../../user/project/releases/index.md) object. |
| [`resource_group`](#resource_group) | Limit job concurrency. |
| [`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. |
| [`script`](#script) | Shell script that is executed by a runner. |
| [`secrets`](#secrets) | The CI/CD secrets the job needs. |
| [`services`](#services) | Use Docker services images. |
| [`stage`](#stage) | Defines a job stage. |
| [`tags`](#tags) | List of tags that are used to select a runner. |
| [`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
You can't use these keywords as job names:
- `image`
- `services`
- `stages`
- `types`
- `before_script`
- `after_script`
- `variables`
- `cache`
- `include`
## Global keywords
Some keywords are not defined in a job. These keywords control pipeline behavior
or import additional pipeline configuration.
### Custom default keyword values
### `default`
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.
These job keywords can be defined inside a `default:` section:
**Keyword type**: Global keyword.
**Possible inputs**: These keywords can have custom defaults:
- [`after_script`](#after_script)
- [`artifacts`](#artifacts)
......@@ -88,9 +90,7 @@ These job keywords can be defined inside a `default:` section:
- [`tags`](#tags)
- [`timeout`](#timeout)
The following example sets the `ruby:3.0` image as the default for all jobs in the pipeline.
The `rspec 2.7` job does not use the default, because it overrides the default with
a job-specific `image:` section:
**Example of `default`:**
```yaml
default:
......@@ -104,16 +104,16 @@ rspec 2.7:
script: bundle exec rspec
```
## Global keywords
In this example, `ruby:3.0` is the default `image` value for all jobs in the pipeline.
The `rspec 2.7` job does not use the default, because it overrides the default with
a job-specific `image:` section:
Some keywords are not defined in a job. These keywords control pipeline behavior
or import additional pipeline configuration:
**Additional details**:
| Keyword | Description |
|-------------------------|:------------|
| [`stages`](#stages) | The names and order of the pipeline stages. |
| [`workflow`](#workflow) | Control what types of pipeline run. |
| [`include`](#include) | Import configuration from other YAML files. |
- When the pipeline is created, each default is copied to all jobs that don't have
that keyword defined.
- If a job already has one of the keywords configured, the configuration in the job
takes precedence and is not replaced by the default.
### `stages`
......@@ -568,7 +568,7 @@ include:
- All [nested includes](includes.md#use-nested-includes) are executed only with the permission of the user,
so it's possible to use `project`, `remote`, or `template` includes.
## Keyword details
## Job keywords
The following topics explain how to use keywords to configure CI/CD pipelines.
......@@ -577,7 +577,7 @@ The following topics explain how to use keywords to configure CI/CD pipelines.
Use `image` to specify a Docker image that the job runs in.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
[`default:` section](#default).
**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats:
......@@ -612,7 +612,7 @@ a job-specific `image:` section.
The name of the Docker image that the job runs in. Similar to [`image:`](#image) used by itself.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
[`default:` section](#default).
**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats:
......@@ -640,7 +640,7 @@ The syntax is similar to the [Dockerfile `ENTRYPOINT` directive](https://docs.do
where each shell token is a separate string in the array.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
[`default:` section](#default).
**Possible inputs**: A string.
......@@ -662,7 +662,7 @@ Use `services` to specify an additional Docker image to run scripts in. The [`se
to the image specified in the [`image`](#image) keyword.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
[`default:` section](#default).
**Possible inputs**: The name of the services image, including the registry path if needed, in one of these formats:
......@@ -748,7 +748,7 @@ Use `before_script` to define an array of commands that should run before each j
`script` commands, but after [artifacts](#artifacts) are restored.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
[`default:` section](#default).
**Possible inputs**: An array including:
......@@ -786,7 +786,7 @@ in the main [`script`](#script). The combined scripts execute together in a sing
Use `after_script` to define an array of commands that run after each job, including failed jobs.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
[`default:` section](#default).
**Possible inputs**: An array including:
......@@ -1918,7 +1918,7 @@ example `ruby`, `postgres`, or `development`. To pick up and run a job, a runner
be assigned every tag listed in the job.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
[`default:` section](#default).
**Possible inputs**:
......@@ -2412,7 +2412,8 @@ Learn more about caches in [Caching in GitLab CI/CD](../caching/index.md).
Use the `cache:paths` keyword to choose which files or directories to cache.
**Keyword type**: Job-specific. You can use it only as part of a job.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
**Possible inputs**: An array of paths relative to the project directory (`$CI_PROJECT_DIR`).
You can use wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming))
......@@ -2451,7 +2452,8 @@ that use the same cache key use the same cache, including in different pipelines
If not set, the default key is `default`. All jobs with the `cache:` keyword but
no `cache:key` share the `default` cache.
**Keyword type**: Job-specific. You can use it only as part of a job.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
**Possible inputs**:
......@@ -2500,7 +2502,8 @@ Use the `cache:key:files` keyword to generate a new key when one or two specific
change. `cache:key:files` lets you reuse some caches, and rebuild them less often,
which speeds up subsequent pipeline runs.
**Keyword type**: Job-specific. You can use it only as part of a job.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
**Possible inputs**: An array of one or two file paths.
......@@ -2536,7 +2539,8 @@ fallback key is `default`.
Use `cache:key:prefix` to combine a prefix with the SHA computed for [`cache:key:files`](#cachekeyfiles).
**Keyword type**: Job-specific. You can use it only as part of a job.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
**Possible inputs**:
......@@ -2571,7 +2575,8 @@ the prefix is added to the `default` key.
Use `untracked: true` to cache all files that are untracked in your Git repository:
**Keyword type**: Job-specific. You can use it only as part of a job.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
**Possible inputs**: `true` or `false` (default).
......@@ -2604,7 +2609,8 @@ rspec:
Use `cache:when` to define when to save the cache, based on the status of the job.
**Keyword type**: Job-specific. You can use it only as part of a job.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
**Possible inputs**:
......@@ -2641,7 +2647,8 @@ Use the `pull` policy when you have many jobs executing in parallel that use the
This policy speeds up job execution and reduces load on the cache server. You can
use a job with the `push` policy to build the cache.
**Keyword type**: Job-specific. You can use it only as part of a job.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
**Possible inputs**:
......@@ -3482,7 +3489,7 @@ By default, all failure types cause the job to be retried. Use [`retry:when`](#r
to select which failures to retry on.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
[`default:` section](#default).
**Possible inputs**: `0` (default), `1`, or `2`.
......@@ -3501,7 +3508,7 @@ Use `retry:when` with `retry:max` to retry jobs for only specific failure cases.
`0`, `1`, or `2`.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
[`default:` section](#default).
**Possible inputs**: A single failure type, or an array of one or more failure types:
......@@ -3567,7 +3574,7 @@ The job-level timeout can be longer than the [project-level timeout](../pipeline
but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner).
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
[`default:` section](#default).
**Possible inputs**: A period of time written in natural language. For example, these are all equivalent:
......@@ -3765,7 +3772,8 @@ a new pipeline starts on the same branch.
You can't cancel subsequent jobs after a job with `interruptible: false` starts.
**Keyword type**: Job keyword. You can use it only as part of a job.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
**Possible inputs**: `true` or `false` (default).
......@@ -4352,7 +4360,7 @@ Defining `image`, `services`, `cache`, `before_script`, and
`after_script` globally is deprecated. Support could be removed
from a future release.
Use [`default:`](#custom-default-keyword-values) instead. For example:
Use [`default:`](#default) instead. For example:
```yaml
default:
......
doc/ci/yaml/script.md
View file @ 5c70072b
......@@ -62,7 +62,7 @@ job:
## Set a default `before_script` or `after_script` for all jobs
You can use [`before_script`](index.md#before_script) and [`after_script`](index.md#after_script)
with [`default`](index.md#custom-default-keyword-values):
with [`default`](index.md#default):
- Use `before_script` with `default` to define a default array of commands that
should run before the `script` commands in all jobs.
......
doc/development/cicd/templates.md
View file @ 5c70072b
......@@ -60,7 +60,7 @@ don't have any other `.gitlab-ci.yml` files.
When authoring pipeline templates:
- Place any [global keywords](../../ci/yaml/index.md#global-keywords) like `image`
or `before_script` in a [`default`](../../ci/yaml/index.md#custom-default-keyword-values)
or `before_script` in a [`default`](../../ci/yaml/index.md#default)
section at the top of the template.
- Note clearly in the [code comments](#explain-the-template-with-comments) if the
template is designed to be used with the `includes` keyword in an existing
......@@ -77,7 +77,7 @@ other pipeline configuration.
When authoring job templates:
- Do not use [global](../../ci/yaml/index.md#global-keywords) or [`default`](../../ci/yaml/index.md#custom-default-keyword-values)
- Do not use [global](../../ci/yaml/index.md#global-keywords) or [`default`](../../ci/yaml/index.md#default)
keywords. When a root `.gitlab-ci.yml` includes a template, global or default keywords
might be overridden and cause unexpected behavior. If a job template requires a
specific stage, explain in the code comments that users must manually add the stage
......
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