[CI] Add documentation for self-hosted runners (#211622)

This patch adds (work in progress) documentation for the various
self-hosted runner groups we have access to in the LLVM monorepo.

Author: ldionne

llvm/docs/CIBestPractices.rst

@@ -15,6 +15,9 @@ GitHub Actions Best Practices
 This section contains information on best practices/guidelines when working on
 LLVM's GitHub actions workflows.
 
+For details on the runner pools these workflows execute on and their
+platform-specific constraints, see :doc:`GitHubActionsRunners`.
+
 Disabling Jobs In Forks
 -----------------------
 

llvm/docs/GitHubActionsRunners.rst

@@ -0,0 +1,105 @@
+===========================
+LLVM GitHub Actions Runners
+===========================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+LLVM's GitHub Actions workflows run on two kinds of runners:
+
+- *GitHub-hosted runners*, which GitHub provisions on demand for each job.
+- *Self-hosted runners*, which are machines provided to the LLVM project and
+  registered with the repository. They are used where GitHub-hosted runners are
+  not sufficient, for example to provide hardware or operating systems that
+  GitHub does not offer, or to provide additional capacity.
+
+Self-hosted runners are organized into sets, and a job selects a set through its
+``runs-on`` labels. Since these machines are shared across the project and are
+available only in limited numbers, workflows that target them should be written
+to use them efficiently and to avoid consuming capacity unnecessarily.
+
+The rest of this document describes the self-hosted runner sets and the
+constraints to keep in mind when writing workflows that target them.
+
+Self-Hosted Linux Runners
+=========================
+
+This section is a work in progress.
+
+Self-Hosted Windows Runners
+===========================
+
+This section is a work in progress.
+
+Self-Hosted macOS Runners
+=========================
+
+Self-hosted runners running macOS arm64 are provided by Apple. These runners can be targeted
+with the following expression ``runs-on: ["self-hosted", "macOS", "apple-runners"]``. Since
+these runners have a limited capacity, please contact the infrastructure team before adding
+new jobs that target these runners.
+
+System Version and Architecture
+-------------------------------
+
+All self-hosted macOS runners run the same version of macOS. However, that version
+is determined by the image used on the runners, which is not controllable from
+the workflow file. These runners will be kept at the latest released (non-beta)
+version of macOS, however jobs running on that infrastructure should not make
+assumptions about the macOS version and should strive to be robust to OS version
+changes.
+
+All the self-hosted macOS runners run on Apple Silicon, however the exact chip
+version can differ from runner to runner. It is not currently possible to target
+a specific chip version.
+
+Minimize Short-Lived Jobs
+-------------------------
+
+The macOS runners are relatively expensive to bring up and tear down. Avoid scheduling
+trivial or short-lived work on these runners. For example, do not spin up a macOS runner
+just to perform a cheap check such as determining whether any relevant files have changed.
+Prefer inexpensive runners instead and only then dispatch a macOS job if testing is actually
+required.
+
+Selecting the Xcode Version
+---------------------------
+
+The macOS runners come with several versions of Xcode installed: the two latest releases of
+Xcode and the latest beta. You can select the version of Xcode by pointing ``DEVELOPER_DIR``
+to it. The toolchain (``clang``, ``xcrun``, the SDKs, and so on) is then taken from that
+Xcode. This can be done in an early step that writes the variable to ``$GITHUB_ENV`` so that
+it applies to all subsequent steps:
+
+.. code-block:: yaml
+
+  - name: Select Xcode
+    run: echo "DEVELOPER_DIR=/Applications/Xcode_26.5.app/Contents/Developer" >> $GITHUB_ENV
+
+No Passwordless ``sudo``
+------------------------
+
+The user that runs jobs on the macOS runners cannot use ``sudo``: there is no passwordless
+sudo, and jobs have no way to supply a password. Any step that requires root privileges will
+therefore fail.
+
+Installing Tools via Homebrew
+-----------------------------
+
+When a job needs a tool that is not already present on the runner, install it with Homebrew.
+Homebrew installs into a prefix owned by the runner account, so it does not require ``sudo``,
+and it provides self-contained tools. Also make sure you update Homebrew before installing.
+For example:
+
+.. code-block:: yaml
+
+  - name: Install dependencies
+    run: |
+      brew update
+      brew install ninja cmake
+
+Version-specific formulae (for example ``python@3.12``) can be used when a job
+needs a particular version of a tool.

llvm/docs/Reference.md

@@ -49,6 +49,7 @@ ConvergenceAndUniformity
 MLGO
 ContentAddressableStorage
 CIBestPractices
+GitHubActionsRunners
 AIToolPolicy
 CallGraphSection
 InterfaceExportAnnotations
@@ -234,3 +235,7 @@ XRayFDRFormat
 {doc}`CIBestPractices`
 :   A list of guidelines and best practices to use when working on LLVM's
     CI systems.
+
+{doc}`GitHubActionsRunners`
+:   A reference for LLVM's GitHub Actions runner pools and their
+    platform-specific constraints.