Using labels with self-hosted runners

You can use labels to organize your self-hosted runners based on their characteristics.

In this article

For information on how to use labels to route jobs to specific types of self-hosted runners, see "Using self-hosted runners in a workflow." You can also route jobs to runners in a specific group. For more information, see "Choosing the runner for a job."

A self-hosted runner can be located in either your repository, organization, or enterprise account settings on GitHub. To manage a self-hosted runner, you must have the following permissions, depending on where the self-hosted runner was added:

  • User repository: You must be the repository owner.

  • Organization: You must be an organization owner.

  • Organization repository: You must be an organization owner, or have admin access to the repository.

  • Enterprise account: You must be an enterprise owner.

Note

Actions Runner Controller does not support multiple labels, to find out more please read our Actions Runner Controller documentation

Creating a custom label

You can create custom labels for runners at the repository, organization, and enterprise levels.

Note

Labels are case-insensitive.

Creating a custom label for a repository runner

  1. Navigate to the main page of the repository where your self-hosted runner group is registered.
  2. Click Settings.
  3. In the left sidebar, click Actions, then click Runners.
  4. In the list of runners, click on the name of the runner you'd like to configure.
  5. In the "Labels" section, click .
  6. In the "Find or create a label" field, type the name of your new label and click Create new label. The custom label is created and assigned to the self-hosted runner. Custom labels can be removed from self-hosted runners, but they currently can't be manually deleted. Any unused labels that are not assigned to a runner will be automatically deleted within 24 hours.

Creating a custom label for an organization runner

  1. Navigate to the main page of the organization where your self-hosted runner group is registered.
  2. Click Settings.
  3. In the left sidebar, click Actions, then click Runners.
  4. In the list of runners, click on the name of the runner you'd like to configure.
  5. In the "Labels" section, click .
  6. In the "Find or create a label" field, type the name of your new label and click Create new label. The custom label is created and assigned to the self-hosted runner. Custom labels can be removed from self-hosted runners, but they currently can't be manually deleted. Any unused labels that are not assigned to a runner will be automatically deleted within 24 hours.

Creating a custom label for an enterprise runner

  1. In the top-right corner of GitHub, click your profile photo.
  2. Depending on your environment, click Your enterprise, or click Your enterprises then click the enterprise you want to view.
  3. On the left side of the page, in the enterprise account sidebar, click Policies.
  4. Under " Policies", click Actions.
  5. Click the Runners tab.
  6. In the list of runners, click on the name of the runner you'd like to configure.
  7. In the "Labels" section, click .
  8. In the "Find or create a label" field, type the name of your new label and click Create new label. The custom label is created and assigned to the self-hosted runner. Custom labels can be removed from self-hosted runners, but they currently can't be manually deleted. Any unused labels that are not assigned to a runner will be automatically deleted within 24 hours.

Assigning a label to a self-hosted runner

You can assign labels to self-hosted runners at the repository, organization, and enterprise levels.

Assigning a label to a repository runner

  1. Navigate to the main page of the repository where your self-hosted runner group is registered.
  2. Click Settings.
  3. In the left sidebar, click Actions, then click Runners.
  4. In the "Labels" section, click .
  5. To assign a label to your self-hosted runner, in the "Find or create a label" field, click the label.

Assigning a label to an organization runner

  1. Navigate to the main page of the organization where your self-hosted runner group is registered.
  2. Click Settings.
  3. In the left sidebar, click Actions, then click Runners.
  4. In the "Labels" section, click .
  5. To assign a label to your self-hosted runner, in the "Find or create a label" field, click the label.

Assigning a label to an enterprise runner

  1. In the top-right corner of GitHub, click your profile photo.
  2. Depending on your environment, click Your enterprise, or click Your enterprises then click the enterprise you want to view.
  3. On the left side of the page, in the enterprise account sidebar, click Policies.
  4. Under " Policies", click Actions.
  5. Click the Runners tab.
  6. In the list of runners, click on the name of the runner you'd like to configure.
  7. In the "Labels" section, click .
  8. To assign a label to your self-hosted runner, in the "Find or create a label" field, click the label.

Removing a custom label from a self-hosted runner

You can remove custom labels from self-hosted runners at the repository, organization, and enterprise levels.

Removing a custom label from a repository runner

  1. Navigate to the main page of the repository where your self-hosted runner group is registered.
  2. Click Settings.
  3. In the left sidebar, click Actions, then click Runners.
  4. In the "Labels" section, click .
  5. In the "Find or create a label" field, assigned labels are marked with the icon. Click on a marked label to unassign it from your self-hosted runner.

Removing a custom label from an organization runner

  1. Navigate to the main page of the organization where your self-hosted runner group is registered.
  2. Click Settings.
  3. In the left sidebar, click Actions, then click Runners.
  4. In the "Labels" section, click .
  5. In the "Find or create a label" field, assigned labels are marked with the icon. Click on a marked label to unassign it from your self-hosted runner.

Removing a custom label from an enterprise runner

  1. In the top-right corner of GitHub, click your profile photo.
  2. Depending on your environment, click Your enterprise, or click Your enterprises then click the enterprise you want to view.
  3. On the left side of the page, in the enterprise account sidebar, click Policies.
  4. Under " Policies", click Actions.
  5. Click the Runners tab.
  6. In the list of runners, click on the name of the runner you'd like to configure.
  7. In the "Labels" section, click .
  8. In the "Find or create a label" field, assigned labels are marked with the icon. Click on a marked label to unassign it from your self-hosted runner.

Programmatically assign labels

You can programmatically assign labels to a self-hosted runner after the runner is created, or during its initial configuration.

  • To programmatically assign labels to an existing self-hosted runner, you must use the REST API. For more information, see "REST API endpoints for self-hosted runners."

  • To programmatically assign labels to a self-hosted runner during the initial runner configuration, you can pass label names to the config script using the labels parameter.

    Note

    You cannot use the config script to assign labels to an existing self-hosted runner.

    For example, this command assigns a label named gpu when configuring a new self-hosted runner:

    ./config.sh --url <REPOSITORY_URL> --token <REGISTRATION_TOKEN> --labels gpu

    The label is created if it does not already exist. You can also use this approach to assign the default labels to runners, such as x64 or linux. When default labels are assigned using the configuration script, GitHub Actions accepts them as given and does not validate that the runner is actually using that operating system or architecture.

    You can use comma separation to assign multiple labels. For example:

    ./config.sh --url <REPOSITORY_URL> --token <REGISTRATION_TOKEN> --labels gpu,x64,linux

    Note

    If you replace an existing runner, then you must reassign any custom labels.