From 8ad66c296536e6a7d642caffed7d7ca08ace6705 Mon Sep 17 00:00:00 2001
From: hubwriter <hubwriter@github.com>
Date: Thu, 25 May 2023 08:09:19 +0100
Subject: [PATCH] Actions: document using variables in `runs-on` (#37205)

Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>
---
 .../section-choosing-the-runner-for-a-job.md  | 33 +++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/data/reusables/actions/jobs/section-choosing-the-runner-for-a-job.md b/data/reusables/actions/jobs/section-choosing-the-runner-for-a-job.md
index 6ae3d9dabc..94fada59e8 100644
--- a/data/reusables/actions/jobs/section-choosing-the-runner-for-a-job.md
+++ b/data/reusables/actions/jobs/section-choosing-the-runner-for-a-job.md
@@ -4,8 +4,37 @@ Use `jobs.<job_id>.runs-on` to define the type of machine to run the job on.
 - The destination machine can be a [self-hosted runner](#choosing-self-hosted-runners).{% endif %}
 {% ifversion target-runner-groups %}- You can target runners based on the labels assigned to them, or their group membership, or a combination of these.{% else %}
 - You can target runners based on the labels assigned to them.{% endif %}
-- You can provide `runs-on` as a single string or as an array of strings.
-- If you specify an array of strings, your workflow will execute on any runner that matches all of the specified `runs-on` values.
+- You can provide `runs-on` as:
+  - a single string
+  - a single variable containing a string
+  - an array of strings, variables containing strings, or a combination of both
+- If you specify an array of strings or variables, your workflow will execute on any runner that matches all of the specified `runs-on` values. For example, here the job will only run on a self-hosted runner that has the labels `linux`, `x64`, and `gpu`:
+  ```
+  runs-on: [self-hosted, linux, x64, gpu]
+  ```
+  For more information, see "[Choosing self-hosted runners](#choosing-self-hosted-runners)."
+- You can mix strings and variables in an array. For example:
+
+  {% raw %}
+  ```
+  on:
+    workflow_dispatch:
+      inputs:
+        chosen-os:
+          required: true
+          type: choice
+          options:
+          - Ubuntu
+          - macOS
+
+  jobs:
+    test:
+      runs-on: [self-hosted, "${{ github.event.inputs.chosen-os }}"]
+      steps:
+      - run: echo Hello world!
+  ```
+  {% endraw %}
+
 - If you would like to run your workflow on multiple machines, use [`jobs.<job_id>.strategy`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategy).
 
 {% ifversion fpt or ghec or ghes %}