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.

Viewing available runners for a repository

Wenn Sie repo: write Zugriff auf ein Repository haben, können Sie sich eine Liste der Runner anzeigen lassen, die für das Repository verfügbar sind.

  1. Navigieren Sie auf GitHub zur Hauptseite des Repositorys.

  2. Klicke unter dem Namen deines Repositorys auf Aktionen.

    Screenshot: Registerkarten für das Repository „github/docs“. Die Registerkarte „Aktionen“ ist mit einem orangefarbenen Rahmen hervorgehoben.

  3. Klicke auf der linken Randleiste unter dem Abschnitt „Verwaltung“ auf Runner.

  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 Informationen zum Actions Runner Controller.

  6. Wenn Sie optional die Bezeichnung eines Runners kopieren möchten, um sie in einem Workflow zu verwenden, klicken Sie auf rechts neben dem Runner, und klicken Sie dann auf Bezeichnung kopieren.

Hinweis

Enterprise- und Organisationsbesitzer und Benutzer mit der Berechtigung „Organisationsrunner und Runnergruppen verwalten“ können auf dieser Seite Runner erstellen. Um einen neuen Runner zu erstellen, klicken Sie oben rechts in der Liste der Runner auf Neuer Runner, um dem Repository Runner hinzuzufügen.

Weitere Informationen findest du unter Managing larger runners und Adding self-hosted runners. Weitere Informationen zu benutzerdefinierten Organisationsrollen findest du unter Informationen zu benutzerdefinierten Organisationsrollen.

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 diesem Beispiel wurden Ubuntu-Runner zu einer Gruppe namens ubuntu-runners hinzugefügt. Der runs-on-Schlüssel sendet den Auftrag an einen beliebigen verfügbaren Runner in der Gruppe 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

Wenn du Gruppen und Bezeichnungen kombinierst, muss der Runner beide Anforderungen erfüllen, um zum Ausführen des Auftrags berechtigt zu sein.

In diesem Beispiel wird eine Runnergruppe namens ubuntu-runners mit Ubuntu-Runnern aufgefüllt, denen zudem die Bezeichnung ubuntu-20.04-16core zugewiesen wurde. Der runs-on-Schlüssel kombiniert group und labels, sodass der Auftrag an einen beliebigen verfügbaren Runner innerhalb der Gruppe weitergeleitet wird, der auch eine übereinstimmende Bezeichnung aufweist:

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