Skip to content

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

Improve the usage of this in the CI ref 

Make sure to use this -> noun, or rephrase. Cleans
up other minor issues surrouding the fixed language
as well
parent bb5d25a9
Hide whitespace changes
Inline Side-by-side
Showing with 118 additions and 139 deletions
doc/ci/yaml/README.md
View file @ 0e5725c3
...@@ -233,7 +233,7 @@ There are also two edge cases worth mentioning: ...@@ -233,7 +233,7 @@ There are also two edge cases worth mentioning:
> [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
The top-level `workflow:` keyword determines whether or not a pipeline is created. 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 within jobs](#rules). 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 it to define what can trigger a new pipeline.
You can use the [`workflow:rules` templates](#workflowrules-templates) to import You can use the [`workflow:rules` templates](#workflowrules-templates) to import
...@@ -289,12 +289,11 @@ workflow: ...@@ -289,12 +289,11 @@ workflow:
``` ```
This example prevents pipelines for schedules or `push` (branches and tags) pipelines. This example prevents pipelines for schedules or `push` (branches and tags) pipelines.
The final `when: always` rule lets all other pipeline types run, **including** merge The final `when: always` rule runs all other pipeline types, **including** merge
request pipelines. request pipelines.
Be careful not to have rules that match both branch pipelines If your rules match both branch pipelines and merge request pipelines,
and merge request pipelines. Similar to `rules` defined in jobs, this can cause [duplicate pipelines](#prevent-duplicate-pipelines) can occur.
[duplicate pipelines](#prevent-duplicate-pipelines).
#### `workflow:rules` templates #### `workflow:rules` templates
...@@ -306,7 +305,7 @@ for common scenarios. These templates help prevent duplicate pipelines. ...@@ -306,7 +305,7 @@ 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) The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml)
makes your pipelines run for branches and tags. makes your pipelines run for branches and tags.
Branch pipeline status is displayed within merge requests that use the branch 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 as a source. However, this pipeline type does not support any features offered by
[Merge Request Pipelines](../merge_request_pipelines/), like [Merge Request Pipelines](../merge_request_pipelines/), like
[Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results) [Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results)
...@@ -339,10 +338,11 @@ include: ...@@ -339,10 +338,11 @@ include:
> - Available for Starter, Premium, and Ultimate in GitLab 10.6 and later. > - Available for Starter, Premium, and Ultimate in GitLab 10.6 and later.
> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Core in 11.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Core in 11.4.
Use the `include` keyword to include external YAML files in your CI/CD configuration. This Use the `include` keyword to include external YAML files in your CI/CD configuration.
breaks down the CI/CD configuration into multiple files and increases readability for long configuration files. You can break down one long `gitlab-ci.yml` into multiple files to increase readability,
It's also possible to have template files stored in a central repository and projects include their or reduce duplication of the same configuration in multiple places.
configuration files. This helps avoid duplicated configuration, for example, global default variables for all projects.
You can also store template files in a central repository and `include` them in projects.
`include` requires the external YAML file to have the extensions `.yml` or `.yaml`, `include` requires the external YAML file to have the extensions `.yml` or `.yaml`,
otherwise the external file is not included. otherwise the external file is not included.
...@@ -437,8 +437,7 @@ include: ...@@ -437,8 +437,7 @@ include:
``` ```
All [nested includes](#nested-includes) are executed in the scope of the target project. All [nested includes](#nested-includes) are executed in the scope of the target project.
This means you can use local (relative to target project), project, remote, You can use local (relative to target project), project, remote, or template includes.
or template includes.
##### Multiple files from a project ##### Multiple files from a project
...@@ -631,8 +630,8 @@ job: ...@@ -631,8 +630,8 @@ job:
#### `before_script` #### `before_script`
`before_script` is used to define commands that should run before each job, including `before_script` is used to define an array of commands that should run before each job,
deploy jobs, but after the restoration of any [artifacts](#artifacts). This must be an array. but after [artifacts](#artifacts) are restored.
Scripts specified in `before_script` are concatenated with any scripts specified Scripts specified in `before_script` are concatenated with any scripts specified
in the main [`script`](#script), and executed together in a single shell. in the main [`script`](#script), and executed together in a single shell.
...@@ -642,25 +641,25 @@ It's possible to overwrite a globally defined `before_script` if you define it i ...@@ -642,25 +641,25 @@ It's possible to overwrite a globally defined `before_script` if you define it i
```yaml ```yaml
default: default:
before_script: before_script:
- echo "Execute this in all jobs that don't already have a before_script section." - echo "Execute this script in all jobs that don't already have a before_script section."
job1: job1:
script: script:
- echo "This executes after the global before_script." - echo "This script executes after the global before_script."
job: job:
before_script: before_script:
- echo "Execute this instead of the global before_script." - echo "Execute this script instead of the global before_script."
script: script:
- echo "This executes after the job's `before_script`" - echo "This script executes after the job's `before_script`"
``` ```
You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts). You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts).
#### `after_script` #### `after_script`
`after_script` is used to define commands that run after each job, including failed `after_script` is used to define an array of commands that run after each job,
jobs. This must be an array. including failed jobs.
If a job times out or is cancelled, the `after_script` commands are not executed. If a job times out or is cancelled, the `after_script` commands are not executed.
Support for executing `after_script` commands for timed-out or cancelled jobs Support for executing `after_script` commands for timed-out or cancelled jobs
...@@ -682,17 +681,17 @@ Scripts specified in `after_script` are executed in a new shell, separate from a ...@@ -682,17 +681,17 @@ Scripts specified in `after_script` are executed in a new shell, separate from a
```yaml ```yaml
default: default:
after_script: after_script:
- echo "Execute this in all jobs that don't already have an after_script section." - echo "Execute this script in all jobs that don't already have an after_script section."
job1: job1:
script: script:
- echo "This executes first. When it completes, the global after_script executes." - echo "This script executes first. When it completes, the global after_script executes."
job: job:
script: script:
- echo "This executes first. When it completes, the job's `after_script` executes." - echo "This script executes first. When it completes, the job's `after_script` executes."
after_script: after_script:
- echo "Execute this instead of the global after_script." - echo "Execute this script instead of the global after_script."
``` ```
You can use [YAML anchors with `after_script`](#yaml-anchors-for-scripts). You can use [YAML anchors with `after_script`](#yaml-anchors-for-scripts).
...@@ -848,9 +847,8 @@ If you do want to include the `rake test`, see [`before_script`](#before_script) ...@@ -848,9 +847,8 @@ If you do want to include the `rake test`, see [`before_script`](#before_script)
`.tests` in this example is a [hidden job](#hide-jobs), but it's `.tests` in this example is a [hidden job](#hide-jobs), but it's
possible to inherit from regular jobs as well. possible to inherit from regular jobs as well.
`extends` supports multi-level inheritance. You should avoid using more than 3 levels, `extends` supports multi-level inheritance. You should avoid using more than three levels,
but you can use as many as eleven. but you can use as many as eleven. The following example has two levels of inheritance:
The following example has two levels of inheritance:
```yaml ```yaml
.tests: .tests:
...@@ -916,7 +914,7 @@ rspec: ...@@ -916,7 +914,7 @@ rspec:
- rake rspec - rake rspec
``` ```
This results in the following `rspec` job: The result is this `rspec` job:
```yaml ```yaml
rspec: rspec:
...@@ -955,7 +953,7 @@ For example, if you have a local `included.yml` file: ...@@ -955,7 +953,7 @@ For example, if you have a local `included.yml` file:
- echo Hello! - echo Hello!
``` ```
Then, in `.gitlab-ci.yml` you can use it like this: Then, in `.gitlab-ci.yml`:
```yaml ```yaml
include: included.yml include: included.yml
...@@ -1041,7 +1039,7 @@ For example, using `if` clauses to strictly limit when jobs run: ...@@ -1041,7 +1039,7 @@ For example, using `if` clauses to strictly limit when jobs run:
```yaml ```yaml
job: job:
script: "echo Hello, Rules!" script: echo "Hello, Rules!"
rules: rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
when: manual when: manual
...@@ -1070,7 +1068,7 @@ run them in all other cases: ...@@ -1070,7 +1068,7 @@ run them in all other cases:
```yaml ```yaml
job: job:
script: "echo Hello, Rules!" script: echo "Hello, Rules!"
rules: rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
when: never when: never
...@@ -1105,7 +1103,7 @@ For example: ...@@ -1105,7 +1103,7 @@ For example:
```yaml ```yaml
job: job:
script: "echo This creates double pipelines!" script: echo "This job creates double pipelines!"
rules: rules:
- if: '$CUSTOM_VARIABLE == "false"' - if: '$CUSTOM_VARIABLE == "false"'
when: never when: never
...@@ -1117,7 +1115,7 @@ other pipelines, including **both** push (branch) and merge request pipelines. W ...@@ -1117,7 +1115,7 @@ other pipelines, including **both** push (branch) and merge request pipelines. W
this configuration, every push to an open merge request's source branch this configuration, every push to an open merge request's source branch
causes duplicated pipelines. causes duplicated pipelines.
There are multiple ways to avoid this: There are multiple ways to avoid duplicate pipelines:
- Use [`workflow: rules`](#workflowrules) to specify which types of pipelines - Use [`workflow: rules`](#workflowrules) to specify which types of pipelines
can run. To eliminate duplicate pipelines, use merge request pipelines only can run. To eliminate duplicate pipelines, use merge request pipelines only
...@@ -1128,7 +1126,7 @@ There are multiple ways to avoid this: ...@@ -1128,7 +1126,7 @@ There are multiple ways to avoid this:
```yaml ```yaml
job: job:
script: "echo This does NOT create double pipelines!" script: echo "This job does NOT create double pipelines!"
rules: rules:
- if: '$CUSTOM_VARIABLE == "true" && $CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CUSTOM_VARIABLE == "true" && $CI_PIPELINE_SOURCE == "merge_request_event"'
``` ```
...@@ -1142,7 +1140,7 @@ without `workflow: rules`: ...@@ -1142,7 +1140,7 @@ without `workflow: rules`:
```yaml ```yaml
job: job:
script: "echo This does NOT create double pipelines!" script: echo "This job does NOT create double pipelines!"
rules: rules:
- if: '$CI_PIPELINE_SOURCE == "push"' - if: '$CI_PIPELINE_SOURCE == "push"'
when: never when: never
...@@ -1153,7 +1151,7 @@ Do not include both push and merge request pipelines in the same job: ...@@ -1153,7 +1151,7 @@ Do not include both push and merge request pipelines in the same job:
```yaml ```yaml
job: job:
script: "echo This creates double pipelines!" script: echo "This job creates double pipelines!"
rules: rules:
- if: '$CI_PIPELINE_SOURCE == "push"' - if: '$CI_PIPELINE_SOURCE == "push"'
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
...@@ -1165,10 +1163,10 @@ and `rules` can cause issues that are difficult to troubleshoot: ...@@ -1165,10 +1163,10 @@ and `rules` can cause issues that are difficult to troubleshoot:
```yaml ```yaml
job-with-no-rules: job-with-no-rules:
script: "echo This job runs in branch pipelines." script: echo "This job runs in branch pipelines."
job-with-rules: job-with-rules:
script: "echo This job runs in merge request pipelines." script: echo "This job runs in merge request pipelines."
rules: rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
``` ```
...@@ -1211,7 +1209,7 @@ For example: ...@@ -1211,7 +1209,7 @@ For example:
```yaml ```yaml
job: job:
script: "echo Hello, Rules!" script: echo "Hello, Rules!"
rules: rules:
- if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'
when: always when: always
...@@ -1244,7 +1242,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable: ...@@ -1244,7 +1242,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable:
| `external` | When using CI services other than GitLab. | | `external` | When using CI services other than GitLab. |
| `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). | | `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). |
| `merge_request_event` | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | | `merge_request_event` | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). |
| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`, use this in the child pipeline configuration so that it can be triggered by the parent pipeline. | | `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`. Use this pipeline source in the child pipeline configuration so that it can be triggered by the parent pipeline. |
| `pipeline` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#triggering-multi-project-pipelines-through-api), or the [`trigger`](#trigger) keyword. | | `pipeline` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#triggering-multi-project-pipelines-through-api), or the [`trigger`](#trigger) keyword. |
| `push` | For pipelines triggered by a `git push` event, including for branches and tags. | | `push` | For pipelines triggered by a `git push` event, including for branches and tags. |
| `schedule` | For [scheduled pipelines](../pipelines/schedules.md). | | `schedule` | For [scheduled pipelines](../pipelines/schedules.md). |
...@@ -1256,7 +1254,7 @@ For example: ...@@ -1256,7 +1254,7 @@ For example:
```yaml ```yaml
job: job:
script: "echo Hello, Rules!" script: echo "Hello, Rules!"
rules: rules:
- if: '$CI_PIPELINE_SOURCE == "schedule"' - if: '$CI_PIPELINE_SOURCE == "schedule"'
when: manual when: manual
...@@ -1272,7 +1270,7 @@ Another example: ...@@ -1272,7 +1270,7 @@ Another example:
```yaml ```yaml
job: job:
script: "echo Hello, Rules!" script: echo "Hello, Rules!"
rules: rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- if: '$CI_PIPELINE_SOURCE == "schedule"' - if: '$CI_PIPELINE_SOURCE == "schedule"'
...@@ -1394,9 +1392,7 @@ Feature.disable(:ci_variable_expansion_in_rules_changes) ...@@ -1394,9 +1392,7 @@ Feature.disable(:ci_variable_expansion_in_rules_changes)
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4.
`exists` accepts an array of paths and matches if any of these paths exist `exists` accepts an array of paths and matches if any of these paths exist
as files in the repository. as files in the repository:
For example:
```yaml ```yaml
job: job:
...@@ -1406,10 +1402,7 @@ job: ...@@ -1406,10 +1402,7 @@ job:
- Dockerfile - Dockerfile
``` ```
You can also use glob patterns to match multiple files in any directory within You can also use glob patterns to match multiple files in any directory in the repository:
the repository.
For example:
```yaml ```yaml
job: job:
...@@ -1426,7 +1419,7 @@ checks. After the 10,000th check, rules with patterned globs always match. ...@@ -1426,7 +1419,7 @@ checks. After the 10,000th check, rules with patterned globs always match.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8.
You can use [`allow_failure: true`](#allow_failure) within `rules:` to allow a job to fail, or a manual job to You can use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail, or a manual job to
wait for action, without stopping the pipeline itself. All jobs using `rules:` default to `allow_failure: false` wait for action, without stopping the pipeline itself. All jobs using `rules:` default to `allow_failure: false`
if `allow_failure:` is not defined. if `allow_failure:` is not defined.
...@@ -1436,7 +1429,7 @@ triggered by the particular rule. ...@@ -1436,7 +1429,7 @@ triggered by the particular rule.
```yaml ```yaml
job: job:
script: "echo Hello, Rules!" script: echo "Hello, Rules!"
rules: rules:
- if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'
when: manual when: manual
...@@ -1465,7 +1458,7 @@ docker build: ...@@ -1465,7 +1458,7 @@ docker build:
- Dockerfile - Dockerfile
- docker/scripts/* - docker/scripts/*
when: manual when: manual
# - when: never would be redundant here, this is implied any time rules are listed. # - "when: never" would be redundant here. It is implied any time rules are listed.
``` ```
Keywords such as `branches` or `refs` that are available for Keywords such as `branches` or `refs` that are available for
...@@ -1792,8 +1785,8 @@ refs only: ...@@ -1792,8 +1785,8 @@ refs only:
CAUTION: **Caution:** CAUTION: **Caution:**
In pipelines with [sources other than the three above](../variables/predefined_variables.md) In pipelines with [sources other than the three above](../variables/predefined_variables.md)
`changes` can't determine if a given file is new or old and always returns `true`. `changes` can't determine if a given file is new or old and always returns `true`.
This includes pipelines triggered by pushing new tags. Configuring jobs to use `only: changes` You can configure jobs to use `only: changes` with other `only: refs` keywords. However,
with other `only: refs` keywords is possible, but not recommended. those jobs ignore the changes and always run.
A basic example of using `only: changes`: A basic example of using `only: changes`:
...@@ -1823,7 +1816,7 @@ If you use `only:changes` with [only allow merge requests to be merged if the pi ...@@ -1823,7 +1816,7 @@ If you use `only:changes` with [only allow merge requests to be merged if the pi
you should [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected. you should [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected.
You can also use glob patterns to match multiple files in either the root directory You can also use glob patterns to match multiple files in either the root directory
of the repository, or in _any_ directory within the repository. However, they must be wrapped of the repository, or in _any_ directory in the repository. However, they must be wrapped
in double quotes or GitLab can't parse them. For example: in double quotes or GitLab can't parse them. For example:
```yaml ```yaml
...@@ -1862,10 +1855,9 @@ With [pipelines for merge requests](../merge_request_pipelines/index.md), ...@@ -1862,10 +1855,9 @@ With [pipelines for merge requests](../merge_request_pipelines/index.md),
it's possible to define a job to be created based on files modified it's possible to define a job to be created based on files modified
in a merge request. in a merge request.
To deduce the correct base SHA of the source branch, we recommend combining Use this keyword with `only: [merge_requests]` so GitLab can find the correct base
this keyword with `only: [merge_requests]`. This way, file differences are correctly SHA of the source branch. File differences are correctly calculated from any further
calculated from any further commits, thus all changes in the merge requests are properly commits, and all changes in the merge requests are properly tested in pipelines.
tested in pipelines.
For example: For example:
...@@ -1933,8 +1925,8 @@ runs. ...@@ -1933,8 +1925,8 @@ runs.
Use the `needs:` keyword to execute jobs out-of-order. Relationships between jobs Use the `needs:` keyword to execute jobs out-of-order. Relationships between jobs
that use `needs` can be visualized as a [directed acyclic graph](../directed_acyclic_graph/index.md). that use `needs` can be visualized as a [directed acyclic graph](../directed_acyclic_graph/index.md).
This lets you run some jobs without waiting for other ones, disregarding stage ordering You can ignore stage ordering and run some jobs without waiting for others to complete.
so you can have multiple stages running concurrently. Jobs in multiple stages can run concurrently.
Let's consider the following example: Let's consider the following example:
...@@ -2002,7 +1994,7 @@ This example creates four paths of execution: ...@@ -2002,7 +1994,7 @@ This example creates four paths of execution:
##### Changing the `needs:` job limit **(CORE ONLY)** ##### Changing the `needs:` job limit **(CORE ONLY)**
The maximum number of jobs that can be defined within `needs:` defaults to 50. The maximum number of jobs that can be defined in `needs:` defaults to 50.
A GitLab administrator with [access to the GitLab Rails console](../../administration/feature_flags.md) A GitLab administrator with [access to the GitLab Rails console](../../administration/feature_flags.md)
can choose a custom limit. For example, to set the limit to 100: can choose a custom limit. For example, to set the limit to 100:
...@@ -2211,16 +2203,13 @@ failure. ...@@ -2211,16 +2203,13 @@ failure.
`when` can be set to one of the following values: `when` can be set to one of the following values:
1. `on_success` - execute job only when all jobs from prior stages 1. `on_success` (default) - Execute job only when all jobs in earlier stages succeed,
succeed (or are considered succeeding because they have `allow_failure: true`). or are considered successful because they have `allow_failure: true`.
This is the default. 1. `on_failure` - Execute job only when at least one job in an earlier stage fails.
1. `on_failure` - execute job only when at least one job from prior stages 1. `always` - Execute job regardless of the status of jobs in earlier stages.
fails. 1. `manual` - Execute job [manually](#whenmanual).
1. `always` - execute job regardless of the status of jobs from prior stages. 1. `delayed` - [Delay the execution of a job](#whendelayed) for a specified duration.
1. `manual` - execute job manually. Read about Added in GitLab 11.14.
[manual jobs](#whenmanual) below.
1. `delayed` - execute job after a certain period (added in GitLab 11.14).
Read about [delayed jobs](#whendelayed) below.
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:rules`](#workflowrules), don't run pipeline.
...@@ -2318,7 +2307,7 @@ the users associated with a protected environment to trigger manual jobs, which ...@@ -2318,7 +2307,7 @@ the users associated with a protected environment to trigger manual jobs, which
- More precisely limit who can deploy to an environment. - More precisely limit who can deploy to an environment.
- Block a pipeline until an approved user "approves" it. - Block a pipeline until an approved user "approves" it.
To do this, you must: To protect a manual job:
1. Add an `environment` to the job. For example: 1. Add an `environment` to the job. For example:
...@@ -2341,10 +2330,10 @@ To do this, you must: ...@@ -2341,10 +2330,10 @@ To do this, you must:
this list can trigger this manual job, as well as GitLab administrators this list can trigger this manual job, as well as GitLab administrators
who are always able to use protected environments. who are always able to use protected environments.
Additionally, if you define a manual job as blocking by adding `allow_failure: false`, You can use protected environments with blocking manual jobs to have a list of users
the pipeline's next stages don't run until the manual job is triggered. You can use this allowed to approve later pipeline stages. Add `allow_failure: false` to the protected
to define a list of users allowed to "approve" later pipeline manual job and the pipeline's next stages only run after the manual job is triggered
stages by triggering the blocking manual job. by authorized users.
#### `when:delayed` #### `when:delayed`
...@@ -2363,7 +2352,7 @@ provided. `start_in` key must be less than or equal to one week. Examples of val ...@@ -2363,7 +2352,7 @@ provided. `start_in` key must be less than or equal to one week. Examples of val
- `1 week` - `1 week`
When there is a delayed job in a stage, the pipeline doesn't progress until the delayed job has finished. When there is a delayed job in a stage, the pipeline doesn't progress until the delayed job has finished.
This means this keyword can also be used for inserting delays between different stages. 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. 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 doesn't start unless the previous stage passed. Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passed.
...@@ -2517,8 +2506,8 @@ Also in the example, `GIT_STRATEGY` is set to `none`. If the ...@@ -2517,8 +2506,8 @@ Also in the example, `GIT_STRATEGY` is set to `none`. If the
the runner won’t try to check out the code after the branch is deleted. the runner won’t try to check out the code after the branch is deleted.
The example also overwrites global variables. If your `stop` `environment` job depends The example also overwrites global variables. If your `stop` `environment` job depends
on global variables, you can use [anchor variables](#yaml-anchors-for-variables) when you set the `GIT_STRATEGY`. on global variables, use [anchor variables](#yaml-anchors-for-variables) when you set the `GIT_STRATEGY`
This changes the job without overriding the global variables. to change the job without overriding the global variables.
The `stop_review_app` job is **required** to have the following keywords defined: The `stop_review_app` job is **required** to have the following keywords defined:
...@@ -2607,16 +2596,12 @@ deploy as review app: ...@@ -2607,16 +2596,12 @@ deploy as review app:
url: https://$CI_ENVIRONMENT_SLUG.example.com/ url: https://$CI_ENVIRONMENT_SLUG.example.com/
``` ```
The `deploy as review app` job is marked as deployment to dynamically The `deploy as review app` job is marked as a deployment to dynamically
create the `review/$CI_COMMIT_REF_NAME` environment, where `$CI_COMMIT_REF_NAME` create the `review/$CI_COMMIT_REF_NAME` environment. `$CI_COMMIT_REF_NAME`
is an [environment variable](../variables/README.md) set by the runner. The is an [environment variable](../variables/README.md) set by the runner. The
`$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable `$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable
for inclusion in URLs. In this case, if the `deploy as review app` job is run for inclusion in URLs. If the `deploy as review app` job runs in a branch named
in a branch named `pow`, this environment would be accessible with an URL like `pow`, this environment would be accessible with a URL like `https://review-pow.example.com/`.
`https://review-pow.example.com/`.
This implies that the underlying server that hosts the application
is properly configured.
The common use case is to create dynamic environments for branches and use them The common use case is to create dynamic environments for branches and use them
as Review Apps. You can see an example that uses Review Apps at as Review Apps. You can see an example that uses Review Apps at
...@@ -2625,8 +2610,7 @@ as Review Apps. You can see an example that uses Review Apps at ...@@ -2625,8 +2610,7 @@ as Review Apps. You can see an example that uses Review Apps at
### `cache` ### `cache`
`cache` is used to specify a list of files and directories that should be `cache` is used to specify a list of files and directories that should be
cached between jobs. You can only use paths that are within the local working cached between jobs. You can only use paths that are in the local working copy.
copy.
If `cache` is defined outside the scope of jobs, it means it's set If `cache` is defined outside the scope of jobs, it means it's set
globally and all jobs use that definition. globally and all jobs use that definition.
...@@ -2681,11 +2665,9 @@ Otherwise cache content can be overwritten. ...@@ -2681,11 +2665,9 @@ Otherwise cache content can be overwritten.
#### `cache:key` #### `cache:key`
> Introduced in GitLab Runner v1.0.0.
The `key` keyword defines the affinity of caching between jobs. The `key` keyword defines the affinity of caching between jobs.
You can have a single cache for all jobs, cache per-job, cache per-branch, You can have a single cache for all jobs, cache per-job, cache per-branch,
or any other way that fits your workflow. This way, you can fine tune caching, or any other way that fits your workflow. You can fine tune caching,
including caching data between different jobs or even different branches. including caching data between different jobs or even different branches.
The `cache:key` variable can use any of the The `cache:key` variable can use any of the
...@@ -2841,9 +2823,9 @@ rspec: ...@@ -2841,9 +2823,9 @@ rspec:
`cache:when` defines when to save the cache, based on the status of the job. You can `cache:when` defines when to save the cache, based on the status of the job. You can
set `cache:when` to: set `cache:when` to:
- `on_success` - save the cache only when the job succeeds. This is the default. - `on_success` (default): Save the cache only when the job succeeds.
- `on_failure` - save the cache only when the job fails. - `on_failure`: Save the cache only when the job fails.
- `always` - save the cache regardless of the job status. - `always`: Always save the cache.
For example, to store a cache whether or not the job fails or succeeds: For example, to store a cache whether or not the job fails or succeeds:
...@@ -2864,9 +2846,8 @@ job are persisted for future runs. This behavior is known as the `pull-push` cac ...@@ -2864,9 +2846,8 @@ job are persisted for future runs. This behavior is known as the `pull-push` cac
policy. policy.
If you know the job does not alter the cached files, you can skip the upload step If you know the job does not alter the cached files, you can skip the upload step
by setting `policy: pull` in the job specification. Typically, this would be by setting `policy: pull` in the job specification. You can add an ordinary cache
twinned with an ordinary cache job at an earlier stage to ensure the cache job at an earlier stage to ensure the cache is updated from time to time:
is updated from time to time:
```yaml ```yaml
stages: stages:
...@@ -2893,9 +2874,8 @@ rspec: ...@@ -2893,9 +2874,8 @@ rspec:
- bundle exec rspec ... - bundle exec rspec ...
``` ```
This helps to speed up job execution and reduce load on the cache server. The `pull` policy speeds up job execution and reduces load on the cache server. It
It is especially helpful when you have a large number of cache-using jobs executing in can be used when you have many jobs that use caches executing in parallel.
parallel.
If you have a job that unconditionally recreates the cache without If you have a job that unconditionally recreates the cache without
referring to its previous contents, you can skip the download step. referring to its previous contents, you can skip the download step.
...@@ -3163,9 +3143,9 @@ failure. ...@@ -3163,9 +3143,9 @@ failure.
`artifacts:when` can be set to one of the following values: `artifacts:when` can be set to one of the following values:
1. `on_success` - upload artifacts only when the job succeeds. This is the default. 1. `on_success` (default): Upload artifacts only when the job succeeds.
1. `on_failure` - upload artifacts only when the job fails. 1. `on_failure`: Upload artifacts only when the job fails.
1. `always` - upload artifacts regardless of the job status. 1. `always`: Always upload artifacts.
For example, to upload artifacts only when a job fails: For example, to upload artifacts only when a job fails:
...@@ -3397,7 +3377,7 @@ Possible values for `when` are: ...@@ -3397,7 +3377,7 @@ Possible values for `when` are:
The test there makes sure that all documented The test there makes sure that all documented
values are valid as a configuration option and therefore should always values are valid as a configuration option and therefore should always
stay in sync with this documentation. stay in sync with this documentation.
--> -->
- `always`: Retry on any failure (default). - `always`: Retry on any failure (default).
- `unknown_failure`: Retry when the failure reason is unknown. - `unknown_failure`: Retry when the failure reason is unknown.
...@@ -3440,16 +3420,11 @@ exceed the runner-specific timeout. ...@@ -3440,16 +3420,11 @@ exceed the runner-specific timeout.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) in GitLab 11.5. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) in GitLab 11.5.
Use `parallel` to configure how many instances of a job to run in Use `parallel` to configure how many instances of a job to run in parallel.
parallel. This value can be from 2 to 50. The value can be from 2 to 50.
This creates N instances of the same job that run in parallel. They are named
sequentially from `job_name 1/N` to `job_name N/N`.
For every job, `CI_NODE_INDEX` and `CI_NODE_TOTAL` [environment variables](../variables/README.md#predefined-environment-variables) are set.
Marking a job to be run in parallel requires adding `parallel` to your configuration The `parallel` keyword creates N instances of the same job that run in parallel.
file. For example: They are named sequentially from `job_name 1/N` to `job_name N/N`:
```yaml ```yaml
test: test:
...@@ -3457,10 +3432,12 @@ test: ...@@ -3457,10 +3432,12 @@ test:
parallel: 5 parallel: 5
``` ```
Parallelize tests suites across parallel jobs. Every parallel job has a `CI_NODE_INDEX` and `CI_NODE_TOTAL`
Different languages have different tools to facilitate this. [environment variable](../variables/README.md#predefined-environment-variables) set.
For example, using [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters) and RSpec to run some Ruby tests: Different languages and test suites have different methods to enable parallelization.
For example, use [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters)
and RSpec to run Ruby tests in parallel:
```ruby ```ruby
# Gemfile # Gemfile
...@@ -3479,7 +3456,7 @@ test: ...@@ -3479,7 +3456,7 @@ test:
``` ```
CAUTION: **Caution:** CAUTION: **Caution:**
Test Boosters reports usages statistics to the author. Test Boosters reports usage statistics to the author.
You can then navigate to the **Jobs** tab of a new pipeline build and see your RSpec You can then navigate to the **Jobs** tab of a new pipeline build and see your RSpec
job split into three separate jobs. job split into three separate jobs.
...@@ -3514,7 +3491,8 @@ deploystacks: ...@@ -3514,7 +3491,8 @@ deploystacks:
STACK: [data, processing] STACK: [data, processing]
``` ```
This generates 10 parallel `deploystacks` jobs, each with different values for `PROVIDER` and `STACK`: This example generates 10 parallel `deploystacks` jobs, each with different values
for `PROVIDER` and `STACK`:
```plaintext ```plaintext
deploystacks: [aws, monitoring] deploystacks: [aws, monitoring]
...@@ -3529,7 +3507,7 @@ deploystacks: [vultr, data] ...@@ -3529,7 +3507,7 @@ deploystacks: [vultr, data]
deploystacks: [vultr, processing] deploystacks: [vultr, processing]
``` ```
Job naming style [was improved](https://gitlab.com/gitlab-org/gitlab/-/issues/230452) in GitLab 13.4. The job naming style was [improved in GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/230452).
### `trigger` ### `trigger`
...@@ -3782,8 +3760,8 @@ deploy-to-production: ...@@ -3782,8 +3760,8 @@ deploy-to-production:
In this case, two `deploy-to-production` jobs in two separate pipelines can never run at the same time. As a result, In this case, two `deploy-to-production` jobs in two separate pipelines can never run at the same time. As a result,
you can ensure that concurrent deployments never happen to the production environment. you can ensure that concurrent deployments never happen to the production environment.
There can be multiple `resource_group`s defined per environment. A good use case for this You can define multiple resource groups per environment. For example,
is when deploying to physical devices. You may have multiple physical devices that when deploying to physical devices, you may have multiple physical devices. Each device
can be deployed to, but there can be only one deployment per device at any given time. can be deployed to, but there can be only one deployment per device at any given time.
The `resource_group` value can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces. The `resource_group` value can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces.
...@@ -3819,8 +3797,9 @@ image: registry.gitlab.com/gitlab-org/release-cli:latest ...@@ -3819,8 +3797,9 @@ image: registry.gitlab.com/gitlab-org/release-cli:latest
#### Script #### Script
All jobs require a `script` tag at a minimum. A `:release` job can use the output of a All jobs except [trigger](#trigger) jobs must have the `script` keyword. A `release`
`:script` tag, but if this is not necessary, a placeholder script can be used, for example: job can use the output from script commands, but a placeholder script can be used if
the script is not needed:
```yaml ```yaml
script: script:
...@@ -3980,15 +3959,16 @@ tags. These options cannot be used together, so choose one: ...@@ -3980,15 +3959,16 @@ tags. These options cannot be used together, so choose one:
#### Release assets as Generic packages #### Release assets as Generic packages
You can use [Generic packages](../../user/packages/generic_packages/) to host your release assets. You can use [Generic packages](../../user/packages/generic_packages/) to host your release assets.
For a complete example of how to do this, see the [example in the repository](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/). For a complete example, see the [Release assets as Generic packages](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/)
project.
#### `releaser-cli` command line #### `releaser-cli` command line
The entries under the `:release` node are transformed into a `bash` command line and sent The entries under the `release` node are transformed into a `bash` command line and sent
to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli). 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. You can also call the `release-cli` directly from a `script` entry.
The YAML described above would be translated into a CLI command like this: For example, using the YAML described above:
```shell ```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" 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"
...@@ -4112,7 +4092,7 @@ deploy_review_job: ...@@ -4112,7 +4092,7 @@ deploy_review_job:
You can use only integers and strings for the variable's name and value. You can use only integers and strings for the variable's name and value.
If you define a variable at the top level of the `gitlab-ci.yml` file, it is global, If you define a variable at the top level of the `gitlab-ci.yml` file, it is global,
meaning it applies to all jobs. If you define a variable within a job, it's available meaning it applies to all jobs. If you define a variable in a job, it's available
to that job only. to that job only.
If a variable of the same name is defined globally and for a specific job, the If a variable of the same name is defined globally and for a specific job, the
...@@ -4160,7 +4140,7 @@ to provide templates for your jobs. When there are duplicate keys, GitLab ...@@ -4160,7 +4140,7 @@ to provide templates for your jobs. When there are duplicate keys, GitLab
performs a reverse deep merge based on the keys. performs a reverse deep merge based on the keys.
You can't use YAML anchors across multiple files when leveraging the [`include`](#include) You can't use YAML anchors across multiple files when leveraging the [`include`](#include)
feature. Anchors are only valid within the file they were defined in. Instead feature. Anchors are only valid in the file they were defined in. Instead
of using YAML anchors, you can use the [`extends` keyword](#extends). of using YAML anchors, you can use the [`extends` keyword](#extends).
The following example uses anchors and map merging. It creates two jobs, The following example uses anchors and map merging. It creates two jobs,
...@@ -4187,7 +4167,7 @@ test2: ...@@ -4187,7 +4167,7 @@ test2:
`&` sets up the name of the anchor (`job_definition`), `<<` means "merge the `&` sets up the name of the anchor (`job_definition`), `<<` means "merge the
given hash into the current one", and `*` includes the named anchor given hash into the current one", and `*` includes the named anchor
(`job_definition` again). The expanded version looks like this: (`job_definition` again). The expanded version of the example above is:
```yaml ```yaml
.job_template: .job_template:
...@@ -4213,10 +4193,9 @@ test2: ...@@ -4213,10 +4193,9 @@ test2:
- test2 project - test2 project
``` ```
Let's see another example. This time we use anchors to define two sets You can use anchors to define two sets of services. For example, `test:postgres`
of services. This configuration creates two jobs, `test:postgres` and `test:mysql`, that and `test:mysql` share the `script` defined in `.job_template`, but use different
share the `script` directive defined in `.job_template`, and the `services` `services`, defined in `.postgres_services` and `.mysql_services`:
directive defined in `.postgres_services` and `.mysql_services` respectively:
```yaml ```yaml
.job_template: &job_definition .job_template: &job_definition
...@@ -4246,7 +4225,7 @@ test:mysql: ...@@ -4246,7 +4225,7 @@ test:mysql:
services: *mysql_definition services: *mysql_definition
``` ```
The expanded version looks like this: The expanded version is:
```yaml ```yaml
.job_template: .job_template:
...@@ -4296,13 +4275,13 @@ and [`after_script`](#after_script) to use predefined commands in multiple jobs: ...@@ -4296,13 +4275,13 @@ and [`after_script`](#after_script) to use predefined commands in multiple jobs:
```yaml ```yaml
.some-script: &some-script .some-script: &some-script
- echo "Execute this in `before_script` sections" - echo "Execute this script in `before_script` sections"
.some-script-before: &some-script-before .some-script-before: &some-script-before
- echo "Execute this in `script` sections" - echo "Execute this script in `script` sections"
.some-script-after: &some-script-after .some-script-after: &some-script-after
- echo "Execute this in `after_script` sections" - echo "Execute this script in `after_script` sections"
job_name: job_name:
before_script: before_script:
......
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