Commit 266e7ad1 authored by Suzanne Selhorn's avatar Suzanne Selhorn

Merge branch 'docs-retry-keyword-revamp' into 'master'

Update docs for retry keyword

See merge request gitlab-org/gitlab!71547
parents b62971ad 3cf0fec7
...@@ -3342,56 +3342,38 @@ to select a specific site profile and scanner profile. ...@@ -3342,56 +3342,38 @@ to select a specific site profile and scanner profile.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3515) in GitLab 11.5, you can control which failures to retry on. > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3515) in GitLab 11.5, you can control which failures to retry on.
Use `retry` to configure how many times a job is retried in Use `retry` to configure how many times a job is retried if it fails.
case of a failure. If not defined, defaults to `0` and jobs do not retry.
When a job fails, the job is processed again, When a job fails, the job is processed up to two more times, until it succeeds or
until the limit specified by the `retry` keyword is reached. reaches the maximum number of retries.
If `retry` is set to `2`, and a job succeeds in a second run (first retry), it is not retried. By default, all failure types cause the job to be retried. Use [`retry:when`](#retrywhen)
The `retry` value must be a positive integer, from `0` to `2` to select which failures to retry on.
(two retries maximum, three runs in total).
The following example retries all failure cases: **Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
```yaml
test:
script: rspec
retry: 2
```
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:
- `max`: The maximum number of retries. **Possible inputs**: `0` (default), `1`, or `2`.
- `when`: The failure cases to retry.
To retry only runner system failures at maximum two times: **Example of `retry`**:
```yaml ```yaml
test: test:
script: rspec script: rspec
retry: retry: 2
max: 2
when: runner_system_failure
``` ```
If there is another failure, other than a runner system failure, the job #### `retry:when`
is not retried.
To retry on multiple failure cases, `when` can also be an array of failures: Use `retry:when` with `retry:max` to retry jobs for only specific failure cases.
`retry:max` is the maximum number of retries, like [`retry`](#retry), and can be
`0`, `1`, or `2`.
```yaml **Keyword type**: Job keyword. You can use it only as part of a job or in the
test: [`default:` section](#custom-default-keyword-values).
script: rspec
retry:
max: 2
when:
- runner_system_failure
- stuck_or_timeout_failure
```
Possible values for `when` are: **Possible inputs**: A single failure type, or an array of one or more failure types:
<!-- <!--
If you change any of the values below, make sure to update the `RETRY_WHEN_IN_DOCUMENTATION` If you change any of the values below, make sure to update the `RETRY_WHEN_IN_DOCUMENTATION`
...@@ -3415,7 +3397,34 @@ Possible values for `when` are: ...@@ -3415,7 +3397,34 @@ Possible values for `when` are:
- `scheduler_failure`: Retry if the scheduler failed to assign the job to a runner. - `scheduler_failure`: Retry if the scheduler failed to assign the job to a runner.
- `data_integrity_failure`: Retry if there is a structural integrity problem detected. - `data_integrity_failure`: Retry if there is a structural integrity problem detected.
You can specify the number of [retry attempts for certain stages of job execution](../runners/configure_runners.md#job-stages-attempts) using variables. **Example of `retry:when`** (single failure type):
```yaml
test:
script: rspec
retry:
max: 2
when: runner_system_failure
```
If there is a failure other than a runner system failure, the job is not retried.
**Example of `retry:when`** (array of failure types):
```yaml
test:
script: rspec
retry:
max: 2
when:
- runner_system_failure
- stuck_or_timeout_failure
```
**Related topics**:
You can specify the number of [retry attempts for certain stages of job execution](../runners/configure_runners.md#job-stages-attempts)
using variables.
### `timeout` ### `timeout`
......
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