Relationships are defined between jobs using the [`needs:` keyword](../yaml/index.md#needs).
Relationships are defined between jobs using the [`needs` keyword](../yaml/index.md#needs).
Note that `needs:` also works with the [parallel](../yaml/index.md#parallel) keyword,
Note that `needs` also works with the [parallel](../yaml/index.md#parallel) keyword,
giving you powerful options for parallelization within your pipeline.
## Limitations
...
...
@@ -87,7 +87,7 @@ are certain use cases that you may need to work around. For more information, ch
The needs visualization makes it easier to visualize the relationships between dependent jobs in a DAG. This graph displays all the jobs in a pipeline that need or are needed by other jobs. Jobs with no relationships are not displayed in this view.
To see the needs visualization, click on the **Needs** tab when viewing a pipeline that uses the `needs:` keyword.
To see the needs visualization, click on the **Needs** tab when viewing a pipeline that uses the `needs` keyword.
@@ -73,7 +73,7 @@ or import additional pipeline configuration.
### `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.
of the listed keywords use the value defined in the `default` section.
**Keyword type**: Global keyword.
...
...
@@ -106,7 +106,7 @@ rspec 2.7:
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:
a job-specific `image` section:
**Additional details**:
...
...
@@ -368,7 +368,7 @@ Use [`workflow`](workflow.md) to control pipeline behavior.
#### `workflow:rules`
The `rules` keyword in `workflow` is similar to [`rules:` defined in jobs](#rules),
The `rules` keyword in `workflow` is similar to [`rules` defined in jobs](#rules),
but controls whether or not a whole pipeline is created.
When no rules evaluate to true, the pipeline does not run.
...
...
@@ -414,7 +414,7 @@ and the pipeline is for either:
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294232) in GitLab 13.11.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/300997) in GitLab 14.1.
You can use [`variables`](#variables) in `workflow:rules:` to define variables for
You can use [`variables`](#variables) in `workflow:rules` to define variables for
specific pipeline conditions.
When the condition matches, the variable is created and can be used by all jobs
...
...
@@ -486,7 +486,7 @@ The following topics explain how to use keywords to configure CI/CD pipelines.
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](#default).
[`default` section](#default).
**Possible inputs**: An array including:
...
...
@@ -585,7 +585,7 @@ In this example, `job1` and `job2` run in parallel:
**Additional details**:
- You can use `allow_failure` as a subkey of [`rules:`](#rulesallow_failure).
- You can use `allow_failure` as a subkey of [`rules`](#rulesallow_failure).
- You can use `allow_failure: false` with a manual job to create a [blocking manual job](../jobs/job_control.md#types-of-manual-jobs).
A blocked pipeline does not run any jobs in later stages until the manual job
is started and completes successfully.
...
...
@@ -656,7 +656,7 @@ artifacts are restored after [caches](#cache).
Use `artifacts:exclude` to prevent files from being added to an artifacts archive.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**:
...
...
@@ -709,7 +709,7 @@ After their expiry, artifacts are deleted hourly by default (using a cron job),
accessible anymore.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**: The expiry time. If no unit is provided, the time is in seconds.
Valid values include:
...
...
@@ -749,7 +749,7 @@ Use the `artifacts:expose_as` keyword to
[expose job artifacts in the merge request UI](../pipelines/job_artifacts.md#expose-job-artifacts-in-the-merge-request-ui).
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**:
...
...
@@ -793,7 +793,7 @@ archive. You can specify a unique name for every archive.
If not defined, the default name is `artifacts`, which becomes `artifacts.zip` when downloaded.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**:
...
...
@@ -822,7 +822,7 @@ Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't direct
link outside it.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**:
...
...
@@ -872,7 +872,7 @@ To deny read access for anonymous and guest users to artifacts in public
pipelines, set `artifacts:public` to `false`:
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**:
...
...
@@ -892,7 +892,7 @@ Use [`artifacts:reports`](artifacts_reports.md) to collect artifacts generated b
included templates in jobs.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**: See list of available [artifacts reports types](artifacts_reports.md).
...
...
@@ -925,7 +925,7 @@ with the paths defined in `artifacts:paths`). `artifacts:untracked` ignores conf
in the repository's `.gitignore` file.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**:
...
...
@@ -951,7 +951,7 @@ Use `artifacts:when` to upload artifacts on job failure or despite the
failure.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**:
...
...
@@ -975,7 +975,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](#default).
[`default` section](#default).
**Possible inputs**: An array including:
...
...
@@ -1022,7 +1022,7 @@ 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 keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`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))
...
...
@@ -1058,11 +1058,11 @@ rspec:
Use the `cache:key` keyword to give each cache a unique identifying key. All jobs
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
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 keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**:
...
...
@@ -1112,7 +1112,7 @@ change. `cache:key:files` lets you reuse some caches, and rebuild them less ofte
which speeds up subsequent pipeline runs.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**: An array of one or two file paths.
...
...
@@ -1151,7 +1151,7 @@ that changed each listed file.
Use `cache:key:prefix` to combine a prefix with the SHA computed for [`cache:key:files`](#cachekeyfiles).
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**:
...
...
@@ -1188,7 +1188,7 @@ is not found, the prefix is added to `default`, so the key in the example would
Use `untracked: true` to cache all files that are untracked in your Git repository:
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**: `true` or `false` (default).
...
...
@@ -1222,7 +1222,7 @@ rspec:
Use `cache:when` to define when to save the cache, based on the status of the job.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**:
...
...
@@ -1260,7 +1260,7 @@ This policy speeds up job execution and reduces load on the cache server. You ca
use a job with the `push` policy to build the cache.
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**:
...
...
@@ -1359,7 +1359,7 @@ dast:
scanner_profile:"QuickPassiveTest"
```
In this example, the `dast` job extends the `dast` configuration added with the `include:` keyword
In this example, the `dast` job extends the `dast` configuration added with the `include` keyword
to select a specific site profile and scanner profile.
**Additional details**:
...
...
@@ -1746,7 +1746,7 @@ rspec:
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](#default).
[`default` section](#default).
**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats:
...
...
@@ -1770,7 +1770,7 @@ rspec 2.7:
In this example, the `ruby:3.0` image is 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.
a job-specific `image` section.
**Related topics**:
...
...
@@ -1778,10 +1778,10 @@ a job-specific `image:` section.
#### `image:name`
The name of the Docker image that the job runs in. Similar to [`image:`](#image) used by itself.
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](#default).
[`default` section](#default).
**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats:
...
...
@@ -1809,7 +1809,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](#default).
[`default` section](#default).
**Possible inputs**: A string.
...
...
@@ -1829,7 +1829,7 @@ image:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9.
Use `inherit:` to [control inheritance of globally-defined defaults and variables](../jobs/index.md#control-the-inheritance-of-default-keywords-and-global-variables).
Use `inherit` to [control inheritance of globally-defined defaults and variables](../jobs/index.md#control-the-inheritance-of-default-keywords-and-global-variables).
#### `inherit:default`
...
...
@@ -1916,7 +1916,7 @@ 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 or in the
[`default:` section](#default).
[`default` section](#default).
**Possible inputs**: `true` or `false` (default).
...
...
@@ -1965,7 +1965,7 @@ In this example, a new pipeline causes a running pipeline to be:
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30631) in GitLab 12.8, `needs: []` lets jobs start immediately.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) in GitLab 14.2, you can refer to jobs in the same stage as the job you are configuring.
Use `needs:` to execute jobs out-of-order. Relationships between jobs
Use `needs` 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).
You can ignore stage ordering and run some jobs without waiting for others to complete.
...
...
@@ -2022,11 +2022,11 @@ This example creates four paths of execution:
**Additional details**:
- The maximum number of jobs that a single job can have in the `needs:` array is limited:
- The maximum number of jobs that a single job can have in the `needs` array is limited:
- For GitLab.com, the limit is 50. For more information, see our
