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
- a single variable containing a string
- an array of strings, variables containing strings, or a combination of both
- a
key: value
pair using thegroup
orlabel
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 }}"
.
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."