Add latest changes from gitlab-org/gitlab@15-4-stable-eev15.4.0-rc42

4 files changed, 137 insertions, 42 deletions

diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md
index 3efa697bf2f..9d26ec63f96 100644
--- a/doc/ci/runners/configure_runners.md
+++ b/doc/ci/runners/configure_runners.md
@@ -151,7 +151,7 @@ different places.
 To view the IP address of a shared runner you must have administrator access to
 the GitLab instance. To determine this:
 
-1. On the top bar, select **Menu > Admin**.
+1. On the top bar, select **Main menu > Admin**.
 1. On the left sidebar, select **Overview > Runners**.
 1. Find the runner in the table and view the **IP Address** column.
 
@@ -859,7 +859,7 @@ You can clean up group runners that have been inactive for more than three month
 
 Group runners are those that were created at the group level.
 
-1. On the top bar, select **Menu > Groups** and find your group.
+1. On the top bar, select **Main menu > Groups** and find your group.
 1. On the left sidebar, select **Settings > CI/CD**.
 1. Expand **Runners**.
 1. Turn on the **Enable stale runner cleanup** toggle.
@@ -903,8 +903,8 @@ The version of GitLab Runner used by your runners should be
 To determine which runners need to be upgraded:
 
 1. View the list of runners:
-   - For a group, on the top bar, select **Menu > Groups** and on the left sidebar, select **CI/CD > Runners**.
-   - For the instance, select **Menu > Admin** and on the left sidebar, select **Runners**.
+   - For a group, on the top bar, select **Main menu > Groups**, find your group, and on the left sidebar select **CI/CD > Runners**.
+   - For the instance, select **Main menu > Admin** and on the left sidebar, select **Runners**.
 
 1. Above the list of runners, view the status:
    - **Outdated - recommended**: The runner does not have the latest `PATCH` version, which may make it vulnerable
@@ -912,3 +912,43 @@ To determine which runners need to be upgraded:
    - **Outdated - available**: Newer versions are available but upgrading is not critical.
 
 1. Filter the list by status to view which individual runners need to be upgraded.
