Skip to content

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

Docs: fixed future tense 

Related to: https://gitlab.com/gitlab-org/gitlab/-/issues/234029
parent 966ac228
Hide whitespace changes
Inline Side-by-side
Showing with 160 additions and 160 deletions
doc/ci/yaml/README.md
View file @ 00f0dcc2
...@@ -205,16 +205,16 @@ inherit: ...@@ -205,16 +205,16 @@ inherit:
In the example below: In the example below:
- `rubocop`: - `rubocop`:
- **will** inherit: Nothing. - inherits: Nothing.
- `rspec`: - `rspec`:
- **will** inherit: the default `image` and the `WEBHOOK_URL` variable. - inherits: the default `image` and the `WEBHOOK_URL` variable.
- will **not** inherit: the default `before_script` and the `DOMAIN` variable. - does **not** inherit: the default `before_script` and the `DOMAIN` variable.
- `capybara`: - `capybara`:
- **will** inherit: the default `before_script` and `image`. - inherits: the default `before_script` and `image`.
- will **not** inherit: the `DOMAIN` and `WEBHOOK_URL` variables. - does **not** inherit: the `DOMAIN` and `WEBHOOK_URL` variables.
- `karma`: - `karma`:
- **will** inherit: the default `image` and `before_script`, and the `DOMAIN` variable. - inherits: the default `image` and `before_script`, and the `DOMAIN` variable.
- will **not** inherit: `WEBHOOK_URL` variable. - does **not** inherit: `WEBHOOK_URL` variable.
```yaml ```yaml
default: default:
...@@ -352,13 +352,13 @@ have [duplicate pipelines](#prevent-duplicate-pipelines). ...@@ -352,13 +352,13 @@ have [duplicate pipelines](#prevent-duplicate-pipelines).
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0.
We provide pre-made templates for use with your pipelines that set up `workflow: rules` We provide templates that set up `workflow: rules`
for common scenarios. Usage of these will make things easier and prevent duplicate pipelines from running. 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 will be displayed within merge requests that use that branch Branch pipeline status is displayed within merge requests that use that branch
as a source, but this pipeline type does not support any features offered by as a source, but 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)
...@@ -1605,8 +1605,8 @@ In addition, `only` and `except` allow the use of special keywords: ...@@ -1605,8 +1605,8 @@ In addition, `only` and `except` allow the use of special keywords:
| `triggers` | For pipelines created by using a [trigger token](../triggers/README.md#trigger-token). | | `triggers` | For pipelines created by using a [trigger token](../triggers/README.md#trigger-token). |
| `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | | `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. |
In the example below, `job` will run only for refs that start with `issue-`, In the example below, `job` runs only for refs that start with `issue-`,
whereas all branches will be skipped: whereas all branches are skipped:
```yaml ```yaml
job: job:
...@@ -1631,8 +1631,8 @@ job: ...@@ -1631,8 +1631,8 @@ job:
- branches - branches
``` ```
In this example, `job` will run only for refs that are tagged, or if a build is In this example, `job` runs only for refs that are tagged, or if a build is
explicitly requested via an API trigger or a [Pipeline Schedule](../pipelines/schedules.md): explicitly requested by an API trigger or a [Pipeline Schedule](../pipelines/schedules.md):
```yaml ```yaml
job: job:
...@@ -1685,11 +1685,11 @@ requires the use of the hex character code match `\x40`. ...@@ -1685,11 +1685,11 @@ requires the use of the hex character code match `\x40`.
Only the tag or branch name can be matched by a regular expression. Only the tag or branch name can be matched by a regular expression.
The repository path, if given, is always matched literally. The repository path, if given, is always matched literally.
If a regular expression shall be used to match the tag or branch name, If a regular expression is used to match the tag or branch name,
the entire ref name part of the pattern has to be a regular expression, the entire ref name part of the pattern has to be a regular expression,
and must be surrounded by `/`. and must be surrounded by `/`.
(With regular expression flags appended after the closing `/`.) (With regular expression flags appended after the closing `/`.)
So `issue-/.*/` won't work to match all tag names or branch names So `issue-/.*/` doesn't work to match all tag names or branch names
that begin with `issue-`. that begin with `issue-`.
TIP: **Tip:** TIP: **Tip:**
...@@ -1735,7 +1735,7 @@ Four keys are available: ...@@ -1735,7 +1735,7 @@ Four keys are available:
- `changes` - `changes`
- `kubernetes` - `kubernetes`
If you use multiple keys under `only` or `except`, the keys will be evaluated as a If you use multiple keys under `only` or `except`, the keys are evaluated as a
single conjoined expression. That is: single conjoined expression. That is:
- `only:` includes the job if **all** of the keys have at least one condition that matches. - `only:` includes the job if **all** of the keys have at least one condition that matches.
...@@ -1791,8 +1791,8 @@ test: ...@@ -1791,8 +1791,8 @@ test:
The `refs` strategy can take the same values as the The `refs` strategy can take the same values as the
[simplified only/except configuration](#onlyexcept-basic). [simplified only/except configuration](#onlyexcept-basic).
In the example below, the `deploy` job is going to be created only when the In the example below, the `deploy` job is created only when the
pipeline has been [scheduled](../pipelines/schedules.md) or runs for the `master` branch: pipeline is [scheduled](../pipelines/schedules.md) or runs for the `master` branch:
```yaml ```yaml
deploy: deploy:
...@@ -1808,7 +1808,7 @@ deploy: ...@@ -1808,7 +1808,7 @@ deploy:
The `kubernetes` strategy accepts only the `active` keyword. The `kubernetes` strategy accepts only the `active` keyword.
In the example below, the `deploy` job is going to be created only when the In the example below, the `deploy` job is created only when the
Kubernetes service is active in the project: Kubernetes service is active in the project:
```yaml ```yaml
...@@ -1821,10 +1821,10 @@ deploy: ...@@ -1821,10 +1821,10 @@ deploy:
> `variables` policy introduced in GitLab 10.7. > `variables` policy introduced in GitLab 10.7.
The `variables` keyword is used to define variables expressions. In other words, The `variables` keyword defines variables expressions. In other words,
you can use predefined variables / project / group or you can use predefined variables / project / group or
environment-scoped variables to define an expression GitLab is going to environment-scoped variables to define an expression that GitLab
evaluate in order to decide whether a job should be created or not. evaluates to decide whether a job should be created or not.
Examples of using variables expressions: Examples of using variables expressions:
...@@ -1911,7 +1911,7 @@ undesired behavior could result if you don't [also use `only:merge_requests`](#u ...@@ -1911,7 +1911,7 @@ undesired behavior could result if you don't [also use `only:merge_requests`](#u
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, but they must be wrapped of the repository, or in _any_ directory within the repository, but they must be wrapped
in double quotes or GitLab will fail to parse the `.gitlab-ci.yml`. For example: in double quotes or GitLab can't parse the `.gitlab-ci.yml`. For example:
```yaml ```yaml
test: test:
...@@ -1924,9 +1924,9 @@ test: ...@@ -1924,9 +1924,9 @@ test:
- "**/*.sql" - "**/*.sql"
``` ```
The following example will skip the `build` job if a change is detected in any file The following example skips the `build` job if a change is detected in any file
in the root directory of the repository with a `.md` extension. This mean that if you change multiple files, with a `.md` extension in the root directory of the repository. This means that if you change multiple files,
but only one file is a `.md` file, the `build` job will still be skipped and will but only one file is a `.md` file, the `build` job is still skipped and does
not run for the other files. not run for the other files.
```yaml ```yaml
...@@ -1951,7 +1951,7 @@ With [pipelines for merge requests](../merge_request_pipelines/index.md), ...@@ -1951,7 +1951,7 @@ 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.
In order to deduce the correct base SHA of the source branch, we recommend combining To deduce the correct base SHA of the source branch, we recommend combining
this keyword with `only: [merge_requests]`. This way, file differences are correctly this keyword with `only: [merge_requests]`. This way, file differences are correctly
calculated from any further commits, thus all changes in the merge requests are properly calculated from any further commits, thus all changes in the merge requests are properly
tested in pipelines. tested in pipelines.
...@@ -1992,7 +1992,7 @@ In the example above, a pipeline could fail due to changes to a file in `service ...@@ -1992,7 +1992,7 @@ In the example above, a pipeline could fail due to changes to a file in `service
A later commit could then be pushed that does not include any changes to this file, A later commit could then be pushed that does not include any changes to this file,
but includes changes to the `Dockerfile`, and this pipeline could pass because it's only but includes changes to the `Dockerfile`, and this pipeline could pass because it's only
testing the changes to the `Dockerfile`. GitLab checks the **most recent pipeline**, testing the changes to the `Dockerfile`. GitLab checks the **most recent pipeline**,
that **passed**, and will show the merge request as mergeable, despite the earlier that **passed**, and shows the merge request as mergeable, despite the earlier
failed pipeline caused by a change that was not yet corrected. failed pipeline caused by a change that was not yet corrected.
With this configuration, care must be taken to check that the most recent pipeline With this configuration, care must be taken to check that the most recent pipeline
...@@ -2062,15 +2062,15 @@ production: ...@@ -2062,15 +2062,15 @@ production:
This example creates four paths of execution: This example creates four paths of execution:
- Linter: the `lint` job will run immediately without waiting for the `build` stage to complete because it has no needs (`needs: []`). - Linter: the `lint` job runs immediately without waiting for the `build` stage to complete because it has no needs (`needs: []`).
- Linux path: the `linux:rspec` and `linux:rubocop` jobs will be run as soon - Linux path: the `linux:rspec` and `linux:rubocop` jobs runs as soon
as the `linux:build` job finishes without waiting for `mac:build` to finish. as the `linux:build` job finishes without waiting for `mac:build` to finish.
- macOS path: the `mac:rspec` and `mac:rubocop` jobs will be run as soon - macOS path: the `mac:rspec` and `mac:rubocop` jobs runs as soon
as the `mac:build` job finishes, without waiting for `linux:build` to finish. as the `mac:build` job finishes, without waiting for `linux:build` to finish.
- The `production` job will be executed as soon as all previous jobs - The `production` job runs as soon as all previous jobs
finish; in this case: `linux:build`, `linux:rspec`, `linux:rubocop`, finish; in this case: `linux:build`, `linux:rspec`, `linux:rubocop`,
`mac:build`, `mac:rspec`, `mac:rubocop`. `mac:build`, `mac:rspec`, `mac:rubocop`.
...@@ -2078,14 +2078,14 @@ This example creates four paths of execution: ...@@ -2078,14 +2078,14 @@ This example creates four paths of execution:
- If `needs:` is set to point to a job that is not instantiated - If `needs:` is set to point to a job that is not instantiated
because of `only/except` rules or otherwise does not exist, the because of `only/except` rules or otherwise does not exist, the
pipeline will be created with YAML error. pipeline is not created and a YAML error is shown.
- The maximum number of jobs that a single job can need in the `needs:` array is limited: - The maximum number of jobs that a single job can need in the `needs:` array is limited:
- For GitLab.com, the limit is 50. For more information, see our - For GitLab.com, the limit is 50. For more information, see our
[infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541). [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541).
- For self-managed instances, the limit is: 50. This limit [can be changed](#changing-the-needs-job-limit). - For self-managed instances, the limit is: 50. This limit [can be changed](#changing-the-needs-job-limit).
- If `needs:` refers to a job that is marked as `parallel:`. - If `needs:` refers to a job that is marked as `parallel:`.
the current job will depend on all parallel jobs created. the current job depends on all parallel jobs being created.
- `needs:` is similar to `dependencies:` in that it needs to use jobs from prior stages, - `needs:` is similar to `dependencies:` in that it must use jobs from prior stages,
meaning it's impossible to create circular dependencies. Depending on jobs in the meaning it's impossible to create circular dependencies. Depending on jobs in the
current stage is not possible either, but support [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/30632). current stage is not possible either, but support [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/30632).
- Related to the above, stages must be explicitly defined for all jobs - Related to the above, stages must be explicitly defined for all jobs
...@@ -2115,8 +2115,8 @@ Since GitLab 12.6, you can't combine the [`dependencies`](#dependencies) keyword ...@@ -2115,8 +2115,8 @@ Since GitLab 12.6, you can't combine the [`dependencies`](#dependencies) keyword
with `needs` to control artifact downloads in jobs. `dependencies` is still valid with `needs` to control artifact downloads in jobs. `dependencies` is still valid
in jobs that do not use `needs`. in jobs that do not use `needs`.
In the example below, the `rspec` job will download the `build_job` artifacts, while the In the example below, the `rspec` job downloads the `build_job` artifacts, while the
`rubocop` job won't: `rubocop` job doesn't:
```yaml ```yaml
build_job: build_job:
...@@ -2138,9 +2138,9 @@ rubocop: ...@@ -2138,9 +2138,9 @@ rubocop:
artifacts: false artifacts: false
``` ```
Additionally, in the three syntax examples below, the `rspec` job will download the artifacts Additionally, in the three syntax examples below, the `rspec` job downloads the artifacts
from all three `build_jobs`, as `artifacts` is true for `build_job_1`, and will from all three `build_jobs`, as `artifacts` is true for `build_job_1`, and
**default** to true for both `build_job_2` and `build_job_3`. **defaults** to true for both `build_job_2` and `build_job_3`.
```yaml ```yaml
rspec: rspec:
...@@ -2171,7 +2171,7 @@ build_job: ...@@ -2171,7 +2171,7 @@ build_job:
artifacts: true artifacts: true
``` ```
`build_job` will download the artifacts from the latest successful `build-1` job `build_job` downloads the artifacts from the latest successful `build-1` job
on the `master` branch in the `group/project-name` project. If the project is in the on the `master` branch in the `group/project-name` project. If the project is in the
same group or namespace, you can omit them from the `project:` key. For example, same group or namespace, you can omit them from the `project:` key. For example,
`project: group/project-name` or `project: project-name`. `project: group/project-name` or `project: project-name`.
...@@ -2182,7 +2182,7 @@ The user running the pipeline must have at least `reporter` access to the group ...@@ -2182,7 +2182,7 @@ The user running the pipeline must have at least `reporter` access to the group
`needs` can be used to download artifacts from different pipelines in the current project `needs` can be used to download artifacts from different pipelines in the current project
by setting the `project` keyword as the current project's name, and specifying a ref. by setting the `project` keyword as the current project's name, and specifying a ref.
In the example below, `build_job` will download the artifacts for the latest successful In the example below, `build_job` downloads the artifacts for the latest successful
`build-1` job with the `other-ref` ref: `build-1` job with the `other-ref` ref:
```yaml ```yaml
...@@ -2265,16 +2265,16 @@ The default value is `false`, except for [manual](#whenmanual) jobs using the ...@@ -2265,16 +2265,16 @@ The default value is `false`, except for [manual](#whenmanual) jobs using the
`when: manual` syntax, unless using [`rules:`](#rules) syntax, where all jobs `when: manual` syntax, unless using [`rules:`](#rules) syntax, where all jobs
default to false, *including* `when: manual` jobs. default to false, *including* `when: manual` jobs.
When enabled and the job fails, the job will show an orange warning in the UI. When `allow_failure` is enabled and the job fails, the job shows an orange warning in the UI.
However, the logical flow of the pipeline will consider the job a However, the logical flow of the pipeline considers the job a
success/passed, and is not blocked. success/passed, and is not blocked.
Assuming all other jobs are successful, the job's stage and its pipeline will Assuming all other jobs are successful, the job's stage and its pipeline
show the same orange warning. However, the associated commit will be marked show the same orange warning. However, the associated commit is marked as
"passed", without warnings. "passed", without warnings.
In the example below, `job1` and `job2` will run in parallel, but if `job1` In the example below, `job1` and `job2` run in parallel, but if `job1`
fails, it won't stop the next stage from running, since it's marked with fails, it doesn't stop the next stage from running, because it's marked with
`allow_failure: true`: `allow_failure: true`:
```yaml ```yaml
...@@ -2374,28 +2374,28 @@ would be a deployment to a production environment. Manual actions can be started ...@@ -2374,28 +2374,28 @@ would be a deployment to a production environment. Manual actions can be started
from the pipeline, job, environment, and deployment views. Read more at the from the pipeline, job, environment, and deployment views. Read more at the
[environments documentation](../environments/index.md#configuring-manual-deployments). [environments documentation](../environments/index.md#configuring-manual-deployments).
Manual actions can be either optional or blocking. Blocking manual actions will Manual actions can be either optional or blocking. Blocking manual actions
block the execution of the pipeline at the stage this action is defined in. It's block the execution of the pipeline at the stage this action is defined in. It's
possible to resume execution of the pipeline when someone executes a blocking possible to resume execution of the pipeline when someone executes a blocking
manual action by clicking a _play_ button. manual action by clicking a _play_ button.
When a pipeline is blocked, it won't be merged if Merge When Pipeline Succeeds When a pipeline is blocked, it isn't merged if Merge When Pipeline Succeeds
is set. Blocked pipelines also do have a special status, called _manual_. is set. Blocked pipelines also have a special status, called _manual_.
When the `when:manual` syntax is used, manual actions are non-blocking by When the `when:manual` syntax is used, manual actions are non-blocking by
default. If you want to make manual action blocking, it's necessary to add default. If you want to make a manual action blocking, add
`allow_failure: false` to the job's definition in `.gitlab-ci.yml`. `allow_failure: false` to the job's definition in `.gitlab-ci.yml`.
Optional manual actions have `allow_failure: true` set by default and their Optional manual actions have `allow_failure: true` set by default and their
Statuses don't contribute to the overall pipeline status. So, if a manual statuses don't contribute to the overall pipeline status. So, if a manual
action fails, the pipeline will eventually succeed. action fails, the pipeline eventually succeeds.
NOTE: **Note:** NOTE: **Note:**
When using [`rules:`](#rules), `allow_failure` defaults to `false`, including for manual jobs. When using [`rules:`](#rules), `allow_failure` defaults to `false`, including for manual jobs.
Manual actions are considered to be write actions, so permissions for Manual actions are considered to be write actions, so permissions for
[protected branches](../../user/project/protected_branches.md) are used when [protected branches](../../user/project/protected_branches.md) are used when
a user wants to trigger an action. In other words, in order to trigger a manual a user wants to trigger an action. In other words, to trigger a manual
action assigned to a branch that the pipeline is running for, the user needs to action assigned to a branch that the pipeline is running for, the user must
have the ability to merge to this branch. It's possible to use protected environments have the ability to merge to this branch. It's possible to use protected environments
to more strictly [protect manual deployments](#protecting-manual-jobs) from being to more strictly [protect manual deployments](#protecting-manual-jobs) from being
run by unauthorized users. run by unauthorized users.
...@@ -2435,12 +2435,12 @@ To do this, you must: ...@@ -2435,12 +2435,12 @@ To do this, you must:
1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments), 1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments),
select the environment (`production` in the example above) and add the users, roles or groups select the environment (`production` in the example above) and add the users, roles or groups
that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in
this list will be able to 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 a manual job is defined as blocking by adding `allow_failure: false`, Additionally, if a manual job is defined as blocking by adding `allow_failure: false`,
the next stages of the pipeline won't run until the manual job is triggered. This the next stages of the pipeline don't run until the manual job is triggered. This
can be used as a way to have a defined list of users allowed to "approve" later pipeline can be used to define a list of users allowed to "approve" later pipeline
stages by triggering the blocking manual job. stages by triggering the blocking manual job.
#### `when:delayed` #### `when:delayed`
...@@ -2459,11 +2459,11 @@ provided. `start_in` key must be less than or equal to one week. Examples of val ...@@ -2459,11 +2459,11 @@ provided. `start_in` key must be less than or equal to one week. Examples of val
- `1 day` - `1 day`
- `1 week` - `1 week`
When there is a delayed job in a stage, the pipeline won'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 means 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 won'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.
The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage has completed: The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage has completed:
...@@ -2476,7 +2476,7 @@ timed rollout 10%: ...@@ -2476,7 +2476,7 @@ timed rollout 10%:
``` ```
You can stop the active timer of a delayed job by clicking the **{time-out}** (**Unschedule**) button. You can stop the active timer of a delayed job by clicking the **{time-out}** (**Unschedule**) button.
This job will never be executed in the future unless you execute the job manually. This job can no longer be scheduled to run automatically. You can, however, execute the job manually.
To start a delayed job immediately, click the **Play** button. To start a delayed job immediately, click the **Play** button.
Soon GitLab Runner picks up and starts the job. Soon GitLab Runner picks up and starts the job.
...@@ -2489,7 +2489,7 @@ Soon GitLab Runner picks up and starts the job. ...@@ -2489,7 +2489,7 @@ Soon GitLab Runner picks up and starts the job.
`environment` is used to define that a job deploys to a specific environment. `environment` is used to define that a job deploys to a specific environment.
If `environment` is specified and no environment under that name exists, a new If `environment` is specified and no environment under that name exists, a new
one will be created automatically. one is created automatically.
In its simplest form, the `environment` keyword can be defined like: In its simplest form, the `environment` keyword can be defined like:
...@@ -2500,7 +2500,7 @@ deploy to production: ...@@ -2500,7 +2500,7 @@ deploy to production:
environment: production environment: production
``` ```
In the above example, the `deploy to production` job will be marked as doing a In the above example, the `deploy to production` job is marked as doing a
deployment to the `production` environment. deployment to the `production` environment.
#### `environment:name` #### `environment:name`
...@@ -2568,7 +2568,7 @@ deploy to production: ...@@ -2568,7 +2568,7 @@ deploy to production:
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22191) in GitLab 8.13. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22191) in GitLab 8.13.
> - Starting with GitLab 8.14, when you have an environment that has a stop action > - Starting with GitLab 8.14, when you have an environment that has a stop action
> defined, GitLab will automatically trigger a stop action when the associated > defined, GitLab automatically triggers a stop action when the associated
> branch is deleted. > branch is deleted.
Closing (stopping) environments can be achieved with the `on_stop` keyword defined under Closing (stopping) environments can be achieved with the `on_stop` keyword defined under
...@@ -2585,7 +2585,7 @@ The `action` keyword can be used to specify jobs that prepare, start, or stop en ...@@ -2585,7 +2585,7 @@ The `action` keyword can be used to specify jobs that prepare, start, or stop en
| **Value** | **Description** | | **Value** | **Description** |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| start | Default value. Indicates that job starts the environment. Deployment will be created after job starts. | | start | Default value. Indicates that job starts the environment. The deployment is created after the job starts. |
| prepare | Indicates that job is only preparing the environment. Does not affect deployments. [Read more about environments](../environments/index.md#prepare-an-environment) | | prepare | Indicates that job is only preparing the environment. Does not affect deployments. [Read more about environments](../environments/index.md#prepare-an-environment) |
| stop | Indicates that job stops deployment. See the example below. | | stop | Indicates that job stops deployment. See the example below. |
...@@ -2613,10 +2613,10 @@ stop_review_app: ...@@ -2613,10 +2613,10 @@ stop_review_app:
In the above example we set up the `review_app` job to deploy to the `review` In the above example we set up the `review_app` job to deploy to the `review`
environment, and we also defined a new `stop_review_app` job under `on_stop`. environment, and we also defined a new `stop_review_app` job under `on_stop`.
Once the `review_app` job is successfully finished, it will trigger the After the `review_app` job is finished, it triggers the
`stop_review_app` job based on what is defined under `when`. In this case we `stop_review_app` job based on what is defined under `when`. In this case we
set it up to `manual` so it will need a [manual action](#whenmanual) via set it up to `manual` so it needs a [manual action](#whenmanual) from
GitLab's web interface in order to run. GitLab's user interface to run.
Also in the example, `GIT_STRATEGY` is set to `none` so that GitLab Runner won’t Also in the example, `GIT_STRATEGY` is set to `none` so that GitLab Runner won’t
try to check out the code after the branch is deleted when the `stop_review_app` try to check out the code after the branch is deleted when the `stop_review_app`
...@@ -2636,7 +2636,7 @@ The `stop_review_app` job is **required** to have the following keywords defined ...@@ -2636,7 +2636,7 @@ The `stop_review_app` job is **required** to have the following keywords defined
Additionally, both jobs should have matching [`rules`](../yaml/README.md#onlyexcept-basic) Additionally, both jobs should have matching [`rules`](../yaml/README.md#onlyexcept-basic)
or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. In the example or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. In the example
above, if the configuration is not identical, the `stop_review_app` job might not be above, if the configuration is not identical, the `stop_review_app` job might not be
included in all pipelines that include the `review_app` job, and it will not be included in all pipelines that include the `review_app` job, and it is not
possible to trigger the `action: stop` to stop the environment automatically. possible to trigger the `action: stop` to stop the environment automatically.
#### `environment:auto_stop_in` #### `environment:auto_stop_in`
...@@ -2681,7 +2681,7 @@ deploy: ...@@ -2681,7 +2681,7 @@ deploy:
namespace: production namespace: production
``` ```
This will set up the `deploy` job to deploy to the `production` This configuration sets up the `deploy` job to deploy to the `production`
environment, using the `production` environment, using the `production`
[Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/). [Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).
...@@ -2713,11 +2713,11 @@ deploy as review app: ...@@ -2713,11 +2713,11 @@ deploy as review app:
url: https://$CI_ENVIRONMENT_SLUG.example.com/ url: https://$CI_ENVIRONMENT_SLUG.example.com/
``` ```
The `deploy as review app` job will be marked as deployment to dynamically The `deploy as review app` job is marked as deployment to dynamically
create the `review/$CI_COMMIT_REF_NAME` environment, where `$CI_COMMIT_REF_NAME` create the `review/$CI_COMMIT_REF_NAME` environment, where `$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 was run for inclusion in URLs. In this case, if the `deploy as review app` job is run
in a branch named `pow`, this environment would be accessible with an URL like in a branch named `pow`, this environment would be accessible with an URL like
`https://review-pow.example.com/`. `https://review-pow.example.com/`.
...@@ -2745,7 +2745,7 @@ cached between jobs. You can only use paths that are within the local working ...@@ -2745,7 +2745,7 @@ cached between jobs. You can only use paths that are within 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 will use that definition. globally and all jobs use that definition.
#### `cache:paths` #### `cache:paths`
...@@ -2771,7 +2771,7 @@ rspec: ...@@ -2771,7 +2771,7 @@ rspec:
``` ```
Locally defined cache overrides globally defined options. The following `rspec` Locally defined cache overrides globally defined options. The following `rspec`
job will cache only `binaries/`: job caches only `binaries/`:
```yaml ```yaml
cache: cache:
...@@ -2836,13 +2836,13 @@ cache: ...@@ -2836,13 +2836,13 @@ cache:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5.
The `cache:key:files` keyword extends the `cache:key` functionality by making it easier The `cache:key:files` keyword extends the `cache:key` functionality by making it easier
to reuse some caches, and rebuild them less often, which will speed up subsequent pipeline to reuse some caches, and rebuild them less often, which speeds up subsequent pipeline
runs. runs.
When you include `cache:key:files`, you must also list the project files that will be used to generate the key, up to a maximum of two files. When you include `cache:key:files`, you must also list the project files that are used to generate the key, up to a maximum of two files.
The cache `key` will be a SHA checksum computed from the most recent commits (up to two, if two files are listed) The cache `key` is a SHA checksum computed from the most recent commits (up to two, if two files are listed)
that changed the given files. If neither file was changed in any commits, that changed the given files. If neither file was changed in any commits,
the fallback key will be `default`. the fallback key is `default`.
```yaml ```yaml
cache: cache:
...@@ -2858,7 +2858,7 @@ cache: ...@@ -2858,7 +2858,7 @@ cache:
In this example we're creating a cache for Ruby and Node.js dependencies that In this example we're creating a cache for Ruby and Node.js dependencies that
is tied to current versions of the `Gemfile.lock` and `package.json` files. Whenever one of is tied to current versions of the `Gemfile.lock` and `package.json` files. Whenever one of
these files changes, a new cache key is computed and a new cache is created. Any future these files changes, a new cache key is computed and a new cache is created. Any future
job runs using the same `Gemfile.lock` and `package.json` with `cache:key:files` will job runs that use the same `Gemfile.lock` and `package.json` with `cache:key:files`
use the new cache, instead of rebuilding the dependencies. use the new cache, instead of rebuilding the dependencies.
##### `cache:key:prefix` ##### `cache:key:prefix`
...@@ -2891,11 +2891,11 @@ rspec: ...@@ -2891,11 +2891,11 @@ rspec:
- bundle exec rspec - bundle exec rspec
``` ```
For example, adding a `prefix` of `$CI_JOB_NAME` will For example, adding a `prefix` of `$CI_JOB_NAME`
cause the key to look like: `rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5` and causes the key to look like: `rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5` and
the job cache is shared across different branches. If a branch changes the job cache is shared across different branches. If a branch changes
`Gemfile.lock`, that branch will have a new SHA checksum for `cache:key:files`. A new cache key `Gemfile.lock`, that branch has a new SHA checksum for `cache:key:files`. A new cache key
will be generated, and a new cache will be created for that key. is generated, and a new cache is created for that key.
If `Gemfile.lock` is not found, the prefix is added to If `Gemfile.lock` is not found, the prefix is added to
`default`, so the key in the example would be `rspec-default`. `default`, so the key in the example would be `rspec-default`.
...@@ -2980,8 +2980,8 @@ skip the download step. ...@@ -2980,8 +2980,8 @@ skip the download step.
`artifacts` is used to specify a list of files and directories that are `artifacts` is used to specify a list of files and directories that are
attached to the job when it [succeeds, fails, or always](#artifactswhen). attached to the job when it [succeeds, fails, or always](#artifactswhen).
The artifacts will be sent to GitLab after the job finishes and will The artifacts are sent to GitLab after the job finishes and are
be available for download in the GitLab UI provided that the size is not available for download in the GitLab UI if the size is not
larger than the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd). larger than the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd).
[Read more about artifacts](../pipelines/job_artifacts.md). [Read more about artifacts](../pipelines/job_artifacts.md).
...@@ -2997,7 +2997,7 @@ patterns and: ...@@ -2997,7 +2997,7 @@ patterns and:
- In GitLab Runner 12.10 and earlier, - In GitLab Runner 12.10 and earlier,
[`filepath.Match`](https://pkg.go.dev/path/filepath/#Match). [`filepath.Match`](https://pkg.go.dev/path/filepath/#Match).
To restrict which jobs a specific job will fetch artifacts from, see [dependencies](#dependencies). To restrict which jobs a specific job fetches artifacts from, see [dependencies](#dependencies).
Send all files in `binaries` and `.config`: Send all files in `binaries` and `.config`:
...@@ -3020,7 +3020,7 @@ job: ...@@ -3020,7 +3020,7 @@ job:
You may want to create artifacts only for tagged releases to avoid filling the You may want to create artifacts only for tagged releases to avoid filling the
build server storage with temporary build artifacts. build server storage with temporary build artifacts.
Create artifacts only for tags (`default-job` won't create artifacts): Create artifacts only for tags (`default-job` doesn't create artifacts):
```yaml ```yaml
default-job: default-job:
...@@ -3092,10 +3092,10 @@ test: ...@@ -3092,10 +3092,10 @@ test:
paths: ['file.txt'] paths: ['file.txt']
``` ```
With this configuration, GitLab will add a link **artifact 1** to the relevant merge request With this configuration, GitLab adds a link **artifact 1** to the relevant merge request
that points to `file1.txt`. that points to `file1.txt`.
An example that will match an entire directory: An example that matches an entire directory:
```yaml ```yaml
test: test:
...@@ -3110,12 +3110,12 @@ Note the following: ...@@ -3110,12 +3110,12 @@ Note the following:
- Artifacts do not display in the merge request UI when using variables to define the `artifacts:paths`. - Artifacts do not display in the merge request UI when using variables to define the `artifacts:paths`.
- A maximum of 10 job artifacts per merge request can be exposed. - A maximum of 10 job artifacts per merge request can be exposed.
- Glob patterns are unsupported. - Glob patterns are unsupported.
- If a directory is specified, the link will be to the job [artifacts browser](../pipelines/job_artifacts.md#browsing-artifacts) if there is more than - If a directory is specified, the link is to the job [artifacts browser](../pipelines/job_artifacts.md#browsing-artifacts) if there is more than
one file in the directory. one file in the directory.
- For exposed single file artifacts with `.html`, `.htm`, `.txt`, `.json`, `.xml`, - For exposed single file artifacts with `.html`, `.htm`, `.txt`, `.json`, `.xml`,
and `.log` extensions, if [GitLab Pages](../../administration/pages/index.md) is: and `.log` extensions, if [GitLab Pages](../../administration/pages/index.md) is:
- Enabled, GitLab will automatically render the artifact. - Enabled, GitLab automatically renders the artifact.
- Not enabled, you will see the file in the artifacts browser. - Not enabled, the file is displayed in the artifacts browser.
#### `artifacts:name` #### `artifacts:name`
...@@ -3336,17 +3336,17 @@ list of jobs (or no jobs) to fetch artifacts from. ...@@ -3336,17 +3336,17 @@ list of jobs (or no jobs) to fetch artifacts from.
To use this feature, define `dependencies` in context of the job and pass To use this feature, define `dependencies` in context of the job and pass
a list of all previous jobs the artifacts should be downloaded from. a list of all previous jobs the artifacts should be downloaded from.
You can only define jobs from stages that are executed before the current one. You can only define jobs from stages that are executed before the current one.
An error will be shown if you define jobs from the current stage or next ones. An error is shown if you define jobs from the current stage or next ones.
Defining an empty array will skip downloading any artifacts for that job. Defining an empty array skips downloading any artifacts for that job.
The status of the previous job is not considered when using `dependencies`, so The status of the previous job is not considered when using `dependencies`, so
if it failed or it's a manual job that was not run, no error occurs. if it failed or it's a manual job that was not run, no error occurs.
In the following example, we define two jobs with artifacts, `build:osx` and In the following example, we define two jobs with artifacts, `build:osx` and
`build:linux`. When the `test:osx` is executed, the artifacts from `build:osx` `build:linux`. When the `test:osx` is executed, the artifacts from `build:osx`
will be downloaded and extracted in the context of the build. The same happens are downloaded and extracted in the context of the build. The same happens
for `test:linux` and artifacts from `build:linux`. for `test:linux` and artifacts from `build:linux`.
The job `deploy` will download artifacts from all previous jobs because of The job `deploy` downloads artifacts from all previous jobs because of
the [stage](#stages) precedence: the [stage](#stages) precedence:
```yaml ```yaml
...@@ -3388,7 +3388,7 @@ deploy: ...@@ -3388,7 +3388,7 @@ deploy:
If the artifacts of the job that is set as a dependency have been If the artifacts of the job that is set as a dependency have been
[expired](#artifactsexpire_in) or [expired](#artifactsexpire_in) or
[erased](../pipelines/job_artifacts.md#erasing-artifacts), then [erased](../pipelines/job_artifacts.md#erasing-artifacts), then
the dependent job will fail. the dependent job fails.
NOTE: **Note:** NOTE: **Note:**
You can ask your administrator to You can ask your administrator to
...@@ -3403,7 +3403,7 @@ Use `coverage` to configure how code coverage is extracted from the ...@@ -3403,7 +3403,7 @@ Use `coverage` to configure how code coverage is extracted from the
job output. job output.
Regular expressions are the only valid kind of value expected here. So, using Regular expressions are the only valid kind of value expected here. So, using
surrounding `/` is mandatory in order to consistently and explicitly represent surrounding `/` is mandatory to consistently and explicitly represent
a regular expression string. You must escape special characters if you want to a regular expression string. You must escape special characters if you want to
match them literally. match them literally.
...@@ -3420,15 +3420,15 @@ job1: ...@@ -3420,15 +3420,15 @@ job1:
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3442) in GitLab 9.5. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3442) in GitLab 9.5.
> - [Behavior expanded](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3515) in GitLab 11.5 to control which failures to retry on. > - [Behavior expanded](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3515) in GitLab 11.5 to control which failures to retry on.
Use `retry` to configure how many times a job is going to be retried in Use `retry` to configure how many times a job is retried in
case of a failure. case of a failure.
When a job fails and has `retry` configured, it's going to be processed again When a job fails and has `retry` configured, the job is processed again,
up to the amount of times specified by the `retry` keyword. up to the amount of times specified by the `retry` keyword.
If `retry` is set to 2, and a job succeeds in a second run (first retry), it won't be retried If `retry` is set to 2, and a job succeeds in a second run (first retry), it is not tried
again. `retry` value has to be a positive integer, equal or larger than 0, but again. `retry` value has to be a positive integer, equal to or larger than 0, but
lower or equal to 2 (two retries maximum, three runs in total). less than or equal to 2 (two retries maximum, three runs in total).
A simple example to retry in all failure cases: A simple example to retry in all failure cases:
...@@ -3438,7 +3438,7 @@ test: ...@@ -3438,7 +3438,7 @@ test:
retry: 2 retry: 2
``` ```
By default, a job will be retried on all failure cases. To have a better control By default, a job is retried on all failure cases. To have better control
over which failures to retry, `retry` can be a hash with the following keys: over which failures to retry, `retry` can be a hash with the following keys:
- `max`: The maximum number of retries. - `max`: The maximum number of retries.
...@@ -3454,8 +3454,8 @@ test: ...@@ -3454,8 +3454,8 @@ test:
when: runner_system_failure when: runner_system_failure
``` ```
If there is another failure, other than a runner system failure, the job will If there is another failure, other than a runner system failure, the job
not be retried. is not retried.
To retry on multiple failure cases, `when` can also be an array of failures: To retry on multiple failure cases, `when` can also be an array of failures:
...@@ -3472,10 +3472,10 @@ test: ...@@ -3472,10 +3472,10 @@ test:
Possible values for `when` are: Possible values for `when` are:
<!-- <!--
Please make sure to update `RETRY_WHEN_IN_DOCUMENTATION` array in If you change any of the values below, make sure to update the `RETRY_WHEN_IN_DOCUMENTATION`
`spec/lib/gitlab/ci/config/entry/retry_spec.rb` if you change any of array in `spec/lib/gitlab/ci/config/entry/retry_spec.rb`.
the documented values below. The test there makes sure that all documented The test there makes sure that all documented
values are really 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.
--> -->
...@@ -3653,7 +3653,7 @@ staging: ...@@ -3653,7 +3653,7 @@ staging:
#### Complex `trigger` syntax for multi-project pipelines #### Complex `trigger` syntax for multi-project pipelines
It's possible to configure a branch name that GitLab will use to create You can configure a branch name that GitLab uses to create
a downstream pipeline with: a downstream pipeline with:
```yaml ```yaml
...@@ -3668,7 +3668,7 @@ staging: ...@@ -3668,7 +3668,7 @@ staging:
branch: stable branch: stable
``` ```
It's possible to mirror the status from a triggered pipeline: To mirror the status from a triggered pipeline:
```yaml ```yaml
trigger_job: trigger_job:
...@@ -3677,7 +3677,7 @@ trigger_job: ...@@ -3677,7 +3677,7 @@ trigger_job:
strategy: depend strategy: depend
``` ```
It's possible to mirror the status from an upstream pipeline: To mirror the status from an upstream pipeline:
```yaml ```yaml
upstream_bridge: upstream_bridge:
...@@ -3741,8 +3741,8 @@ By default, the `trigger` job completes with the `success` status ...@@ -3741,8 +3741,8 @@ By default, the `trigger` job completes with the `success` status
as soon as the downstream pipeline is created. as soon as the downstream pipeline is created.
To force the `trigger` job to wait for the downstream (multi-project or child) pipeline to complete, use To force the `trigger` job to wait for the downstream (multi-project or child) pipeline to complete, use
`strategy: depend`. This will make the trigger job wait with a "running" status until the triggered `strategy: depend`. This setting makes the trigger job wait with a "running" status until the triggered
pipeline completes. At that point, the `trigger` job will complete and display the same status as pipeline completes. At that point, the `trigger` job completes and displays the same status as
the downstream job. the downstream job.
```yaml ```yaml
...@@ -3752,8 +3752,8 @@ trigger_job: ...@@ -3752,8 +3752,8 @@ trigger_job:
strategy: depend strategy: depend
``` ```
This can help keep your pipeline execution linear. In the example above, jobs from This setting can help keep your pipeline execution linear. In the example above, jobs from
subsequent stages will wait for the triggered pipeline to successfully complete before subsequent stages wait for the triggered pipeline to successfully complete before
starting, at the cost of reduced parallelization. starting, at the cost of reduced parallelization.
#### Trigger a pipeline by API call #### Trigger a pipeline by API call
...@@ -3770,10 +3770,10 @@ Not to be confused with the [`trigger`](#trigger) parameter. ...@@ -3770,10 +3770,10 @@ Not to be confused with the [`trigger`](#trigger) parameter.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3.
`interruptible` is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Defaults to `false`. `interruptible` is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Defaults to `false`.
This value will only be used if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-pending-pipelines) This value is used only if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-pending-pipelines)
is enabled. is enabled.
When enabled, a pipeline on the same branch will be canceled when: When enabled, a pipeline on the same branch is canceled when:
- It's made redundant by a newer pipeline run. - It's made redundant by a newer pipeline run.
- Either all jobs are set as interruptible, or any uninterruptible jobs haven't started. - Either all jobs are set as interruptible, or any uninterruptible jobs haven't started.
...@@ -3809,13 +3809,13 @@ step-3: ...@@ -3809,13 +3809,13 @@ step-3:
interruptible: true interruptible: true
``` ```
In the example above, a new pipeline run will cause an existing running pipeline to be: In the example above, a new pipeline run causes an existing running pipeline to be:
- Canceled, if only `step-1` is running or pending. - Canceled, if only `step-1` is running or pending.
- Not canceled, once `step-2` starts running. - Not canceled, once `step-2` starts running.
NOTE: **Note:** NOTE: **Note:**
Once an uninterruptible job is running, the pipeline will never be canceled, regardless of the final job's state. When an uninterruptible job is running, the pipeline can never be canceled, regardless of the final job's state.
### `resource_group` ### `resource_group`
...@@ -3842,9 +3842,9 @@ deploy-to-production: ...@@ -3842,9 +3842,9 @@ deploy-to-production:
``` ```
In this case, if a `deploy-to-production` job is running in a pipeline, and a new In this case, if a `deploy-to-production` job is running in a pipeline, and a new
`deploy-to-production` job is created in a different pipeline, it won't run until `deploy-to-production` job is created in a different pipeline, it doesn't run until
the currently running/pending `deploy-to-production` job is finished. As a result, the currently running/pending `deploy-to-production` job finishes. As a result,
you can ensure that concurrent deployments will 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 There can be multiple `resource_group`s defined per environment. A good use case for this
is when deploying to physical devices. You may have more than one physical device, and each is when deploying to physical devices. You may have more than one physical device, and each
...@@ -4064,7 +4064,7 @@ environment variables. ...@@ -4064,7 +4064,7 @@ environment variables.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in GitLab 13.4. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in GitLab 13.4.
`vault` keyword specifies secrets provided by [Hashicorp's Vault](https://www.vaultproject.io/). `vault` keyword specifies secrets provided by [Hashicorp's Vault](https://www.vaultproject.io/).
This syntax has multiple forms. The shortest form asssumes the use of the This syntax has multiple forms. The shortest form assumes the use of the
[KV-V2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) secrets engine, [KV-V2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) secrets engine,
mounted at the default path `kv-v2`. The last part of the secret's path is the mounted at the default path `kv-v2`. The last part of the secret's path is the
field to fetch the value for: field to fetch the value for:
...@@ -4175,7 +4175,7 @@ May change or be removed completely in future releases. ...@@ -4175,7 +4175,7 @@ May change or be removed completely in future releases.
You can set the `GIT_STRATEGY` used for getting recent application code, either You can set the `GIT_STRATEGY` used for getting recent application code, either
globally or per-job in the [`variables`](#variables) section. If left globally or per-job in the [`variables`](#variables) section. If left
unspecified, the default from project settings will be used. unspecified, the default from the project settings is used.
There are three possible values: `clone`, `fetch`, and `none`. There are three possible values: `clone`, `fetch`, and `none`.
...@@ -4223,10 +4223,10 @@ globally or per-job in the [`variables`](#variables) section. ...@@ -4223,10 +4223,10 @@ globally or per-job in the [`variables`](#variables) section.
There are three possible values: `none`, `normal`, and `recursive`: There are three possible values: `none`, `normal`, and `recursive`:
- `none` means that submodules won't be included when fetching the project - `none` means that submodules are not included when fetching the project
code. This is the default, which matches the pre-v1.10 behavior. code. This is the default, which matches the pre-v1.10 behavior.
- `normal` means that only the top-level submodules will be included. It's - `normal` means that only the top-level submodules are included. It's
equivalent to: equivalent to:
```shell ```shell
...@@ -4235,7 +4235,7 @@ There are three possible values: `none`, `normal`, and `recursive`: ...@@ -4235,7 +4235,7 @@ There are three possible values: `none`, `normal`, and `recursive`:
``` ```
- `recursive` means that all submodules (including submodules of submodules) - `recursive` means that all submodules (including submodules of submodules)
will be included. This feature needs Git v1.8.1 and later. When using a are included. This feature needs Git v1.8.1 and later. When using a
GitLab Runner with an executor not based on Docker, make sure the Git version GitLab Runner with an executor not based on Docker, make sure the Git version
meets that requirement. It's equivalent to: meets that requirement. It's equivalent to:
...@@ -4244,7 +4244,7 @@ There are three possible values: `none`, `normal`, and `recursive`: ...@@ -4244,7 +4244,7 @@ There are three possible values: `none`, `normal`, and `recursive`:
git submodule update --init --recursive git submodule update --init --recursive
``` ```
Note that for this feature to work correctly, the submodules must be configured For this feature to work correctly, the submodules must be configured
(in `.gitmodules`) with either: (in `.gitmodules`) with either:
- the HTTP(S) URL of a publicly-accessible repository, or - the HTTP(S) URL of a publicly-accessible repository, or
...@@ -4260,15 +4260,15 @@ The `GIT_CHECKOUT` variable can be used when the `GIT_STRATEGY` is set to either ...@@ -4260,15 +4260,15 @@ The `GIT_CHECKOUT` variable can be used when the `GIT_STRATEGY` is set to either
specified, it defaults to true. You can set them globally or per-job in the specified, it defaults to true. You can set them globally or per-job in the
[`variables`](#variables) section. [`variables`](#variables) section.
If set to `false`, the runner will: If set to `false`, the runner:
- when doing `fetch` - update the repository and leave working copy on - when doing `fetch` - updates the repository and leaves the working copy on
the current revision, the current revision,
- when doing `clone` - clone the repository and leave working copy on the - when doing `clone` - clones the repository and leaves the working copy on the
default branch. default branch.
Having this setting set to `true` will mean that for both `clone` and `fetch` Having this setting set to `true` means that for both `clone` and `fetch`
strategies the runner will checkout the working copy to a revision related strategies the runner checks out the working copy to a revision related
to the CI pipeline: to the CI pipeline:
```yaml ```yaml
...@@ -4314,7 +4314,7 @@ script: ...@@ -4314,7 +4314,7 @@ script:
The `GIT_FETCH_EXTRA_FLAGS` variable is used to control the behavior of The `GIT_FETCH_EXTRA_FLAGS` variable is used to control the behavior of
`git fetch`. You can set it globally or per-job in the [`variables`](#variables) section. `git fetch`. You can set it globally or per-job in the [`variables`](#variables) section.
`GIT_FETCH_EXTRA_FLAGS` accepts all possible options of the [`git fetch`](https://git-scm.com/docs/git-fetch) command, but please note that `GIT_FETCH_EXTRA_FLAGS` flags will be appended after the default flags that can't be modified. `GIT_FETCH_EXTRA_FLAGS` accepts all possible options of the [`git fetch`](https://git-scm.com/docs/git-fetch) command, but `GIT_FETCH_EXTRA_FLAGS` flags are appended after the default flags that can't be modified.
The default flags are: The default flags are:
...@@ -4336,7 +4336,7 @@ script: ...@@ -4336,7 +4336,7 @@ script:
- ls -al cache/ - ls -al cache/
``` ```
The configuration above will result in `git fetch` being called this way: The configuration above results in `git fetch` being called this way:
```shell ```shell
git fetch origin $REFSPECS --depth 50 --prune git fetch origin $REFSPECS --depth 50 --prune
...@@ -4348,8 +4348,8 @@ Where `$REFSPECS` is a value provided to the runner internally by GitLab. ...@@ -4348,8 +4348,8 @@ Where `$REFSPECS` is a value provided to the runner internally by GitLab.
> Introduced in GitLab, it requires GitLab Runner v1.9+. > Introduced in GitLab, it requires GitLab Runner v1.9+.
You can set the number for attempts the running job will try to execute each You can set the number of attempts that the running job tries to execute
of the following stages: the following stages:
| Variable | Description | | Variable | Description |
|-----------------------------------|--------------------------------------------------------| |-----------------------------------|--------------------------------------------------------|
...@@ -4374,7 +4374,7 @@ You can set them globally or per-job in the [`variables`](#variables) section. ...@@ -4374,7 +4374,7 @@ You can set them globally or per-job in the [`variables`](#variables) section.
> Introduced in GitLab 8.9 as an experimental feature. > Introduced in GitLab 8.9 as an experimental feature.
NOTE: **Note:** NOTE: **Note:**
As of GitLab 12.0, newly created projects will automatically have a [default `git depth` value of `50`](../pipelines/settings.md#git-shallow-clone). In GitLab 12.0 and later, newly-created projects automatically have a [default `git depth` value of `50`](../pipelines/settings.md#git-shallow-clone).
You can specify the depth of fetching and cloning using `GIT_DEPTH`. This does a You can specify the depth of fetching and cloning using `GIT_DEPTH`. This does a
shallow clone of the repository and can significantly speed up cloning for shallow clone of the repository and can significantly speed up cloning for
...@@ -4387,9 +4387,9 @@ jobs, jobs may fail. ...@@ -4387,9 +4387,9 @@ jobs, jobs may fail.
Since Git fetching and cloning is based on a ref, such as a branch name, runners Since Git fetching and cloning is based on a ref, such as a branch name, runners
can't clone a specific commit SHA. If there are multiple jobs in the queue, or can't clone a specific commit SHA. If there are multiple jobs in the queue, or
you're retrying an old job, the commit to be tested needs to be within the you're retrying an old job, the commit to be tested must be within the
Git history that is cloned. Setting too small a value for `GIT_DEPTH` can make Git history that is cloned. Setting too small a value for `GIT_DEPTH` can make
it impossible to run these old commits. You will see `unresolved reference` in it impossible to run these old commits and `unresolved reference` is displayed in
job logs. You should then reconsider changing `GIT_DEPTH` to a higher value. job logs. You should then reconsider changing `GIT_DEPTH` to a higher value.
Jobs that rely on `git describe` may not work correctly when `GIT_DEPTH` is Jobs that rely on `git describe` may not work correctly when `GIT_DEPTH` is
...@@ -4507,12 +4507,12 @@ need to be used to merge arrays. ...@@ -4507,12 +4507,12 @@ need to be used to merge arrays.
YAML has a handy feature called 'anchors', which lets you easily duplicate YAML has a handy feature called 'anchors', which lets you easily duplicate
content across your document. Anchors can be used to duplicate/inherit content across your document. Anchors can be used to duplicate/inherit
properties, and is a perfect example to be used with [hidden jobs](#hide-jobs) properties, and is a perfect example to be used with [hidden jobs](#hide-jobs)
to provide templates for your jobs. When there is duplicate keys, GitLab will to provide templates for your jobs. When there are duplicate keys, GitLab
perform a reverse deep merge based on the keys. performs a reverse deep merge based on the keys.
The following example uses anchors and map merging. It will create two jobs, The following example uses anchors and map merging. It creates two jobs,
`test1` and `test2`, that will inherit the parameters of `.job_template`, each `test1` and `test2`, that inherit the parameters of `.job_template`, each
having their own custom `script` defined: with their own custom `script` defined:
```yaml ```yaml
.job_template: &job_definition # Hidden key that defines an anchor named 'job_definition' .job_template: &job_definition # Hidden key that defines an anchor named 'job_definition'
...@@ -4560,9 +4560,9 @@ test2: ...@@ -4560,9 +4560,9 @@ test2:
- test2 project - test2 project
``` ```
Let's see another one example. This time we will use anchors to define two sets Let's see another example. This time we use anchors to define two sets
of services. This will create two jobs, `test:postgres` and `test:mysql`, that of services. This configuration creates two jobs, `test:postgres` and `test:mysql`, that
will share the `script` directive defined in `.job_template`, and the `services` share the `script` directive defined in `.job_template`, and the `services`
directive defined in `.postgres_services` and `.mysql_services` respectively: directive defined in `.postgres_services` and `.mysql_services` respectively:
```yaml ```yaml
...@@ -4693,7 +4693,7 @@ job_name: ...@@ -4693,7 +4693,7 @@ job_name:
of variables across multiple jobs. It can also enable more flexibility when a job of variables across multiple jobs. It can also enable more flexibility when a job
requires a specific `variables` block that would otherwise override the global variables. requires a specific `variables` block that would otherwise override the global variables.
In the example below, we will override the `GIT_STRATEGY` variable without affecting In the example below, we override the `GIT_STRATEGY` variable without affecting
the use of the `SAMPLE_VARIABLE` variable: the use of the `SAMPLE_VARIABLE` variable:
```yaml ```yaml
...@@ -4702,7 +4702,7 @@ variables: &global-variables ...@@ -4702,7 +4702,7 @@ variables: &global-variables
SAMPLE_VARIABLE: sample_variable_value SAMPLE_VARIABLE: sample_variable_value
ANOTHER_SAMPLE_VARIABLE: another_sample_variable_value ANOTHER_SAMPLE_VARIABLE: another_sample_variable_value
# a job that needs to set the GIT_STRATEGY variable, yet depend on global variables # a job that must set the GIT_STRATEGY variable, yet depend on global variables
job_no_git_strategy: job_no_git_strategy:
stage: cleanup stage: cleanup
variables: variables:
...@@ -4724,8 +4724,8 @@ lines where the job is defined: ...@@ -4724,8 +4724,8 @@ lines where the job is defined:
# - run test # - run test
``` ```
You can instead start its name with a dot (`.`) and it won't be processed by Instead, you can start its name with a dot (`.`) and it is not processed by
GitLab CI/CD. In the following example, `.hidden_job` will be ignored: GitLab CI/CD. In the following example, `.hidden_job` is ignored:
```yaml ```yaml
.hidden_job: .hidden_job:
...@@ -4740,18 +4740,18 @@ into templates. ...@@ -4740,18 +4740,18 @@ into templates.
## Skip Pipeline ## Skip Pipeline
If your commit message contains `[ci skip]` or `[skip ci]`, using any If your commit message contains `[ci skip]` or `[skip ci]`, using any
capitalization, the commit will be created but the pipeline will be skipped. capitalization, the commit is created but the pipeline is skipped.
Alternatively, one can pass the `ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd) Alternatively, one can pass the `ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd)
if using Git 2.10 or newer. if using Git 2.10 or newer.
## Processing Git pushes ## Processing Git pushes
GitLab will create at most 4 branch and tag pipelines when GitLab creates at most four branch and tag pipelines when
pushing multiple changes in single `git push` invocation. pushing multiple changes in single `git push` invocation.
This limitation does not affect any of the updated Merge Request pipelines. This limitation does not affect any of the updated merge request pipelines.
All updated Merge Requests will have a pipeline created when using All updated merge requests have a pipeline created when using
[pipelines for merge requests](../merge_request_pipelines/index.md). [pipelines for merge requests](../merge_request_pipelines/index.md).
## Deprecated parameters ## Deprecated parameters
......
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