Merge branch 'feature/runner-script-attempts-docs' into 'master'

Add new runner script attempts docs and update .gitlab-ci.yml

Related: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/issues/1907 and https://gitlab.com/gitlab-com/infrastructure/issues/685

Adds missing docs about the new script attempts variables in the runner.

See merge request !8100

.gitlab-ci.yml

@@ -15,6 +15,7 @@ variables:
   USE_BUNDLE_INSTALL: "true"
   GIT_DEPTH: "20"
   PHANTOMJS_VERSION: "2.1.1"
+  GET_SOURCES_ATTEMPTS: "3"
 
 before_script:
   - source ./scripts/prepare_build.sh

doc/ci/variables/README.md

@@ -61,6 +61,9 @@ version of Runner required.
 | **CI_RUNNER_DESCRIPTION** | 8.10 | 0.5    | The description of the runner as saved in GitLab |
 | **CI_RUNNER_TAGS**      | 8.10   | 0.5    | The defined runner tags |
 | **CI_DEBUG_TRACE**      | all    | 1.7    | Whether [debug tracing](#debug-tracing) is enabled |
+| **GET_SOURCES_ATTEMPTS** | 8.15    | 1.9    | Number of attempts to fetch sources running a build |
+| **ARTIFACT_DOWNLOAD_ATTEMPTS** | 8.15    | 1.9    | Number of attempts to download artifacts running a build |
+| **RESTORE_CACHE_ATTEMPTS** | 8.15    | 1.9    | Number of attempts to restore the cache running a build |
 | **GITLAB_USER_ID**      | 8.12   | all    | The id of the user who started the build |
 | **GITLAB_USER_EMAIL**   | 8.12   | all    | The email of the user who started the build |
 

doc/ci/yaml/README.md

@@ -1034,6 +1034,31 @@ variables:
   GIT_STRATEGY: none
 ```
 
+## Build stages attempts
+
+> Introduced in GitLab, it requires GitLab Runner v1.9+.
+
+You can set the number for attempts the running build will try to execute each
+of the following stages:
+
+| Variable                | Description |
+|-------------------------|-------------|
+| **GET_SOURCES_ATTEMPTS** | Number of attempts to fetch sources running a build |
+| **ARTIFACT_DOWNLOAD_ATTEMPTS** | Number of attempts to download artifacts running a build |
+| **RESTORE_CACHE_ATTEMPTS** | Number of attempts to restore the cache running a build |
+
+The default is one single attempt.
+
+Example:
+
+```
+variables:
+  GET_SOURCES_ATTEMPTS: "3"
+```
+
+You can set the them in the global [`variables`](#variables) section or the [`variables`](#job-variables)
+section for individual jobs.
+
 ## Shallow cloning
 
 > Introduced in GitLab 8.9 as an experimental feature. May change in future