LLVM GitHub Actions Runners#

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:

- 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:

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