Merge branch 'docs-runner-buildcloud-macos' into 'master'

Added beta content for macOS

See merge request gitlab-org/gitlab!66290

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)

doc/ci/runners/build_cloud/macos/environment.md

+---
+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).

doc/ci/runners/build_cloud/macos_build_cloud.md

+---
+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)
+
+Build Cloud for macOS Beta provides on-demand GitLab Runners integrated with GitLab SaaS [CI/CD](../../../ci/index.md)
+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. 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.

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.

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).

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)

doc/development/architecture.md

@@ -536,7 +536,7 @@ You can use it either for personal or business websites, such as portfolios, doc
   - [Source](https://docs.gitlab.com/runner/)
   - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/runner.md)
 - Layer: Core Service (Processor)
-- GitLab.com: [Runner](../user/gitlab_com/index.md#shared-runners)
+- GitLab.com: [Runners](../ci/runners/index.md)
 
 GitLab Runner runs jobs and sends the results to GitLab.
 

doc/install/requirements.md

@@ -296,10 +296,10 @@ The GitLab Runner server requirements depend on:
 
 Since the nature of the jobs varies for each use case, you need to experiment by adjusting the job concurrency to get the optimum setting.
 
-For reference, GitLab.com's [auto-scaling shared runner](../user/gitlab_com/index.md#shared-runners) is configured so that a **single job** runs in a **single instance** with:
+For reference, the GitLab.com Build Cloud [auto-scaling runner for Linux](../ci/runners/build_cloud/linux_build_cloud.md) is configured so that a **single job** runs in a **single instance** with:
 
-- 1vCPU.
-- 3.75GB of RAM.
+- 1 vCPU.
+- 3.75 GB of RAM.
 
 ## Supported web browsers
 

doc/user/gitlab_com/index.md

@@ -177,11 +177,11 @@ The following limits apply for [Webhooks](../project/integrations/webhooks.md):
 | [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks) | `100` per project, `50` per group | `100` per project, `50` per group |
 | Maximum payload size | 25 MB       | 25 MB   |
 
-## Shared runners
+## Shared Build Cloud runners
 
 GitLab has shared runners on GitLab.com that you can use to run your CI jobs.
 
-For more information, see [choosing a runner](../../ci/runners/index.md).
+For more information, see [GitLab Build Cloud runners](../../ci/runners/index.md).
 
 ## Sidekiq
 

doc/user/project/clusters/cluster_access.md

@@ -83,6 +83,4 @@ arbitrary images as they effectively have root access.
 If you don't want to use a runner in privileged mode, either:
 
 - Use shared runners on GitLab.com. They don't have this security issue.
-- Set up your own runners using the configuration described at
-[shared runners](../../gitlab_com/index.md#shared-runners) using
-[`docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html).
+- Set up your own runners that use [`docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html).