Merge branch 'fneill-refactor-runner-config-sections' into 'master'

Refactor runner config sections

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127349



Merged-by: Russell Dickenson <rdickenson@gitlab.com>
Approved-by: Russell Dickenson <rdickenson@gitlab.com>
Co-authored-by: fneill <fneill@gitlab.com>

doc/ci/runners/configure_runners.md

@@ -57,59 +57,47 @@ How this feature works:
 1. You start a job
 1. The job, if running longer, times out after **30 minutes**
 
-## Be careful with sensitive information
+## Protecting sensitive information
 
-With some [runner executors](https://docs.gitlab.com/runner/executors/),
-if you can run a job on the runner, you can get full access to the file system,
-and thus any code it runs as well as the token of the runner. With shared runners, this means that anyone
-that runs jobs on the runner, can access another user's code that runs on the
-runner.
+To avoid exposing sensitive information, you can restrict the usage
+of shared runners on large GitLab instances. This ensures that you
+control access to your GitLab instances and secure [runner executors](https://docs.gitlab.com/runner/executors/).
 
-In addition, because you can get access to the runner token, it is possible
-to create a clone of a runner and submit false jobs, for example.
-
-The above is easily avoided by restricting the usage of shared runners
-on large public GitLab instances, controlling access to your GitLab instance,
-and using more secure [runner executors](https://docs.gitlab.com/runner/executors/).
+If certain executors run a job, the file system, the code the runner executes,
+and the runner token may be exposed. This means that anyone that runs jobs
+on a _shared runner_ can access another user's code that runs on the runner.
+Users with access to the runner token can use it to create a clone of
+a runner and submit false jobs in a vector attack. For more information, see [Security Considerations](https://docs.gitlab.com/runner/security/).
 
 ### Prevent runners from revealing sensitive information
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13194) in GitLab 10.0.
-
-You can protect runners so they don't reveal sensitive information.
-When a runner is protected, the runner picks jobs created on
-[protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md) only,
-and ignores other jobs.
+To ensure runners don't reveal sensitive information, you can configure them to only run jobs
+on [protected branches](../../user/project/protected_branches.md), or jobs that have [protected tags](../../user/project/protected_tags.md).
 
-To protect or unprotect a runner:
+To prevent runners from revealing sensitive information:
 
-1. Go to the project's **Settings > CI/CD** and expand the **Runners** section.
-1. Find the runner you want to protect or unprotect. Make sure it's enabled.
-1. Select the pencil button.
-1. Check the **Protected** option.
+1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project.
+1. Select **Settings > CI/CD**.
+1. Expand **Runners**.
+1. Find the runner you want to protect or unprotect. Make sure the runner is enabled.
+1. Select **Edit** (**{pencil}**).
+1. Select the **Protected** checkbox.
 1. Select **Save changes**.
 
-![Protect project runners checkbox](img/protected_runners_check_box_v14_1.png)
-
-### Forks
+### Using shared runners in forked projects
 
-Whenever a project is forked, it copies the settings of the jobs that relate
-to it. This means that if you have shared runners set up for a project and
-someone forks that project, the shared runners serve jobs of this project.
+When a project is forked, the job settings related to jobs are copied. If you have shared runners
+configured for a project and a user forks that project, the shared runners serve jobs of this project.
 
-Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/364303), you might encounter the message `An error occurred while forking the project. Please try again.` if the runner settings of the project you are forking does not match the new project namespace.
+Due to a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/364303), if the runner settings
+of the forked project does not match the new project namespace, the following message displays:
+`An error occurred while forking the project. Please try again.`.
 
-To work around this issue, you should make sure that the shared runner settings are consistent in the forked project and the new namespace.
+To work around this issue, ensure that the shared runner settings are consistent in the forked project and the new namespace.
 
 - If shared runners are **enabled** on the forked project, then this should also be **enabled** on the new namespace.
 - If shared runners are **disabled** on the forked project, then this should also be **disabled** on the new namespace.
 
-### Attack vectors in runners
-
-Mentioned briefly earlier, but the following things of runners can be exploited.
-We're always looking for contributions that can mitigate these
-[Security Considerations](https://docs.gitlab.com/runner/security/).
-
 ### Reset the runner registration token for a project
 
 If you think that a registration token for a project was revealed, you should
@@ -142,19 +130,13 @@ To verify that the previous authentication token has been revoked, use the [Runn
 
 ## Use tags to control which jobs a runner can run
 
-You must set up a runner to be able to run all the different types of jobs
-that it may encounter on the projects it's shared over. This would be
-problematic for large amounts of projects, if it weren't for tags.
+You can use [tags](../yaml/index.md#tags) to ensure that runners only run the jobs they are equipped
+to run. For example, you can specify the `rails` tag for runners that have the dependencies to run
+Rails test suites.
 
-GitLab CI/CD tags are not the same as Git tags. GitLab CI/CD tags are associated with runners.
+GitLab CI/CD tags are different to Git tags. GitLab CI/CD tags are associated with runners.
 Git tags are associated with commits.
 
-By tagging a runner for the types of jobs it can handle, you can make sure
-shared runners will [only run the jobs they are equipped to run](../yaml/index.md#tags).
-
-For instance, at GitLab we have runners tagged with `rails` if they contain
-the appropriate dependencies to run Rails test suites.
-
 ### Set a runner to run untagged jobs
 
 When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick**
@@ -302,9 +284,6 @@ When using the Kubernetes executor, you can use variables to
 
 ### Git strategy
 
-> - Introduced in GitLab 8.9 as an experimental feature.
-> - `GIT_STRATEGY=none` requires GitLab Runner v1.7+.
-
 You can set the `GIT_STRATEGY` used to fetch the repository content, either
 globally or per-job in the [`variables`](../yaml/index.md#variables) section:
 
@@ -341,8 +320,6 @@ rely on files brought into the local working copy from cache or artifacts.
 
 ### Git submodule strategy
 
-> Requires GitLab Runner v1.10+.
-
 The `GIT_SUBMODULE_STRATEGY` variable is used to control if / how Git
 submodules are included when fetching the code before a build. You can set them
 globally or per-job in the [`variables`](../yaml/index.md#variables) section.
@@ -381,8 +358,6 @@ You can provide additional flags to control advanced behavior using [`GIT_SUBMOD
 
 ### Git checkout
 
-> Introduced in GitLab Runner 9.3.
-
 The `GIT_CHECKOUT` variable can be used when the `GIT_STRATEGY` is set to either
 `clone` or `fetch` to specify whether a `git checkout` should be run. If not
 specified, it defaults to true. You can set them globally or per-job in the
@@ -410,8 +385,6 @@ script:
 
 ### Git clean flags
 
-> Introduced in GitLab Runner 11.10
-
 The `GIT_CLEAN_FLAGS` variable is used to control the default behavior of
 `git clean` after checking out the sources. You can set it globally or per-job in the
 [`variables`](../yaml/index.md#variables) section.
@@ -437,8 +410,6 @@ script:
 
 ### Git fetch extra flags
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4142) in GitLab Runner 13.1.
-
 Use the `GIT_FETCH_EXTRA_FLAGS` variable to control the behavior of
 `git fetch`. You can set it globally or per-job in the [`variables`](../yaml/index.md#variables) section.
 
@@ -503,8 +474,6 @@ to wrap the string in single quotes so the YAML can be parsed successfully.
 
 ### Git submodule update flags
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3192) in GitLab Runner 14.8.
-
 Use the `GIT_SUBMODULE_UPDATE_FLAGS` variable to control the behavior of `git submodule update`
 when [`GIT_SUBMODULE_STRATEGY`](#git-submodule-strategy) is set to either `normal` or `recursive`.
 You can set it globally or per-job in the [`variables`](../yaml/index.md#variables) section.
@@ -561,8 +530,6 @@ the permissions of the user executing the job, and does not require SSH credenti
 
 ### Shallow cloning
 
-> Introduced in GitLab 8.9 as an experimental feature.
-
 You can specify the depth of fetching and cloning using `GIT_DEPTH`.
 `GIT_DEPTH` does a shallow clone of the repository and can significantly speed up cloning.
 It can be helpful for repositories with a large number of commits or old, large binaries. The value is
@@ -613,8 +580,6 @@ variables:
 
 ### Custom build directories
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2211) in GitLab Runner 11.10.
-
 By default, GitLab Runner clones the repository in a unique subpath of the
 `$CI_BUILDS_DIR` directory. However, your project might require the code in a
 specific directory (Go projects, for example). In that case, you can specify
@@ -696,8 +661,6 @@ because `$CI_BUILDS_DIR` is not expanded.
 
 ### Job stages attempts
 
-> Introduced in GitLab, it requires GitLab Runner v1.9+.
-
 You can set the number of attempts that the running job tries to execute
 the following stages:
 
@@ -725,8 +688,6 @@ GitLab.com shared runners run on CoreOS. This means that you cannot use some sys
 
 ## Artifact and cache settings
 
-> Introduced in GitLab Runner 13.9.
-
 Artifact and cache settings control the compression ratio of artifacts and caches.
 Use these settings to specify the size of the archive produced by a job.
 

doc/user/project/repository/forking_workflow.md

@@ -202,7 +202,7 @@ to share objects with another repository:
 ### Error: `An error occurred while forking the project. Please try again`
 
 This error can be due to a mismatch in shared runner settings between the forked project
-and the new namespace. See [Forks](../../../ci/runners/configure_runners.md#forks)
+and the new namespace. See [Forks](../../../ci/runners/configure_runners.md#using-shared-runners-in-forked-projects)
 in the Runner documentation for more information.
 
 ### Removing fork relationship fails