+
+## Authentication token security
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. Disabled by default.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to
+[enable the feature flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`.
+On GitLab.com, this feature is not available.
+
+Each runner has an [authentication token](../../api/runners.md#registration-and-authentication-tokens)
+to connect with the GitLab instance.
+
+To help prevent the token from being compromised, you can have the
+token rotate automatically at specified intervals. When the tokens are rotated,
+they are updated for each runner, regardless of the runner's status (`online` or `offline`).
+
+No manual intervention should be required, and no running jobs should be affected.
+
+If you need to manually update the authentication token, you can run a
+command to [reset the token](https://docs.gitlab.com/runner/commands/#gitlab-runner-reset-token).
+
+### Automatically rotate authentication tokens
+
+You can specify an interval for authentication tokens to rotate.
+This rotation helps ensure the security of the tokens assigned to your runners.
+
+Prerequisites:
+
+- Ensure your runners are using [GitLab Runner 15.3 or later](https://docs.gitlab.com/runner/#gitlab-runner-versions).
+
+To automatically rotate runner authentication tokens:
+
+1. On the top bar, select **Main menu > Admin**.
+1. On the left sidebar, select **Settings > CI/CD**.
+1. Expand **Continuous Integration and Deployment**
+1. Set a **Runners expiration** time for runners, leave empty for no expiration.
+1. Select **Save**.
+
+Before the interval expires, runners automatically request a new authentication token.
diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md
index f69d1f0f730..1de24efa8aa 100644
--- a/doc/ci/runners/index.md
+++ b/doc/ci/runners/index.md
@@ -7,8 +7,8 @@ type: reference
 
 # Runner SaaS **(FREE SAAS)**
 
-If you use GitLab SaaS (GitLab.com), your CI jobs automatically run on runners provided by GitLab.
-No configuration is required. Your jobs can run on:
+If you use GitLab SaaS (GitLab.com), your [untagged](../../ci/runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) CI jobs automatically run in containers on the Linux Runners.
+As long as shared runners are enabled for your project, no configuration is required. Your jobs can run on:
 
 - [Linux runners](saas/linux_saas_runner.md).
 - [Windows runners](saas/windows_saas_runner.md) ([Beta](../../policy/alpha-beta-support.md#beta-features)).
diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md
index 9bd0b52f423..f8a33ea6861 100644
--- a/doc/ci/runners/runners_scope.md
+++ b/doc/ci/runners/runners_scope.md
@@ -28,7 +28,7 @@ If you are using a self-managed instance of GitLab:
   going to your project's **Settings > CI/CD**, expanding **Runners**,
   and selecting **Show runner installation instructions**.
   These instructions are also available [in the documentation](https://docs.gitlab.com/runner/install/index.html).
-- The administrator can also configure a maximum number of shared runner 
+- The administrator can also configure a maximum number of shared runner
   [CI/CD minutes for each group](../pipelines/cicd_minutes.md#set-the-quota-of-cicd-minutes-for-a-specific-namespace).
 
 If you are using GitLab.com:
@@ -51,7 +51,7 @@ For existing projects, an administrator must
 
 To enable shared runners for a project:
 
-1. On the top bar, select **Menu > Projects** and find your project.
+1. On the top bar, select **Main menu > Projects** and find your project.
 1. On the left sidebar, select **Settings > CI/CD**.
 1. Expand **Runners**.
 1. Turn on the **Enable shared runners for this project** toggle.
@@ -60,7 +60,7 @@ To enable shared runners for a project:
 
 To enable shared runners for a group:
 
-1. On the top bar, select **Menu > Groups** and find your group.
+1. On the top bar, select **Main menu > Groups** and find your group.
 1. On the left sidebar, select **Settings > CI/CD**.
 1. Expand **Runners**.
 1. Turn on the **Enable shared runners for this group** toggle.
@@ -73,7 +73,7 @@ or group.
 
 To disable shared runners for a project:
 
-1. On the top bar, select **Menu > Projects** and find your project.
+1. On the top bar, select **Main menu > Projects** and find your project.
 1. On the left sidebar, select **Settings > CI/CD**.
 1. Expand **Runners**.
 1. In the **Shared runners** area, turn off the **Enable shared runners for this project** toggle.
@@ -87,7 +87,7 @@ Shared runners are automatically disabled for a project:
 
 To disable shared runners for a group:
 
-1. On the top bar, select **Menu > Groups** and find your group.
+1. On the top bar, select **Main menu > Groups** and find your group.
 1. On the left sidebar, select **Settings > CI/CD**.
 1. Expand **Runners**.
 1. Turn off the **Enable shared runners for this group** toggle.
@@ -170,7 +170,7 @@ You must have the Owner role for the group.
 To create a group runner:
 
 1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/).
-1. On the top bar, select **Menu > Groups** and find your group.
+1. On the top bar, select **Main menu > Groups** and find your group.
 1. On the left sidebar, select **CI/CD > Runners**.
 1. Note the URL and token.
 1. [Register the runner](https://docs.gitlab.com/runner/register/).
@@ -183,7 +183,7 @@ You can view and manage all runners for a group, its subgroups, and projects.
 You can do this for your self-managed GitLab instance or for GitLab.com.
 You must have the Owner role for the group.
 
-1. On the top bar, select **Menu > Groups** and find your group.
+1. On the top bar, select **Main menu > Groups** and find your group.
 1. On the left sidebar, select **CI/CD > Runners**.
 
 From this page, you can edit, pause, and remove runners from the group, its subgroups, and projects.
@@ -193,7 +193,7 @@ From this page, you can edit, pause, and remove runners from the group, its subg
 You can pause or remove a group runner for your self-managed GitLab instance or for GitLab.com.
 You must have the Owner role for the group.
 
-1. On the top bar, select **Menu > Groups** and find your group.
+1. On the top bar, select **Main menu > Groups** and find your group.
 1. On the left sidebar, select **CI/CD > Runners**.
 1. Select **Pause** or **Remove runner**.
    - If you pause a group runner that is used by multiple projects, the runner pauses for all projects.
@@ -229,7 +229,7 @@ Prerequisite:
 To create a specific runner:
 
 1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/).
-1. On the top bar, select **Menu > Projects** and find the project where you want to use the runner.
+1. On the top bar, select **Main menu > Projects** and find the project where you want to use the runner.
 1. On the left sidebar, select **Settings > CI/CD**.
 1. Expand **Runners**.
 1. In the **Specific runners** section, note the URL and token.
@@ -250,7 +250,7 @@ You must have at least the Maintainer role for:
 
 To enable a specific runner for a project:
 
-1. On the top bar, select **Menu > Projects** and find the project where you want to enable the runner.
+1. On the top bar, select **Main menu > Projects** and find the project where you want to enable the runner.
 1. On the left sidebar, select **Settings > CI/CD**.
 1. Expand **Runners**.
 1. In the **Specific runners** area, by the runner you want, select **Enable for this project**.
@@ -269,7 +269,7 @@ but can also be changed later.
 
 To lock or unlock a specific runner:
 
-1. On the top bar, select **Menu > Projects** and find the project where you want to enable the runner.
+1. On the top bar, select **Main menu > Projects** and find the project where you want to enable the runner.
 1. On the left sidebar, select **Settings > CI/CD**.
 1. Expand **Runners**.
 1. Find the specific runner you want to lock or unlock. Make sure it's enabled. You cannot lock shared or group runners.
diff --git a/doc/ci/runners/saas/linux_saas_runner.md b/doc/ci/runners/saas/linux_saas_runner.md
index e96e89b47e5..a7d1b8722a5 100644
--- a/doc/ci/runners/saas/linux_saas_runner.md
+++ b/doc/ci/runners/saas/linux_saas_runner.md
@@ -4,43 +4,97 @@ group: Runner
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# SaaS runners on Linux **(FREE SAAS)**
+# SaaS runners on Linux
 
-SaaS runners on Linux are autoscaled ephemeral Google Cloud Platform virtual machines.
+When you run jobs on SaaS runners on Linux, the runners are on auto-scaled ephemeral virtual machine (VM) instances.
+Each VM uses the Google Container-Optimized OS (COS) and the latest version of Docker Engine.
+The default region for the VMs is `us-east1`.
 
-Autoscaling means reduced queue times to spin up CI/CD jobs, and isolated VMs for each job, thus maximizing security. These shared runners are available on GitLab.com.
+## Machine types available for private projects (x86-64)
 
-GitLab offers Ultimate tier capabilities and included CI/CD minutes per group per month for our [Open Source](https://about.gitlab.com/solutions/open-source/join/), [Education](https://about.gitlab.com/solutions/education/), and [Startups](https://about.gitlab.com/solutions/startups/) programs. For private projects, GitLab offers various [plans](https://about.gitlab.com/pricing/), starting with a Free tier.
+For the SaaS runners on Linux, GitLab offers a range of machine types for use in private projects.
+For Free, Premium, and Ultimate plan customers, jobs on these instances consume the CI/CD minutes allocated to your namespace.
 
-All your CI/CD jobs run on [n1-standard-1 instances](https://cloud.google.com/compute/docs/machine-types) with 3.75GB of RAM, Google COS and the latest Docker Engine
-installed. Instances provide 1 vCPU and 25GB of HDD disk space. The default
-region of the VMs is US East1.
-Each instance is used only for one job. This ensures that any sensitive data left on the system can't be accessed by other people's CI/CD jobs.
+|                   | Small                     | Medium                    | Large                    |
+|-------------------|---------------------------|---------------------------|--------------------------|
+| Specs             | 1 vCPU, 3.75GB RAM        | 2 vCPUs, 8GB RAM          | 4 vCPUs, 16GB RAM        |
+| GitLab CI/CD tags | `saas-linux-small-amd64` | `saas-linux-medium-amd64` | `saas-linux-large-amd64` |
+| Subscription      | Free, Premium, Ultimate   | Free, Premium, Ultimate   | Premium, Ultimate        |
 
-NOTE:
-The final disk space your jobs can use will be less than 25GB. Some disk space allocated to the instance will be occupied by the operating system, the Docker image, and a copy of your cloned repository.
+The `small` machine type is the default. Your job runs on this machine type if you don't specify
+a [tags:](../../yaml/index.md#tags) keyword in your `.gitlab-ci.yml` file.
+
+CI/CD jobs that run on `medium` and `large` machine types **will** consume CI minutes at a different rate than CI/CD jobs on the `small` machine type.
+
+Refer to the CI/CD minutes [cost factor](../../../ci/pipelines/cicd_minutes.md#cost-factor) for the cost factor applied to the machine type based on size.
+
+## Example of how to tag a job
 
-The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated for GitLab projects as well as community forks of them. They use a slightly larger machine type (n1-standard-2) and have a bigger SSD disk size. They don't run untagged jobs and unlike the general fleet of shared runners, the instances are re-used up to 40 times.
+To use a machine type other than `small`, add a `tags:` keyword to your job.
+For example:
 
-Jobs handled by shared runners on GitLab.com (`shared-runners-manager-X.gitlab.com`)
-**time out after 3 hours**, regardless of the timeout configured in a
-project. Check issue [#4010](https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues/4010) and [#4070](https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues/4070) for the reference.
+```yaml
+stages:
+  - Prebuild
+  - Build
+  - Unit Test
 
-Jobs handled by shared runners on Windows and macOS on GitLab.com **time out after 1 hour** while this service is in the [Beta](../../../policy/alpha-beta-support.md#beta-features) stage.
+job_001:
+ stage: Prebuild
+ script:
+  - echo "this job runs on the default (small) instance"
 
-Below are the runners' settings.
+job_002:
+ tags: [ saas-linux-medium-amd64 ]
+ stage: Build
+ script:
+  - echo "this job runs on the medium instance"
+
+
+job_003:
+ tags: [ saas-linux-large-amd64 ]
+ stage: Unit Test
+ script:
+  - echo "this job runs on the large instance"
+
+```
 
-| Setting                               | GitLab.com                                        | Default    |
-| -----------                           | -----------------                                 | ---------- |
-| Executor                              | `docker+machine`                                  | -          |
-| Default Docker image                  | `ruby:2.5`                                        | -          |
-| `privileged` (run [Docker in Docker](https://hub.docker.com/_/docker/)) | `true`          | `false`    |
+## SaaS runners for GitLab projects
 
-These runners share a [distributed cache](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) through use of a Google Cloud Storage (GCS) bucket. Cache contents not updated within the last 14 days are automatically removed through use of an [object lifecycle management policy](https://cloud.google.com/storage/docs/lifecycle).
+The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated for
+GitLab projects and related community forks. These runners are backed by a Google Compute
+`n1-standard-2` machine type and do not run untagged jobs. Unlike the machine types used
+for private projects, each virtual machine is re-used up to 40 times.
+
+## SaaS runners on Linux settings
+
+Below are the settings for SaaS runners on Linux.
+
+| Setting                                                                 | GitLab.com       | Default |
+|-------------------------------------------------------------------------|------------------|---------|
+| Executor                                                                | `docker+machine` | -       |
+| Default Docker image                                                    | `ruby:2.5`       | -       |
+| `privileged` (run [Docker in Docker](https://hub.docker.com/_/docker/)) | `true`           | `false` |
+
+- **Cache**: These runners share a
+  [distributed cache](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching)
+  that's stored in a Google Cloud Storage (GCS) bucket. Cache contents not updated within
+  the last 14 days are automatically removed, based on the
+  [object lifecycle management policy](https://cloud.google.com/storage/docs/lifecycle).
+
+- **Timeout settings**: Jobs handled by the SaaS Runners on Linux
+  **time out after 3 hours**, regardless of the timeout configured in a
+  project. For details, see issues [#4010](https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues/4010)
+  and [#4070](https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues/4070).
+
+NOTE:
+The final disk space your jobs can use will be less than 25GB. Some disk space
+allocated to the instance will be occupied by the operating system, the Docker image,
+and a copy of your cloned repository.
 
 ## Pre-clone script
 
-With SaaS runners on Linux, you can run commands in a CI
+With SaaS runners on Linux, you can run commands in a CI/CD
 job before the runner attempts to run `git init` and `git fetch` to
 download a GitLab repository. The
 [`pre_clone_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section)
@@ -55,12 +109,13 @@ To use this feature, define a [CI/CD variable](../../../ci/variables/index.md#cu
 `CI_PRE_CLONE_SCRIPT` that contains a bash script.
 
 NOTE:
-The `CI_PRE_CLONE_SCRIPT` variable does not work on GitLab SaaS Windows or macOS Runners.
+The `CI_PRE_CLONE_SCRIPT` variable does not work on GitLab SaaS Windows or macOS runners.
 
 ### Pre-clone script example
 
 This example was used in the `gitlab-org/gitlab` project until November 2021.
-The project no longer uses this optimization because the [pack-objects cache](../../../administration/gitaly/configure_gitaly.md#pack-objects-cache)
+The project no longer uses this optimization because the
+[pack-objects cache](../../../administration/gitaly/configure_gitaly.md#pack-objects-cache)
 lets Gitaly serve the full CI/CD fetch traffic. See [Git fetch caching](../../../development/pipelines.md#git-fetch-caching).
 
 The `CI_PRE_CLONE_SCRIPT` was defined as a project CI/CD variable: