Skip to main content

This version of GitHub Enterprise was discontinued on 2022-10-12. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Using labels with self-hosted runners

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

Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.

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 settings on your GitHub Enterprise Server instance. 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: You must be a GitHub Enterprise site administrator.

Creating a custom label

  1. Navigate to where your runner is registered:

    • In an organization or repository: navigate to the main page and click Settings.

    • If using an enterprise-level runner:

      1. In the top-right corner of GitHub Enterprise Server, click your profile photo, then click Enterprise settings. "Enterprise settings" in drop-down menu for profile photo on GitHub Enterprise Server
  2. Navigate to the GitHub Actions settings:

    • In an organization or repository:

      1. In the left sidebar, click Actions.
      2. In the left sidebar, under "Actions", click Runners.
    • If using an enterprise-level runner:

      1. In the enterprise sidebar, click Policies. Policies tab in the enterprise account sidebar
      2. Under " Policies", click Actions.
      3. Click the Runners tab.
  3. Locate the list of runners under "Runners".

  4. If your runner is in a group, locate the runner group and click to view the list of runners. List runner group

  5. Locate the runner you want to update, and click to view the label selection menu. This menu displays all the custom labels available to your self-hosted runner. Labels already assigned to your self-hosted runner have a next to them. Change runner label

  6. In the "Filter labels" field, type the name of your new label, and click Create new label. Add runner 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 runner is registered:

    • In an organization or repository: navigate to the main page and click Settings.

    • If using an enterprise-level runner:

      1. In the top-right corner of GitHub Enterprise Server, click your profile photo, then click Enterprise settings. "Enterprise settings" in drop-down menu for profile photo on GitHub Enterprise Server
  2. Navigate to the GitHub Actions settings:

    • In an organization or repository:

      1. In the left sidebar, click Actions.
      2. In the left sidebar, under "Actions", click Runners.
    • If using an enterprise-level runner:

      1. In the enterprise sidebar, click Policies. Policies tab in the enterprise account sidebar
      2. Under " Policies", click Actions.
      3. Click the Runners tab.
  3. Locate the list of runners under "Runners".

  4. If your runner is in a group, locate the runner group and click to view the list of runners. List runner group

  5. Locate the runner you want to update, and click to view the label selection menu. This menu displays all the custom labels available to your self-hosted runner. Labels already assigned to your self-hosted runner have a next to them. Change runner label

  6. Click on a label to assign it to your self-hosted runner.

Removing a custom label from a self-hosted runner

  1. Navigate to where your runner is registered:

    • In an organization or repository: navigate to the main page and click Settings.

    • If using an enterprise-level runner:

      1. In the top-right corner of GitHub Enterprise Server, click your profile photo, then click Enterprise settings. "Enterprise settings" in drop-down menu for profile photo on GitHub Enterprise Server
  2. Navigate to the GitHub Actions settings:

    • In an organization or repository:

      1. In the left sidebar, click Actions.
      2. In the left sidebar, under "Actions", click Runners.
    • If using an enterprise-level runner:

      1. In the enterprise sidebar, click Policies. Policies tab in the enterprise account sidebar
      2. Under " Policies", click Actions.
      3. Click the Runners tab.
  3. Locate the list of runners under "Runners".

  4. If your runner is in a group, locate the runner group and click to view the list of runners. List runner group

  5. Locate the runner you want to update, and click to view the label selection menu. This menu displays all the custom labels available to your self-hosted runner. Labels already assigned to your self-hosted runner have a next to them. Change runner label

  6. Click on the assigned label to remove it from your self-hosted runner. Any unused labels that are not assigned to a runner will be automatically deleted within 24 hours.

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

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