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, or their group membership, or a combination of these.
-
You can provide
runs-on
as:- A single string
- A single variable containing a string
- An array of strings, variables containing strings, or a combination of both
- A
key: value
pair using thegroup
orlabels
keys
-
If you specify an array of strings or variables, your workflow will execute on any runner that matches all of the specified
runs-on
values. For example, here the job will only run on a self-hosted runner that has the labelslinux
,x64
, andgpu
:runs-on: [self-hosted, linux, x64, gpu]
For more information, see "Choosing self-hosted runners."
-
You can mix strings and variables in an array. For example:
on: workflow_dispatch: inputs: chosen-os: required: true type: choice options: - Ubuntu - macOS jobs: test: runs-on: [self-hosted, "${{ inputs.chosen-os }}"] steps: - run: echo Hello world!
-
If you would like to run your workflow on multiple machines, use
jobs.<job_id>.strategy
.
Note: Quotation marks are not required around simple strings like self-hosted
, but they are required for expressions like "${{ inputs.chosen-os }}"
.
Choosing GitHub-hosted runners
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 self-hosted runners
To specify a self-hosted runner for your job, configure runs-on
in your workflow file with self-hosted runner labels.
Self-hosted runners may have the self-hosted
label. When setting up a self-hosted runner, by default we will include the label self-hosted
. You may pass in the --no-default-labels
flag to prevent the self-hosted label from being applied. Labels can be used to create targeting options for runners, 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.
Note that Action-runner-controller does not support multiple labels and does not support the self-hosted
label.
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."
Choosing runners in a group
You can use runs-on
to target runner groups, so that the job will execute on any runner that is a member of that group. For more granular control, you can also combine runner groups with labels.
Example: Using groups to control where jobs are run
In this example, Ubuntu runners have been added to a group called ubuntu-runners
. The runs-on
key sends the job to any available runner in the ubuntu-runners
group:
name: learn-github-actions
on: [push]
jobs:
check-bats-version:
runs-on:
group: ubuntu-runners
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '14'
- run: npm install -g bats
- run: bats -v
Example: Combining groups and labels
When you combine groups and labels, the runner must meet both requirements to be eligible to run the job.
In this example, a runner group called ubuntu-runners
is populated with Ubuntu runners, which have also been assigned the label ubuntu-20.04-16core
. The runs-on
key combines group
and labels
so that the job is routed to any available runner within the group that also has a matching label:
name: learn-github-actions
on: [push]
jobs:
check-bats-version:
runs-on:
group: ubuntu-runners
labels: ubuntu-20.04-16core
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '14'
- run: npm install -g bats
- run: bats -v
Example: using prefixes to differentiate runner groups
For example, if you have a runner group named my-group
in the organization and another named my-group
in the enterprise, you can update your workflow file to use org/my-group
or ent/my-group
to differentiate between the two.
Using org/
:
runs-on:
group: org/my-group
labels: [ self-hosted, label-1 ]
Using ent/
:
runs-on:
group: ent/my-group
labels: [ self-hosted, label-1 ]