Add latest changes from gitlab-org/gitlab@master

5 files changed, 89 insertions, 84 deletions

diff --git a/doc/ci/mobile_devops.md b/doc/ci/mobile_devops.md
index ab8fa0c9e6c..9c2777efec2 100644
--- a/doc/ci/mobile_devops.md
+++ b/doc/ci/mobile_devops.md
@@ -43,7 +43,7 @@ test:
 
 [GitLab SaaS runners on macOS](../ci/runners/saas/macos_saas_runner.md) are currently available in beta.
 
-After you are granted access to the beta macOS runners, [choose an image](../ci/runners/saas/macos/environment.md#available-images)
+After you are granted access to the beta macOS runners, [choose an image](../ci/runners/saas/macos_saas_runner.md#supported-macos-images)
 and add it to your `.gitlab-ci.yml` file.
 
 For example:
diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md
index 6883f0727dd..0482fd0912f 100644
--- a/doc/ci/runners/index.md
+++ b/doc/ci/runners/index.md
@@ -18,6 +18,17 @@ The number of minutes you can use on these runners depends on the
 [maximum number of CI/CD minutes](../pipelines/cicd_minutes.md)
 in your [subscription plan](https://about.gitlab.com/pricing/).
 
+## VM instances and images for SaaS runners
+
+When you use SaaS runners:
+
+- 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. This means that any changes that your job makes to the virtual machine will not be available to a subsequent job.
+- The virtual machine where your job runs has `sudo` access with no password.
+
+NOTE:
+Jobs handled by SaaS runners on GitLab.com **time out after 3 hours**, regardless of the timeout configured in a project.
+
 ## Security for GitLab SaaS runners
 
 GitLab SaaS runners on Linux and Windows run on Google Compute Platform. The [Google Infrastructure Security Design Overview whitepaper](https://cloud.google.com/docs/security/infrastructure/design/resources/google_infrastructure_whitepaper_fa.pdf) provides an overview of how Google designs security into its technical infrastructure. The GitLab [Trust Center](https://about.gitlab.com/security/) and [GitLab Security Compliance Controls](https://about.staging.gitlab.com/handbook/engineering/security/security-assurance/security-compliance/sec-controls.html) pages provide an overview of the security and compliance controls that govern the GitLab SaaS runners.
diff --git a/doc/ci/runners/saas/macos/codesigning.md b/doc/ci/runners/saas/macos/codesigning.md
index 809b8faf9df..7e70e984c7c 100644
--- a/doc/ci/runners/saas/macos/codesigning.md
+++ b/doc/ci/runners/saas/macos/codesigning.md
@@ -1,28 +1,11 @@
 ---
-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/product/ux/technical-writing/#assignments
+redirect_to: '../macos_saas_runner.md'
+remove_date: '2023-09-05'
 ---
 
-# Code signing for SaaS runners on macOS
+This document was moved to [another location](../macos_saas_runner.md).
 
-Before you can integrate GitLab with Apple services, install to a device, or deploy to the Apple App Store, you must [code sign](https://developer.apple.com/support/code-signing/) your application.
-
-## Code signing iOS Projects with fastlane
-
-When you use SaaS runners on macOS, each job runs on a VM. Included in each VM is [fastlane](https://fastlane.tools/),
-an open-source solution aimed at simplifying mobile app deployment.
-
-For information about how to set up code signing for your application, see the instructions in the [Mobile DevOps documentation](../../../../ci/mobile_devops.md#code-sign-ios-projects-with-fastlane).
-
-These instructions provide the minimal setup to use fastlane to code sign your application. For more information about using fastlane to handle code signing, see the following resources:
-
-- [fastlane getting started guide](https://docs.fastlane.tools/)
-- [Best practices for integrating with GitLab CI](https://docs.fastlane.tools/best-practices/continuous-integration/gitlab/)
-- [fastlane code signing getting started guide](https://docs.fastlane.tools/codesigning/getting-started/)
-
-## Related topics
-
-- [Apple Developer Support - Code Signing](https://developer.apple.com/support/code-signing/)
-- [Code Signing Best Practice Guide](https://codesigning.guide/)
-- [fastlane authentication with Apple Services guide](https://docs.fastlane.tools/getting-started/ios/authentication/)
+<!-- This redirect file can be deleted after <2023-09-05>. -->
+<!-- Redirects that point to other docs in the same project expire in three months. -->
+<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file
diff --git a/doc/ci/runners/saas/macos/environment.md b/doc/ci/runners/saas/macos/environment.md
index 2fad9bd4af2..7e70e984c7c 100644
--- a/doc/ci/runners/saas/macos/environment.md
+++ b/doc/ci/runners/saas/macos/environment.md
@@ -1,59 +1,11 @@
 ---
-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/product/ux/technical-writing/#assignments
+redirect_to: '../macos_saas_runner.md'
+remove_date: '2023-09-05'
 ---
 
-# VM instances and images for SaaS runners on macOS **(PREMIUM SAAS)**
+This document was moved to [another location](../macos_saas_runner.md).
 
-When you use SaaS runners on 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. This means that any changes that your job makes to the virtual machine will not be available to a subsequent job.
-- The virtual machine where your job runs has `sudo` access with no password.
-
-NOTE:
-Each time you run a job that requires tooling or dependencies not available in the base image, those items must be added to the newly provisioned build VM. That process will likely increase the total job duration.
-
-## VM types
-
-GitLab SaaS provides macOS build machines on Apple silicon (M1) chips.
-At this time there is only one available machine type offered, `saas-macos-medium-m1`. We deprecated Intel x86 runners in favor of Apple silicon. If you need to build for an x86 target, you can use Rosetta 2 to emulate an Intel x86 build environment.
-
-| Instance type | vCPUS | Memory (GB) |
-| --------- | --- | ------- |
-|  `saas-macos-medium-m1` | 6 | 8 |
-
-## VM images
-
-### Image update policy
-
-GitLab expects to release new images based on this cadence:
-
-macOS updates:
-
-- **For new OS versions:** When Apple releases a new macOS version to developers (like macOS `12`), GitLab will plan to release an image based on the OS within the next 30 business days. The image is considered `beta` and the contents of the image (including tool versions) are subject to change until the first patch release (`12.1`). The long-term name will not include `beta` (for example, `macos-12-xcode-13`), so customers are moved automatically out of beta over time. GitLab will try to minimize breaking changes between the first two minor versions but makes no guarantees. Tooling often gets critical bug fixes after the first public release of an OS version.
-
-- **After the first patch release (`12.1`):**
-  - The image moves to `maintenance` mode. The tools GitLab builds into the image with Homebrew and asdf are frozen. GitLab continues making Xcode updates, security updates, and any non-breaking changes deemed necessary.
-  - The image for the previous OS version (`11`) moves to `frozen` mode. GitLab then does only unavoidable changes: security updates, runner version upgrades, and setting the production password.
-
-Both macOS and Xcode follow a yearly release cadence. As time goes on, GitLab increments their versions synchronously (meaning we build macOS 11 with Xcode 12, macOS 12 with Xcode 13, and so on).
-
-### Available 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                  | Status | Included software  |
-|---------------------------|--------|--------------------|
-| `macos-10.13-xcode-8`       | `frozen` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/high-sierra.yml>  |
-| `macos-10.13-xcode-9`       | `frozen` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/high-sierra.yml>  |
-| `macos-10.14-xcode-10`      | `frozen` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/mojave.yml>       |
-| `macos-10.15-xcode-11`      | `frozen` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/catalina.yml>     |
-| `macos-11-xcode-12`         | `frozen` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/big-sur.yml>      |
-| `macos-12-xcode-13`         | `maintenance` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/monterey.yml> |
-| `macos-12-xcode-14`         | `maintenance` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/monterey.yml> |
-| (none, awaiting macOS 13)        | `beta` |       |
+<!-- This redirect file can be deleted after <2023-09-05>. -->
+<!-- Redirects that point to other docs in the same project expire in three months. -->
+<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file
diff --git a/doc/ci/runners/saas/macos_saas_runner.md b/doc/ci/runners/saas/macos_saas_runner.md
index 9908495c9b4..52a5f89d7e7 100644
--- a/doc/ci/runners/saas/macos_saas_runner.md
+++ b/doc/ci/runners/saas/macos_saas_runner.md
@@ -10,11 +10,53 @@ SaaS runners on macOS are in [Beta](../../../policy/alpha-beta-support.md#beta)
 
 SaaS runners on macOS provide an on-demand macOS build environment 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
+Use these runners to build, test, and deploy apps for the Apple ecosystem (macOS, iOS, watchOS, 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. Our [Mobile DevOps solution](../../../ci/mobile_devops.md#ios-build-environments) provides features, documentation, and guidance on building and deploying mobile applications for iOS.
 
-Jobs handled by macOS shared runners on GitLab.com **time out after 3 hours**, regardless of the timeout configured in a project.
+## Machine types available for macOS
+
+GitLab SaaS provides macOS build machines on Apple silicon (M1) chips.
+Intel x86-64 runners were deprecated in favor of Apple silicon. To build for an x86-64 target, use Rosetta 2 to emulate an Intel x86-64 build environment.
+
+| Instance type | vCPUS | Memory (GB) |
+| --------- | --- | ------- |
+|  `saas-macos-medium-m1` | 4 | 8 |
+
+## VM images
+
+In comparison to our SaaS runners on Linux, where you can run any Docker image, 
+GitLab SaaS provides a set of VM images for macOS.
+
+### Supported macOS images
+
+You can execute your build in one of the following images, which you specify
+in your `.gitlab-ci.yml` file.
+
+Each image runs a specific version of macOS and Xcode.
+
+| VM image                  | Status | Included software  |
+|---------------------------|--------|--------------------|
+| `macos-12-xcode-13`       | `maintenance` |  |
+| `macos-12-xcode-14`       | `maintenance` |  |
+| (none, awaiting macOS 13) | `beta` |  |
+
+NOTE:
+Each time you run a job that requires tooling or dependencies not available in the base image, those items must be added to the newly provisioned build VM. That installation process will likely increase the total job duration.
+
+### Image update policy
+
+GitLab expects to release new images based on this cadence:
+
+macOS updates:
+
+- **For new OS versions:** When Apple releases a new macOS version to developers (like macOS `12`), GitLab will plan to release an image based on the OS within the next 30 business days. The image is considered `beta` and the contents of the image (including tool versions) are subject to change until the first patch release (`12.1`). The long-term name will not include `beta` (for example, `macos-12-xcode-13`), so customers are moved automatically out of beta over time. GitLab will try to minimize breaking changes between the first two minor versions but makes no guarantees. Tooling often gets critical bug fixes after the first public release of an OS version.
+
+- **After the first patch release (`12.1`):**
+  - The image moves to `maintenance` mode. The tools GitLab builds into the image with Homebrew and asdf are frozen. GitLab continues making Xcode updates, security updates, and any non-breaking changes deemed necessary.
+  - The image for the previous OS version (`11`) moves to `frozen` mode. GitLab then does only unavoidable changes: security updates, runner version upgrades, and setting the production password.
+
+Both macOS and Xcode follow a yearly release cadence. As time goes on, GitLab increments their versions synchronously (meaning we build macOS 11 with Xcode 12, macOS 12 with Xcode 13, and so on).
 
 ## Quickstart
 
@@ -26,7 +68,7 @@ To start using the SaaS runners on macOS to run your CI jobs, you must configure
 
 1. Add a `.gitlab-ci.yml` file to your project repository.
 1. Specify the tag `saas-macos-medium-m1`.
-1. Specify the [image](macos/environment.md#vm-images) you want to use.
+1. Specify the [image](#supported-macos-images) you want to use.
 1. Commit a change to your repository.
 
 The runners automatically run your build.
@@ -64,7 +106,24 @@ test:
 ```
 
 NOTE:
-You can specify a different Xcode image to run a job. To do so, replace the value for the `image` keyword with the value of the [virtual machine image name](macos/environment.md#vm-images) from the list of available images. The default value is our latest image.
+You can specify a different Xcode image to run a job. To do so, replace the value for the `image` keyword with the value of the [virtual machine image name](#supported-macos-images) from the list of available images. The default value is our latest image.
+
+## Code signing for SaaS runners on macOS
+
+Before you can integrate GitLab with Apple services, install to a device, or deploy to the Apple App Store, you must [code sign](https://developer.apple.com/support/code-signing/) your application.
+
+### Code signing iOS Projects with fastlane
+
+When you use SaaS runners on macOS, each job runs on a VM. Included in each VM is [fastlane](https://fastlane.tools/),
+an open-source solution aimed at simplifying mobile app deployment.
+
+For information about how to set up code signing for your application, see the instructions in the [Mobile DevOps documentation](../../../ci/mobile_devops.md#code-sign-ios-projects-with-fastlane).
+
+### Related topics
+
+- [Apple Developer Support - Code Signing](https://developer.apple.com/support/code-signing/)
+- [Code Signing Best Practice Guide](https://codesigning.guide/)
+- [fastlane authentication with Apple Services guide](https://docs.fastlane.tools/getting-started/ios/authentication/)
 
 ## SaaS runners on macOS service level objective