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.

本文内容

Viewing available runners for a repository

如果对存储库具有 repo: write 访问权限，则可以查看存储库可用的运行器列表。

  1. 在 GitHub 上，导航到存储库的主页面。

  2. 在存储库名称下，单击 “操作”。

    “github/docs”存储库的选项卡的屏幕截图。 “操作”选项卡以橙色边框突出显示。

  3. 在左侧边栏中的“管理”部分下，单击“ 运行器”。****

  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 关于 Actions Runner Controller.

  6. （可选）要复制运行器标签以在工作流中使用，请单击运行器右侧的 ，然后单击“复制标签”。****

注意

企业和组织所有者以及拥有“管理组织运行器和运行器组”权限的用户可以从此页面创建运行器。 若要创建新的运行器，请单击运行器列表右上角的“新建运行器”****，将运行器添加到存储库。

有关详细信息，请参阅 Managing larger runners 和 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

在此示例中，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 运行器（分配了标签 ubuntu-20.04-16core）进行填充。 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