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.

Si vous souhaitez spécifier un exécuteur autohébergé pour votre travail, configurez runs-on dans votre fichier de workflow avec des étiquettes d’exécuteur autohébergé.

Les exécuteurs auto-hébergés sont susceptibles d’avoir l’étiquette self-hosted. Lors de la configuration d’un exécuteur auto-hébergé, nous inclurons l’étiquette self-hosted par défaut. Vous pouvez passer l’indicateur --no-default-labels pour empêcher l’application de l’étiquette d’auto-hébergement. Les étiquettes peuvent être utilisées pour créer des options de ciblage pour les exécuteurs, telles que le système d’exploitation ou l’architecture. Nous recommandons de fournir un tableau d’étiquettes qui commence par self-hosted (ceci doit être listé en premier) et inclut ensuite des étiquettes supplémentaires si nécessaire. Quand vous spécifiez un tableau d’étiquettes, les travaux sont mis en file d’attente sur des exécuteurs qui comportent toutes les étiquettes que vous indiquez.

Notez qu’Actions Runner Controller ne prend pas en charge plusieurs étiquettes et ne prend pas en charge l’étiquette 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

Dans cet exemple, des exécuteurs Ubuntu ont été ajoutés à un groupe appelé ubuntu-runners. La clé runs-on envoie le travail à n’importe quel exécuteur disponible dans le groupe 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

Quand vous combinez des groupes et des étiquettes, l’exécuteur doit satisfaire aux deux exigences pour pouvoir exécuter le travail.

Dans cet exemple, un groupe d’exécuteurs appelé ubuntu-runners est rempli avec des exécuteurs Ubuntu, qui ont également reçu l’étiquette ubuntu-20.04-16core. La clé runs-on combine group et labels afin que le travail soit routé vers n’importe quel exécuteur disponible au sein du groupe qui a également une étiquette correspondante :

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

Si les services GitHub Actions sont temporairement indisponibles, alors une exécution de workflow est ignorée si elle n’a pas été mise en file d’attente dans les 30 minutes suivant son déclenchement. Par exemple, si un workflow est déclenché et que les services GitHub Actions ne sont pas disponibles pendant 31 minutes ou plus, l’exécution du workflow n’est pas traitée.