[2026-03-19] Multi-Label Support for Actions Runner Controller (ARC) [GA] (#60102)

sophietheking · Copilot · subatoi · web-flow · commit cc3a8c6a9469 · 2026-03-19T07:33:54.000Z
Co-authored-by: Copilot Autofix powered by AI &lt;175728472+Copilot@users.noreply.github.com&gt;
Co-authored-by: Ben Ahmady &lt;32935794+subatoi@users.noreply.github.com&gt;
diff --git a/content/actions/concepts/runners/actions-runner-controller.md b/content/actions/concepts/runners/actions-runner-controller.md
@@ -26,10 +26,10 @@ The following diagram illustrates the architecture of ARC's autoscaling runner s
 
 <!-- The numbers in the ordered list below correspond to numbers in the above diagram, which is why we use explicit numbering here. -->
 
-1. {% data variables.product.prodname_actions_runner_controller %} is installed using the supplied Helm charts, and the controller manager pod is deployed in the specified namespace. A new AutoScalingRunnerSet resource is deployed via the supplied Helm charts or a customized manifest file. The AutoScalingRunnerSet Controller calls GitHub's APIs to fetch the runner group ID that the runner scale set will belong to.
-1. The AutoScalingRunnerSet Controller calls the APIs one more time to either fetch or create a runner scale set in the {% data variables.product.prodname_actions %} service before creating the Runner ScaleSet Listener resource.
+1. {% data variables.product.prodname_actions_runner_controller %} is installed using the supplied Helm charts, and the controller manager pod is deployed in the specified namespace. A new AutoScalingRunnerSet resource is deployed via the supplied Helm charts or a customized manifest file. The AutoScalingRunnerSet Controller calls the {% data variables.product.github %}'s API to fetch the runner group ID that the runner scale set will belong to.
+1. The AutoScalingRunnerSet Controller calls the API one more time to either fetch or create a runner scale set in the {% data variables.product.prodname_actions %} service before creating the Runner ScaleSet Listener resource.
 1. A Runner ScaleSet Listener pod is deployed by the AutoScalingListener Controller. In this pod, the listener application connects to the {% data variables.product.prodname_actions %} Service to authenticate and establish an HTTPS long poll connection. The listener stays idle until it receives a `Job Available` message from the {% data variables.product.prodname_actions %} Service.
-1. When a workflow run is triggered from a repository, the {% data variables.product.prodname_actions %} Service dispatches individual job runs to the runners or runner scale sets where the `runs-on` key matches the name of the runner scale set or labels of self-hosted runners.
+1. When a workflow run is triggered from a repository, the {% data variables.product.prodname_actions %} Service dispatches individual job runs to the runners or runner scale sets where the `runs-on` key matches the name of a runner scale set or the labels of a runner scale set or self-hosted runner.
 1. When the Runner ScaleSet Listener receives the `Job Available` message, it checks whether it can scale up to the desired count. If it can, the Runner ScaleSet Listener acknowledges the message.
 1. The Runner ScaleSet Listener uses a Service Account and a Role bound to that account to make an HTTPS call through the Kubernetes APIs to patch the Ephemeral RunnerSet resource with the number of desired replicas count.
 1. The Ephemeral RunnerSet attempts to create new runners and the EphemeralRunner Controller requests a Just-in-Time (JIT) configuration token to register these runners. The controller attempts to create runner pods. If the pod's status is `failed`, the controller retries up to 5 times. After 24 hours the {% data variables.product.prodname_actions %} Service unassigns the job if no runner accepts it.
@@ -71,7 +71,7 @@ Each resource that is deployed by ARC is given a name composed of:
 |-------|---------------|------|-----------------|-------------|-------|
 | `autoscalingrunnerset.yaml` | AutoscalingRunnerSet | INSTALLATION_NAME | 0 | Top level resource working with scale sets | The name is limited to 45 characters in length. |
 | `no_permission_service_account.yaml` | ServiceAccount | INSTALLATION_NAME-gha-rs-no-permission | 21 | Service account mounted to the runner container | This is created if the container mode is not "kubernetes" and `template.spec.serviceAccountName` is not specified. |
-| `githubsecret.yaml` | Secret | INSTALLATION_NAME-gha-rs-github-secret | 20 | Secret containing values needed to authenticate to the GitHub API | This is created if `githubConfigSecret` is an object. If a string is provided, this secret will not be created. |
+| `githubsecret.yaml` | Secret | INSTALLATION_NAME-gha-rs-github-secret | 20 | Secret containing values needed to authenticate to the {% data variables.product.github %} API | This is created if `githubConfigSecret` is an object. If a string is provided, this secret will not be created. |
 | `manager_role.yaml` | Role | INSTALLATION_NAME-gha-rs-manager | 15 | Role provided to the manager to be able to reconcile on resources in the autoscaling runner set's namespace  | This is always created. |
 | `manager_role_binding.yaml` | RoleBinding | INSTALLATION_NAME-gha-rs-manager | 15 | Binding manager_role to the manager service account.  | This is always created. |
 | `kube_mode_role.yaml` | Role | INSTALLATION_NAME-gha-rs-kube-mode | 17 | Role providing necessary permissions for the hook  | This is created when the container mode is set to "kubernetes" and `template.spec.serviceAccount` is not provided. |
@@ -176,6 +176,8 @@ The supported runner image is released as a separate container image, which you
 
 ## Next steps
 
+If you're new to ARC, see [AUTOTITLE](/actions/tutorials/use-actions-runner-controller/get-started) to try out the basics.
+
 When you're ready to use ARC to execute workflows, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow).
 
 {% data reusables.actions.actions-runner-controller-labels %} See [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow).
diff --git a/content/actions/how-tos/manage-runners/index.md b/content/actions/how-tos/manage-runners/index.md
@@ -9,6 +9,7 @@ children:
   - /github-hosted-runners
   - /self-hosted-runners
   - /larger-runners
+  - /use-actions-runner-controller
   - /use-proxy-servers
 contentType: how-tos
 ---
diff --git a/content/actions/how-tos/manage-runners/self-hosted-runners/apply-labels.md b/content/actions/how-tos/manage-runners/self-hosted-runners/apply-labels.md
@@ -22,9 +22,6 @@ For information on how to use labels to route jobs to specific types of self-hos
 
 {% data reusables.actions.self-hosted-runner-management-permissions-required %}
 
-> [!NOTE]
-> Actions Runner Controller does not support multiple labels, to find out more please read our [Actions Runner Controller documentation](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller#using-arc-runners-in-a-workflow)
-
 ## Creating a custom label
 
 You can create custom labels for runners at the repository{% ifversion ghec or ghes %}, organization, and enterprise{% else %} and organization{% endif %} levels.
diff --git a/content/actions/how-tos/manage-runners/self-hosted-runners/use-in-a-workflow.md b/content/actions/how-tos/manage-runners/self-hosted-runners/use-in-a-workflow.md
@@ -55,7 +55,7 @@ runs-on: [self-hosted, linux, ARM64]
 * `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.
+To create individual self-hosted runners without the default labels, pass the `--no-default-labels` flag when you create the runner.
 
 ## Using custom labels to route jobs
 
diff --git a/content/actions/how-tos/manage-runners/use-actions-runner-controller/authenticate-to-the-api.md b/content/actions/how-tos/manage-runners/use-actions-runner-controller/authenticate-to-the-api.md
@@ -1,7 +1,7 @@
 ---
 title: Authenticating ARC to the GitHub API
 shortTitle: Authenticate to the API
-intro: Learn how to authenticate {% data variables.product.prodname_actions_runner_controller %} to the {% data variables.product.company_short %} API.
+intro: Authenticate {% data variables.product.prodname_actions_runner_controller %} to the {% data variables.product.company_short %} API.
 versions:
   fpt: '*'
   ghec: '*'
@@ -11,9 +11,8 @@ redirect_from:
   - /actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api
   - /actions/how-tos/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api#deploying-using-personal-access-token-classic-authentication
   - /actions/tutorials/actions-runner-controller/authenticating-arc-to-the-github-api
-contentType: tutorials
-category:
-  - Use and manage runners
+  - /actions/tutorials/use-actions-runner-controller/authenticate-to-the-api
+contentType: how-tos
 ---
 
 You can authenticate {% data variables.product.prodname_actions_runner_controller %} (ARC) to the {% data variables.product.prodname_dotcom %} API by using a {% data variables.product.prodname_github_app %} or by using a {% data variables.product.pat_v1 %}.
diff --git a/content/actions/how-tos/manage-runners/use-actions-runner-controller/deploy-runner-scale-sets.md b/content/actions/how-tos/manage-runners/use-actions-runner-controller/deploy-runner-scale-sets.md
@@ -1,7 +1,7 @@
 ---
 title: Deploying runner scale sets with Actions Runner Controller
 shortTitle: Deploy runner scale sets
-intro: Learn how to deploy runner scale sets with {% data variables.product.prodname_actions_runner_controller %}, and use advanced configuration options to tailor {% data variables.product.prodname_actions_runner_controller %} to your needs.
+intro: Deploy runner scale sets with {% data variables.product.prodname_actions_runner_controller %}, and use advanced configuration options to tailor {% data variables.product.prodname_actions_runner_controller %} to your needs.
 versions:
   fpt: '*'
   ghec: '*'
@@ -11,9 +11,8 @@ redirect_from:
   - /actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller
   - /actions/how-tos/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller
   - /actions/tutorials/actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller
-contentType: tutorials
-category:
-  - Set up runners
+  - /actions/tutorials/use-actions-runner-controller/deploy-runner-scale-sets
+contentType: how-tos
 ---
 
 ## Deploying a runner scale set
@@ -32,7 +31,7 @@ You can deploy runner scale sets with ARC's Helm charts or by deploying the nece
 
    When you run the command, keep the following in mind.
 
-   * Update the `INSTALLATION_NAME` value carefully. You will use the installation name as the value of [`runs-on`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) in your workflows.
+   * Update the `INSTALLATION_NAME` value carefully. You can use the installation name as the value of [`runs-on`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) in your workflows.
    * Update the `NAMESPACE` value to the location you want the runner pods to be created.
    * Set the `GITHUB_CONFIG_URL` value to the URL of your repository, organization, or enterprise. This is the entity that the runners will belong to.
    * This example command installs the latest version of the Helm chart. To install a specific version, you can pass the `--version` argument with the version of the chart you want to install. You can find the list of releases in the [`actions-runner-controller`](https://github.com/actions/actions-runner-controller/pkgs/container/actions-runner-controller-charts%2Fgha-runner-scale-set) repository.
@@ -1222,7 +1221,7 @@ You can use {% data variables.product.prodname_actions_runner_controller %} to c
 
 You can also use ARC with {% data variables.product.prodname_codeql %} to identify vulnerabilities and errors in your code. For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql). If you're already using {% data variables.product.prodname_code_scanning %} and want to configure a runner scale set to use default setup, set `INSTALLATION_NAME=code-scanning`. For more information about {% data variables.product.prodname_code_scanning %} default setup, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning).
 
-{% data variables.product.prodname_actions_runner_controller %} does not use multiple labels to route jobs to specific runner scale sets. Instead, to designate a runner scale set for {% data variables.product.prodname_dependabot %} updates or {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}, use a descriptive installation name in your Helm chart, such as `dependabot` or `code-scanning`. You can then set the `runs-on` value in your workflows to the installation name as the single label, and use the designated runner scale set for {% data variables.product.prodname_dependabot %} updates or {% data variables.product.prodname_code_scanning %} jobs.
+To designate a runner scale set for {% data variables.product.prodname_dependabot %} updates or {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}, use a descriptive installation name in your Helm chart, such as `dependabot` or `code-scanning`. You can then set the `runs-on` value in your workflows to the installation name, and use the designated runner scale set for {% data variables.product.prodname_dependabot %} updates or {% data variables.product.prodname_code_scanning %} jobs.
 
 If you're using default setup for {% data variables.product.prodname_code_scanning %}, the analysis will automatically look for a runner scale set with the installation name `code-scanning` {% ifversion code-scanning-default-setup-customize-labels %} but you can specify a custom name in the configuration, so that individual repositories can use different runner scale sets. See [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning#assigning-labels-to-runners){% endif %}.
 
diff --git a/content/actions/how-tos/manage-runners/use-actions-runner-controller/index.md b/content/actions/how-tos/manage-runners/use-actions-runner-controller/index.md
@@ -0,0 +1,15 @@
+---
+title: Use Actions Runner Controller
+shortTitle: Actions Runner Controller
+intro: Host your own runners in a Kubernetes cluster with {% data variables.product.prodname_actions_runner_controller %}.
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+children:
+  - /authenticate-to-the-api
+  - /deploy-runner-scale-sets  
+  - /use-arc-in-a-workflow
+contentType: how-tos  
+---
+
diff --git a/content/actions/how-tos/manage-runners/use-actions-runner-controller/use-arc-in-a-workflow.md b/content/actions/how-tos/manage-runners/use-actions-runner-controller/use-arc-in-a-workflow.md
@@ -1,7 +1,7 @@
 ---
 title: Using Actions Runner Controller runners in a workflow
 shortTitle: Use ARC in a workflow
-intro: You can use {% data variables.product.prodname_actions_runner_controller %} runners in a workflow file.
+intro: Use {% data variables.product.prodname_actions_runner_controller %} runners in a workflow file.
 versions:
   fpt: '*'
   ghec: '*'
@@ -11,9 +11,8 @@ redirect_from:
   - /actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow
   - /actions/how-tos/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow
   - /actions/tutorials/actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow
-contentType: tutorials
-category:
-  - Use and manage runners
+  - /actions/tutorials/use-actions-runner-controller/use-arc-in-a-workflow
+contentType: how-tos
 ---
 
 ## Using ARC runners in a workflow file
@@ -50,6 +49,25 @@ Runner scale set names are unique within the runner group they belong to. To dep
 
 {% data reusables.actions.actions-runner-controller-labels %} For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller#scaling-runners).
 
+## Using labels to target runner scale sets
+
+You can also assign multiple labels to a runner scale set and use them to target runners in your workflow. To configure labels for a runner scale set, set the `runnerScaleSetLabels` values in your `values.yaml` file.
+
+```yaml
+runnerScaleSetLabels:
+  - linux
+  - gpu
+  - private-network
+```
+
+To target a runner scale set with specific labels, specify the labels as an array in the `runs-on` key of your workflow.
+
+```yaml
+jobs:
+  job_name:
+    runs-on: [linux, gpu, private-network]
+```
+
 ## Legal notice
 
 {% data reusables.actions.actions-runner-controller-legal-notice %}
diff --git a/content/actions/tutorials/use-actions-runner-controller/get-started.md b/content/actions/tutorials/use-actions-runner-controller/get-started.md
@@ -1,19 +1,18 @@
 ---
-title: Quickstart for Actions Runner Controller
-shortTitle: Quickstart
-intro: In this tutorial, you'll try out the basics of {% data variables.product.prodname_actions_runner_controller %}.
+title: Get started with Actions Runner Controller
+shortTitle: Get started
+intro: 'In this tutorial, you''ll try out the basics of {% data variables.product.prodname_actions_runner_controller %}.'
 versions:
   fpt: '*'
   ghec: '*'
   ghes: '*'
 defaultPlatform: linux
+contentType: tutorials
 redirect_from:
   - /actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/quickstart-for-actions-runner-controller
   - /actions/tutorials/quickstart-for-actions-runner-controller
   - /actions/tutorials/actions-runner-controller/quickstart-for-actions-runner-controller
-contentType: tutorials
-category:
-  - Set up runners
+  - /actions/tutorials/use-actions-runner-controller/quickstart
 ---
 
 ## Prerequisites
diff --git a/content/actions/tutorials/use-actions-runner-controller/index.md b/content/actions/tutorials/use-actions-runner-controller/index.md
@@ -1,6 +1,7 @@
 ---
-title: Use Actions Runner Controller
-intro: You can host your own runners to run workflows in a highly customizable environment.
+title: Actions Runner Controller
+intro: You can use {% data variables.product.prodname_actions_runner_controller %} to host your own runners in a Kubernetes cluster.
+allowTitleToDifferFromFilename: true
 versions:
   fpt: '*'
   ghes: '*'
@@ -11,16 +12,10 @@ journeyTracks:
     title: Set up Actions Runner Controller
     description: Install and configure Actions Runner Controller to run self-hosted runners at scale.
     guides:
-      - href: /actions/tutorials/use-actions-runner-controller/quickstart
-      - href: /actions/tutorials/use-actions-runner-controller/deploy-runner-scale-sets
-      - href: /actions/tutorials/use-actions-runner-controller/authenticate-to-the-api
-      - href: /actions/tutorials/use-actions-runner-controller/use-arc-in-a-workflow
+      - href: /actions/tutorials/use-actions-runner-controller/get-started
       - href: /actions/tutorials/use-actions-runner-controller/troubleshoot
 children:
-  - /quickstart
-  - /deploy-runner-scale-sets
-  - /authenticate-to-the-api
-  - /use-arc-in-a-workflow
+  - /get-started
   - /troubleshoot
 redirect_from:
   - /actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller
diff --git a/data/reusables/actions/actions-runner-controller-labels.md b/data/reusables/actions/actions-runner-controller-labels.md
@@ -1 +1 @@
-You cannot use additional labels to target runners created by ARC. You can only use the installation name of the runner scale set that you specified during the installation or by defining the value of the `runnerScaleSetName` field in your [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file. These are used as the 'single label' to use as your `runs-on` target.
+You can use the installation name of the runner scale set, or define the value of the `runnerScaleSetName` field in your [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file, as your `runs-on` target. You can also assign multiple labels to a scale set to enable more flexible job routing. To configure labels for a runner scale set, set the `runnerScaleSetLabels` value in your `values.yaml` file.
diff --git a/data/reusables/actions/self-hosted-runner-labels-runs-on.md b/data/reusables/actions/self-hosted-runner-labels-runs-on.md
@@ -2,4 +2,4 @@ To specify a self-hosted runner for your job, configure `runs-on` in your workfl
 
 Self-hosted runners may have the `self-hosted` label. When setting up a self-hosted runner, by default we will include the label `self-hosted`. You may pass in the `--no-default-labels` flag to prevent the self-hosted label from being applied. Labels can be used to create targeting options for runners, such as operating system or architecture, we recommend providing an array of labels that begins with `self-hosted` (this must be listed first) and then includes additional labels as needed. When you specify an array of labels, jobs will be queued on runners that have all the labels that you specify.
 
-Note that Actions Runner Controller does not support multiple labels and does not support the `self-hosted` label.
+>[!NOTE] {% data variables.product.prodname_actions_runner_controller %} does not support the `self-hosted` label.
