Using labels with self-hosted runners

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."

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.

Creating a custom label

1. Navigate to where your self-hosted runner is registered:
   • In an organization or repository: navigate to the main page and click Settings.
   • If using an enterprise account: navigate to your enterprise account by visiting https://github.com/enterprises/ENTERPRISE-NAME, replacing ENTERPRISE-NAME with your enterprise account's name. In the enterprise sidebar, Policies.
2. Navigate to the GitHub Actions settings:
   • In an organization or repository: Click Actions in the left sidebar, then click Runners.
   • If using an enterprise account: Click Actions under " Policies", then click the Runners tab.
3. In the list of runners, click the runner you'd like to configure.
4. In the "Labels" section, click .
5. 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

1. Navigate to where your self-hosted runner is registered:
   • In an organization or repository: navigate to the main page and click Settings.
   • If using an enterprise account: navigate to your enterprise account by visiting https://github.com/enterprises/ENTERPRISE-NAME, replacing ENTERPRISE-NAME with your enterprise account's name. In the enterprise sidebar, Policies.
2. Navigate to the GitHub Actions settings:
   • In an organization or repository: Click Actions in the left sidebar, then click Runners.
   • If using an enterprise account: Click Actions under " Policies", then click the Runners tab.
3. In the list of runners, click the runner you'd like to configure.
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.

Removing a custom label from a self-hosted runner

1. Navigate to where your self-hosted runner is registered:
   • In an organization or repository: navigate to the main page and click Settings.
   • If using an enterprise account: navigate to your enterprise account by visiting https://github.com/enterprises/ENTERPRISE-NAME, replacing ENTERPRISE-NAME with your enterprise account's name. In the enterprise sidebar, Policies.
2. Navigate to the GitHub Actions settings:
   • In an organization or repository: Click Actions in the left sidebar, then click Runners.
   • If using an enterprise account: Click Actions under " Policies", then click the Runners tab.
3. In the list of runners, click the runner you'd like to configure.
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.

Using the configuration script to create and assign labels

You can use the configuration script on the self-hosted runner to create and assign custom labels. For example, this command assigns a label named gpu to the self-hosted runner.

./config.sh --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 --labels gpu,x64,linux