Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.
Overview
Use jobs.<job_id>.runs-on
to define the type of machine to run the job on.
-
The destination machine can be a self-hosted runner.
-
You can target runners based on the labels assigned to them.
-
You can provide
runs-on
as a single string or as an array of strings. -
If you specify an array of strings, your workflow will execute on any runner that matches all of the specified
runs-on
values. -
If you would like to run your workflow on multiple machines, use
jobs.<job_id>.strategy
.
Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.
Choosing GitHub-hosted runners
If you use a GitHub-hosted runner, each job runs in a fresh instance of a runner image specified by runs-on
.
Available GitHub-hosted runner types are:
Runner image | YAML workflow label | Notes |
---|---|---|
Windows Server 2022 |
windows-latest or windows-2022
|
The windows-latest label currently uses the Windows Server 2022 runner image.
|
Windows Server 2019 |
windows-2019
|
|
Ubuntu 22.04 |
ubuntu-latest or ubuntu-22.04
|
The ubuntu-latest label currently uses the Ubuntu 22.04 runner image.
|
Ubuntu 20.04 |
ubuntu-20.04
|
|
Ubuntu 18.04 [deprecated] |
ubuntu-18.04
|
Migrate to ubuntu-20.04 or ubuntu-22.04 . For more information, see this GitHub blog post.
|
macOS Monterey 12 |
macos-latest or macos-12
|
The macos-latest label currently uses the macOS 12 runner image.
|
macOS Big Sur 11 |
macos-11
|
|
macOS Catalina 10.15 [deprecated] |
macos-10.15
|
Migrate to macOS-11 or macOS-12 . For more information, see this GitHub blog post.
|
Note: The -latest
runner images are the latest stable images that GitHub provides, and might not be the most recent version of the operating system available from the operating system vendor.
Warning: Beta and Deprecated Images are provided "as-is", "with all faults" and "as available" and are excluded from the service level agreement and warranty. Beta Images may not be covered by customer support.
Example: Specifying an operating system
runs-on: ubuntu-latest
For more information, see "About GitHub-hosted runners."
Choosing self-hosted runners
To specify a self-hosted runner for your job, configure runs-on
in your workflow file with self-hosted runner labels.
All self-hosted runners have the self-hosted
label. Using only this label will select any self-hosted runner. To select runners that meet certain criteria, such as operating system or architecture, we recommend providing an array of labels that begins with self-hosted
(this must be listed first) and then includes additional labels as needed. When you specify an array of labels, jobs will be queued on runners that have all the labels that you specify.
Although the self-hosted
label is not required, we strongly recommend specifying it when using self-hosted runners to ensure that your job does not unintentionally specify any current or future GitHub-hosted runners.
Example: Using labels for runner selection
runs-on: [self-hosted, linux]
For more information, see "About self-hosted runners" and "Using self-hosted runners in a workflow."