•  


Using self-hosted runners in a workflow - GitHub Docs
Skip to main content

Using self-hosted runners in a workflow

To use self-hosted runners in a workflow, you can use labels or groups to specify the runner for a job.

You can target self-hosted runners for use in a workflow based on the labels assigned to the runners, or their group membership, or a combination of these.

Note

Action Runner Controller does not support multiple labels, only the name of the runner can be used in place of a label

About self-hosted runner labels

Labels allow you to send workflow jobs to specific types of self-hosted runners, based on their shared characteristics. For example, if your job requires a particular hardware component or software package, you can assign a custom label to a runner and then configure your job to only execute on runners with that label.

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.

For information on creating custom and default labels, see " Using labels with self-hosted runners ."

About self-hosted runner groups

For self-hosted runners defined at the organization level, you can group your runners with shared characteristics into a single runner group and then configure your job to target the runner group.

To specify a self-hosted runner group for your job, configure runs-on.group in your workflow file.

For information on creating and managing runner groups, see " Managing access to self-hosted runners using groups ."

Viewing available runners for a repository

If you have repo: write access to a repository, you can view a list of the runners available to the repository.

  1. On GitHub.com, navigate to the main page of the repository.

  2. Under your repository name, click Actions .

    Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.

  3. In the left sidebar, under the "Management" section, click Runners .

  4. Click the Self hosted tab at the top of the list of runners.

  5. Review the list of available self-hosted runners for the repository. This list includes both self-hosted runners and runner scale sets created with Actions Runner Controller. For more information, see " About Actions Runner Controller ."

  6. Optionally, to copy a runner's label to use it in a workflow, click to the right of the runner, then click Copy label .

Note: Enterprise and organization owners can create runners from this page. To create a new runner, click New runner at the top right of the list of runners to add runners to the repository.

For more information, see " Managing larger runners " and " Adding self-hosted runners ."

Using default labels to route jobs

A self-hosted runner automatically receives certain labels when it is added to GitHub Actions. These are used to indicate its operating system and hardware platform:

  • self-hosted : Default label applied to self-hosted runners.
  • linux , windows , or macOS : Applied depending on operating system.
  • x64 , ARM , or ARM64 : Applied depending on hardware architecture.

You can use your workflow's YAML to send jobs to a combination of these labels. In this example, a self-hosted runner that matches all three labels will be eligible to run the job:

runs-on:
 [
self-hosted
, 
linux
, 
ARM64
]
  • self-hosted - Run this job on a self-hosted runner.
  • linux - Only use a Linux-based runner.
  • ARM64 - Only use a runner based on ARM64 hardware.

To create individual self-hosted runners without the default labels, pass the --no-default-labels flag when you create the runner. Actions Runner Controller does not support multiple labels.

Using custom labels to route jobs

You can create custom labels and assign them to your self-hosted runners at any time. Custom labels let you send jobs to particular types of self-hosted runners, based on how they're labeled.

For example, if you have a job that requires a specific type of graphics hardware, you can create a custom label called gpu and assign it to the runners that have the hardware installed. A self-hosted runner that matches all the assigned labels will then be eligible to run the job.

This example shows a job that combines default and custom labels:

runs-on:
 [
self-hosted
, 
linux
, 
x64
, 
gpu
]
  • self-hosted - Run this job on a self-hosted runner.
  • linux - Only use a Linux-based runner.
  • x64 - Only use a runner based on x64 hardware.
  • gpu - This custom label has been manually assigned to self-hosted runners with the GPU hardware installed.

These labels operate cumulatively, so a self-hosted runner must have all four labels to be eligible to process the job.

Using groups to route jobs

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

Using labels and groups to route jobs

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

Routing precedence for self-hosted runners

When routing a job to a self-hosted runner, GitHub looks for a runner that matches the job's runs-on labels and/or groups:

  • If GitHub finds an online and idle runner that matches the job's runs-on labels and/or groups, the job is then assigned and sent to the runner.
    • If the runner doesn't pick up the assigned job within 60 seconds, the job is re-queued so that a new runner can accept it.
  • If GitHub doesn't find an online and idle runner that matches the job's runs-on labels and/or groups, then the job will remain queued until a runner comes online.
  • If the job remains queued for more than 24 hours, the job will fail.
- "漢字路" 한글한자자동변환 서비스는 교육부 고전문헌국역지원사업의 지원으로 구축되었습니다.
- "漢字路" 한글한자자동변환 서비스는 전통문화연구회 "울산대학교한국어처리연구실 옥철영(IT융합전공)교수팀"에서 개발한 한글한자자동변환기를 바탕하여 지속적으로 공동 연구 개발하고 있는 서비스입니다.
- 현재 고유명사(인명, 지명등)을 비롯한 여러 변환오류가 있으며 이를 해결하고자 많은 연구 개발을 진행하고자 하고 있습니다. 이를 인지하시고 다른 곳에서 인용시 한자 변환 결과를 한번 더 검토하시고 사용해 주시기 바랍니다.
- 변환오류 및 건의,문의사항은 juntong@juntong.or.kr로 메일로 보내주시면 감사하겠습니다. .
Copyright ⓒ 2020 By '전통문화연구회(傳統文化硏究會)' All Rights reserved.
 한국   대만   중국   일본