Using self-hosted runners in a workflow

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.

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.

작업에 대한 자체 호스팅 실행기를 지정하려면 자체 호스팅 실행기 레이블을 사용하여 워크플로 파일에서 runs-on을 구성합니다.

자체 호스트형 실행기에는 self-hosted 레이블이 있을 수 있습니다. 자체 호스트형 실행기를 설정할 때 기본적으로 self-hosted 레이블이 포함됩니다. 자체 호스트형 레이블이 적용되지 않도록 --no-default-labels 플래그를 전달할 수 있습니다. 레이블은 운영 체제 또는 아키텍처와 같은 실행기에 대한 타겟팅 옵션을 만드는 데 사용할 수 있으며, self-hosted로 시작하는 레이블 배열(먼저 나열해야 함)을 제공한 다음 필요에 따라 추가 레이블을 포함하는 것이 좋습니다. 레이블 배열을 지정하면 지정한 모든 레이블이 있는 실행기에서 작업이 큐에 대기됩니다.

작업 실행기 컨트롤러는 다중 레이블을 지원하지 않으며 self-hosted 레이블을 지원하지 않는다는 점에 유의하세요.

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 or enterprise levels, 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.

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

이 예제에서는 Ubuntu 실행기라는 ubuntu-runners 그룹에 추가되었습니다. runs-on 키는 ubuntu-runners 그룹에서 사용 가능한 모든 실행기로 작업을 보냅니다.

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

그룹과 레이블을 결합할 때, 실행기는 작업을 실행할 수 있도록 두 요구 사항을 모두 충족해야 합니다.

이 예제에서 ubuntu-runners 실행기 그룹은 ubuntu-20.04-16core 레이블이 할당된 Ubuntu 실행기로 채워집니다. runs-on 키가 group, labels와 결합되어 작업이 일치하는 레이블이 있는 그룹 내에서 사용 가능한 모든 실행기로 라우팅됩니다.

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

• If GitHub finds an online and idle runner that matches the job's runs-on labels and 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 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.

Workflow run continuity

GitHub Actions 서비스를 일시적으로 사용할 수 없는 경우 트리거된 후 30분 이내에 큐에 대기하지 않으면 워크플로 실행이 삭제됩니다. 예를 들어 워크플로가 트리거되고 GitHub Actions 서비스를 31분 이상 사용할 수 없는 경우 워크플로 실행이 처리되지 않습니다.