Add latest changes from gitlab-org/gitlab@14-2-stable-eev14.2.0-rc42

7 files changed, 133 insertions, 24 deletions

diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md
index 5ab8653dc35..0e6c2f63f9e 100644
--- a/doc/ci/runners/README.md
+++ b/doc/ci/runners/README.md
@@ -1,5 +1,6 @@
 ---
 redirect_to: 'index.md'
+remove_date: '2021-09-28'
 ---
 
 This document was moved to [another location](index.md).
diff --git a/doc/ci/runners/build_cloud/linux_build_cloud.md b/doc/ci/runners/build_cloud/linux_build_cloud.md
index 710054921ef..1125d8dbcb4 100644
--- a/doc/ci/runners/build_cloud/linux_build_cloud.md
+++ b/doc/ci/runners/build_cloud/linux_build_cloud.md
@@ -4,11 +4,11 @@ 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
 ---
 
-# Linux shared runners
+# Build Cloud runners for Linux
 
-Linux shared runners on GitLab.com run in autoscale mode and are powered by Google Cloud Platform.
+GitLab Build Cloud runners for Linux run in autoscale mode and are powered by Google Cloud Platform.
 
-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 for users and customers on GitLab.com.
+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.
 
 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.
 
@@ -23,7 +23,7 @@ Jobs handled by the shared runners on GitLab.com (`shared-runners-manager-X.gitl
 **time out after 3 hours**, regardless of the timeout configured in a
 project. Check the issues [4010](https://gitlab.com/gitlab-com/infrastructure/-/issues/4010) and [4070](https://gitlab.com/gitlab-com/infrastructure/-/issues/4070) for the reference.
 
-Below are the shared runners settings.
+Below are the runners' settings.
 
 | Setting                               | GitLab.com                                        | Default    |
 | -----------                           | -----------------                                 | ---------- |
@@ -33,7 +33,7 @@ Below are the shared runners settings.
 
 ## Pre-clone script
 
-Linux shared runners on GitLab.com provide a way to run commands in a CI
+Build Cloud runners for Linux provide a way to run commands in a CI
 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)
diff --git a/doc/ci/runners/build_cloud/macos/environment.md b/doc/ci/runners/build_cloud/macos/environment.md
new file mode 100644
index 00000000000..e84b7d0a207
--- /dev/null
+++ b/doc/ci/runners/build_cloud/macos/environment.md
@@ -0,0 +1,43 @@
+---
+stage: Verify
+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
+---
+
+# VM instances and images for Build Cloud for macOS 
+
+When you use the Build Cloud for macOS:
+
+- Each of your jobs runs in a newly provisioned VM, which is dedicated to the specific job. 
+- The VM is active only for the duration of the job and immediately deleted. 
+
+## VM types
+
+The virtual machine where your job runs has `sudo` access with no password.
+For the Beta, there is only one available machine type, `gbc-macos-large`.
+
+| Instance type | vCPUS | Memory (GB) |
+| --------- | --- | ------- |
+|  `gbc-macos-large` | 4 | 10 |
+
+## VM images
+
+You can execute your build on one of the following images.
+You specify this image in your `.gitlab-ci.yml` file.
+
+Each image is running a specific version of macOS and Xcode.
+
+| VM image                  | Included software  |
+|---------------------------|--------------------|
+| macos-10.13-xcode-7       | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/high-sierra.yml>  |
+| macos-10.13-xcode-8       | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/high-sierra.yml>  |
+| macos-10.13-xcode-9       | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/high-sierra.yml>  |
+| macos-10.14-xcode-10      | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/mojave.yml>       |
+| macos-10.15-xcode-11      | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/catalina.yml>     |
+| macos-11-xcode-12         | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/big-sur.yml>      |
+
+### Image update policy
+
+- Support for new macOS versions is planned.
+- Additional details on the support policy and image update release process are documented
+  [in this project](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/55bf59c8fa88712960afff2bf6ecc5daa879a8f5/docs/overview.md#os-images).
diff --git a/doc/ci/runners/build_cloud/macos_build_cloud.md b/doc/ci/runners/build_cloud/macos_build_cloud.md
new file mode 100644
index 00000000000..1400c7e08db
--- /dev/null
+++ b/doc/ci/runners/build_cloud/macos_build_cloud.md
@@ -0,0 +1,62 @@
+---
+stage: Verify
+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
+---
+
+# Build Cloud runners for macOS (Beta)
+
+The GitLab Build Cloud for macOS Beta provides on-demand runners integrated with GitLab SaaS [CI/CD](../../../ci/index.md).
+Use these runners to build, test, and deploy apps for the Apple ecosystem (macOS, iOS, tvOS). You can take advantage
+of all the capabilities of the GitLab single DevOps platform and not have to manage or operate a
+build environment.
+
+Build Cloud runners for macOS are in [Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta)
+and shouldn't be relied upon for mission-critical production jobs. 
+
+## Quickstart
+
+To start using Build Cloud for macOS Beta, you must submit an access request issue. After your
+access has been granted and your build environment configured, you must configure your
+`.gitlab-ci.yml` pipeline file:
+
+1. Add a `.gitlab-ci.yml` file to your project repository.
+1. Specify the [image](macos/environment.md#vm-images) you want to use.
+1. Commit a change to your repository.
+
+The runners automatically run your build.
+
+## Example `.gitlab-ci.yml` file
+
+The following sample `.gitlab-ci.yml` file shows how to start using the runners for macOS:
+
+```yaml
+.macos_buildcloud_runners:
+  tags:
+    - shared-macos-amd64
+  image: macos-11-xcode-12
+
+stages:
+  - build
+  - test
+
+before_script:
+ - echo "started by ${GITLAB_USER_NAME}"
+
+build:
+  extends:
+    - .macos_buildcloud_runners
+  stage: build
+  script:
+    - echo "running scripts in the build job"
+
+test:
+  extends:
+    - .macos_buildcloud_runners
+  stage: test
+  script:
+    - echo "running scripts in the test job"
+```
+
+NOTE:
+During the Beta period, the architecture of this solution will change. Rather than the jobs running on a specific VM instance, they will run on an ephemeral VM instance that is created by an autoscaling instance, known as the Runner Manager. We will notify all Beta participants of any downtime required to do this work.
diff --git a/doc/ci/runners/build_cloud/windows_build_cloud.md b/doc/ci/runners/build_cloud/windows_build_cloud.md
index 5a85f28e4b9..0004041a3e8 100644
--- a/doc/ci/runners/build_cloud/windows_build_cloud.md
+++ b/doc/ci/runners/build_cloud/windows_build_cloud.md
@@ -4,24 +4,24 @@ 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
 ---
 
-# Windows shared runners (beta)
+# Build Cloud runners for Windows (beta)
 
-The Windows shared runners are in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta)
+GitLab Build Cloud runners for Windows are in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta)
 and shouldn't be used for production workloads.
 
 During this beta period, the [shared runner pipeline quota](../../../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota)
 applies for groups and projects in the same manner as Linux runners. This may
 change when the beta period ends, as discussed in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30834).
 
-Windows shared runners on GitLab.com autoscale by launching virtual machines on
+Windows runners on GitLab.com autoscale by launching virtual machines on
 the Google Cloud Platform. This solution uses an
 [autoscaling driver](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/tree/master/docs/readme.md)
 developed by GitLab for the [custom executor](https://docs.gitlab.com/runner/executors/custom.html).
-Windows shared runners execute your CI/CD jobs on `n1-standard-2` instances with
+Windows runners execute your CI/CD jobs on `n1-standard-2` instances with
 2 vCPUs and 7.5 GB RAM. You can find a full list of available Windows packages in
 the [package documentation](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/master/cookbooks/preinstalled-software/README.md).
 
-We want to keep iterating to get Windows shared runners in a stable state and
+We want to keep iterating to get Windows runners in a stable state and
 [generally available](https://about.gitlab.com/handbook/product/gitlab-the-product/#generally-available-ga).
 You can follow our work towards this goal in the
 [related epic](https://gitlab.com/groups/gitlab-org/-/epics/2162).
@@ -89,10 +89,9 @@ VMTag = "windows"
   Directory = "C:\\GitLab-Runner\\autoscaler\\machines"
 ```
 
-## Example
+## Example `.gitlab-ci.yml` file
 
-Below is a simple `.gitlab-ci.yml` file to show how to start using the
-Windows shared runners:
+Below is a sample `.gitlab-ci.yml` file that shows how to start using the runners for Windows:
 
 ```yaml
 .shared_windows_runners:
@@ -131,14 +130,14 @@ test:
   definition](https://about.gitlab.com/handbook/product/#beta).
 - The average provisioning time for a new Windows VM is 5 minutes.
   This means that you may notice slower build start times
-  on the Windows shared runner fleet during the beta. In a future
+  on the Windows runner fleet during the beta. In a future
   release we intend to update the autoscaler to enable
   the pre-provisioning of virtual machines. This is intended to significantly reduce
   the time it takes to provision a VM on the Windows fleet. You can
   follow along in the [related issue](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/-/issues/32).
-- The Windows shared runner fleet may be unavailable occasionally
+- The Windows runner fleet may be unavailable occasionally
   for maintenance or updates.
-- The Windows shared runner virtual machine instances do not use the
+- The Windows runner virtual machine instances do not use the
   GitLab Docker executor. This means that you can't specify
   [`image`](../../../ci/yaml/index.md#image) or [`services`](../../../ci/yaml/index.md#services) in
   your pipeline configuration.
@@ -150,7 +149,7 @@ test:
   installation of additional software packages needs to be repeated for
   each job in your pipeline.
 - The job may stay in a pending state for longer than the
-  Linux shared runners.
+  Linux runners.
 - There is the possibility that we introduce breaking changes which will
-  require updates to pipelines that are using the Windows shared runner
+  require updates to pipelines that are using the Windows runner
   fleet.
diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md
index da7289a0ebd..6642913a9d8 100644
--- a/doc/ci/runners/index.md
+++ b/doc/ci/runners/index.md
@@ -5,14 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 type: reference
 ---
 
-# GitLab SaaS runners
+# GitLab Build Cloud runners
 
 If you are using self-managed GitLab or you want to use your own runners on GitLab.com, you can
 [install and configure your own runners](https://docs.gitlab.com/runner/install/).
 
-If you are using GitLab SaaS (GitLab.com), your CI jobs automatically run on shared runners. No configuration is required.
-Your jobs can run on [Linux](build_cloud/linux_build_cloud.md) or [Windows](build_cloud/windows_build_cloud.md).
+If you are using GitLab SaaS (GitLab.com), your CI jobs automatically run on runners in the GitLab Build Cloud.
+No configuration is required. Your jobs can run on:
 
-The number of minutes you can use on these shared runners depends on your
+- [Linux runners](build_cloud/linux_build_cloud.md).
+- [Windows runners](build_cloud/windows_build_cloud.md) (beta).
+- [macOS runners](build_cloud/macos_build_cloud.md) (beta).
+
+The number of minutes you can use on these runners depends on your
 [quota](../../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota),
 which depends on your [subscription plan](../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes).
diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md
index fa56be3a151..2af373384d2 100644
--- a/doc/ci/runners/runners_scope.md
+++ b/doc/ci/runners/runners_scope.md
@@ -33,13 +33,13 @@ If you are using a self-managed instance of GitLab:
 
 If you are using GitLab.com:
 
-- You can select from a list of [shared runners that GitLab maintains](../../user/gitlab_com/index.md#shared-runners).
+- You can select from a list of [shared runners that GitLab maintains](index.md).
 - The shared runners consume the [pipelines minutes](../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes)
   included with your account.
 
 ### Enable shared runners
 
-On GitLab.com, [shared runners](#shared-runners) are enabled in all projects by
+On GitLab.com, [shared runners](index.md) are enabled in all projects by
 default.
 
 On self-managed instances of GitLab, an administrator must [install](https://docs.gitlab.com/runner/install/index.html)