repo sync

content/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups.md

@@ -4,6 +4,7 @@ shortTitle: Manage access with runner groups
 intro: You can use policies to limit access to self-hosted runners that have been added to an organization or enterprise.
 redirect_from:
   - /actions/hosting-your-own-runners/managing-access-to-self-hosted-runners
+miniTocMaxHeadingLevel: 3
 versions:
   fpt: '*'
   ghes: '*'
@@ -15,6 +16,10 @@ type: tutorial
 {% data reusables.actions.enterprise-beta %}
 {% data reusables.actions.enterprise-github-hosted-runners %}
 
+{% ifversion target-runner-groups %}
+For information on how to route jobs to runners in a specific group, see "[Choosing runners in a group](/actions/using-jobs/choosing-the-runner-for-a-job#choosing-runners-in-a-group)."
+{% endif %}
+
 ## About runner groups
 
 {% data reusables.actions.about-runner-groups %} {% ifversion fpt %}For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups).{% endif %}
@@ -71,3 +76,5 @@ type: tutorial
 {% data reusables.actions.removing-a-runner-group %}
 
 {% endif %}
+
+{% data reusables.actions.section-using-unique-names-for-runner-groups %}

content/actions/hosting-your-own-runners/using-labels-with-self-hosted-runners.md

@@ -13,7 +13,7 @@ shortTitle: Label runners
 {% data reusables.actions.enterprise-beta %}
 {% data reusables.actions.enterprise-github-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](/actions/hosting-your-own-runners/using-self-hosted-runners-in-a-workflow)."
+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](/actions/hosting-your-own-runners/using-self-hosted-runners-in-a-workflow)." {% ifversion target-runner-groups %}You can also route jobs to runners in a specific group. For more information, see "[Targeting runners in a group](/actions/using-jobs/choosing-the-runner-for-a-job#targeting-runners-in-a-group)."{% endif %}
 
 {% data reusables.actions.self-hosted-runner-management-permissions-required %}
 

content/actions/using-github-hosted-runners/controlling-access-to-larger-runners.md

@@ -3,6 +3,7 @@ title: Controlling access to larger runners
 shortTitle: 'Control access to {% data variables.actions.hosted_runner %}s'
 intro: 'You can use policies to limit access to {% data variables.actions.hosted_runner %}s that have been added to an organization or enterprise.'
 product: '{% data reusables.gated-features.hosted-runners %}'
+miniTocMaxHeadingLevel: 3
 versions:
   feature: actions-hosted-runners
 type: tutorial
@@ -29,6 +30,8 @@ type: tutorial
 
 {% endif %}
 
+{% data reusables.actions.section-using-unique-names-for-runner-groups %}
+
 ## Changing the access policy of a runner group
 
 {% data reusables.actions.hosted-runner-security-admonition %}

content/actions/using-github-hosted-runners/using-larger-runners.md

@@ -28,13 +28,13 @@ When you add a {% data variables.actions.hosted_runner %} to an organization, yo
 
 ## Architectural overview of {% data variables.actions.hosted_runner %}s
 
-The {% data variables.actions.hosted_runner %}s are managed at the organization level, where they are arranged into groups that can contain multiple instances of the runner. They can also be created at the enterprise level and shared with organizations in the hierarchy. Once you've created a group, you can then add a runner to the group and update your workflows to target the label assigned to the {% data variables.actions.hosted_runner %}. You can also control which repositories are permitted to send jobs to the group for processing. For more information about groups, see "[Controlling access to {% data variables.actions.hosted_runner %}s](/actions/using-github-hosted-runners/controlling-access-to-larger-runners)."
+The {% data variables.actions.hosted_runner %}s are managed at the organization level, where they are arranged into groups that can contain multiple instances of the runner. They can also be created at the enterprise level and shared with organizations in the hierarchy. Once you've created a group, you can then add a runner to the group and update your workflows to target either the group name or the label assigned to the {% data variables.actions.hosted_runner %}. You can also control which repositories are permitted to send jobs to the group for processing. For more information about groups, see "[Controlling access to {% data variables.actions.hosted_runner %}s](/actions/using-github-hosted-runners/controlling-access-to-larger-runners)."
 
 In the following diagram, a class of hosted runner named `ubuntu-20.04-16core` has been defined with customized hardware and operating system configuration.
 
 ![Diagram explaining {% data variables.actions.hosted_runner %}](/assets/images/hosted-runner.png)
 
-1. Instances of this runner are automatically created and added to a group called `ubuntu-20.04-16core`. 
+1. Instances of this runner are automatically created and added to a group called `grp-ubuntu-20.04-16core`. 
 2. The runners have been assigned the label `ubuntu-20.04-16core`. 
 3. Workflow jobs use the `ubuntu-20.04-16core` label in their `runs-on` key to indicate the type of runner they need to execute the job.
 4. {% data variables.product.prodname_actions %} checks the runner group to see if your repository is authorized to send jobs to the runner.
@@ -99,14 +99,51 @@ You can add a {% data variables.actions.hosted_runner %} to an organization, whe
 
 ## Running jobs on your runner
 
-Once your runner type has been defined, you can update your workflow YAML files to send jobs to your newly created runner instances for processing. In this example, a runner group is populated with Ubuntu 16-core runners, which have been assigned the label `ubuntu-20.04-16core`. If you have a runner matching this label, the `check-bats-version` job then uses the `runs-on` key to target that runner whenever the job is run:
+Once your runner type has been defined, you can update your workflow YAML files to send jobs to your newly created runner instances for processing. You can use runner groups or labels to define where your jobs run. 
+
+Only owner or administrator accounts can see the runner settings. Non-administrative users can contact the organization administrator to find out which runners are enabled. Your organization administrator can create new runners and runner groups, as well as configure permissions to specify which repositories can access a runner group.
+
+### Using groups to control where jobs are run
+
+{% data reusables.actions.jobs.example-runs-on-groups %}
+
+### Using labels to control where jobs are run
+
+In this example, a runner group is populated with Ubuntu 16-core runners, which have also been assigned the label `ubuntu-20.04-16core`. The `runs-on` key sends the job to any available runner with a matching label:
+
+```yaml
+name: learn-github-actions
+on: [push]
+jobs:
+  check-bats-version:
+    runs-on:
+      labels: ubuntu-20.04-16core
+    steps:
+      - uses: {% data reusables.actions.action-checkout %}
+      - uses: {% data reusables.actions.action-setup-node %}
+        with:
+          node-version: '14'
+      - run: npm install -g bats
+      - run: bats -v
+```
+
+### Using labels and groups to control where jobs are run
+
+{% data reusables.actions.jobs.example-runs-on-labels-and-groups %}
+
+### Using multiple labels
+
+You can specify multiple labels that need to be matched for a job to run on a runner. A runner will need to match all labels to be eligible to run the job.
+
+In this example, a runner will need to match all three of the labels to run the job:
 
 ```yaml
 name: learn-github-actions
 on: [push]
 jobs:
   check-bats-version:
-    runs-on: ubuntu-20.04-16core
+    runs-on:
+      labels: [ ubuntu-20.04-16core, gpu, qa ]
     steps:
       - uses: {% data reusables.actions.action-checkout %}
       - uses: {% data reusables.actions.action-setup-node %}
@@ -116,7 +153,7 @@ jobs:
       - run: bats -v
 ```
 
-To find out which runners are enabled for your repository and organization, you must contact your organization admin. Your organization admin can create new runners and runner groups, as well as configure permissions to specify which repositories can access a runner group.
+{% data reusables.actions.section-using-unique-names-for-runner-groups %}
 
 ## Managing access to your runners
 

content/actions/using-jobs/choosing-the-runner-for-a-job.md

@@ -2,12 +2,12 @@
 title: Choosing the runner for a job
 shortTitle: Choose the runner for a job
 intro: Define the type of machine that will process a job in your workflow.
+miniTocMaxHeadingLevel: 3
 versions:
   fpt: '*'
   ghes: '*'
   ghae: '*'
   ghec: '*'
-miniTocMaxHeadingLevel: 4
 ---
 
 {% data reusables.actions.enterprise-beta %}

data/features/target-runner-groups.yml

@@ -0,0 +1,7 @@
+# Reference: #8268
+# Restrict workflow using runner group names
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>= 3.8'
+  ghae: '>= 3.8'

data/reusables/actions/jobs/example-runs-on-groups.md

@@ -0,0 +1,17 @@
+In this example, Ubuntu 16-core runners have been added to a group called `ubuntu-runners`. The `runs-on` key sends the job to any available runner in the `ubuntu-runners` group:
+
+```yaml
+name: learn-github-actions
+on: [push]
+jobs:
+  check-bats-version:
+    runs-on: 
+      group: ubuntu-runners
+    steps:
+      - uses: {% data reusables.actions.action-checkout %}
+      - uses: {% data reusables.actions.action-setup-node %}
+        with:
+          node-version: '14'
+      - run: npm install -g bats
+      - run: bats -v
+```

data/reusables/actions/jobs/example-runs-on-labels-and-groups.md

@@ -0,0 +1,20 @@
+When you combine groups and labels, the runner must meet both requirements to be eligible to run the job.
+
+In this example, a runner group called `ubuntu-runners` is populated with Ubuntu 16-core runners, which have also been assigned the label `ubuntu-20.04-16core`. The `runs-on` key combines `group` and `labels` so that the job is routed to any available runner within the group that also has a matching label:
+
+```yaml
+name: learn-github-actions
+on: [push]
+jobs:
+  check-bats-version:
+    runs-on:
+      group: ubuntu-runners
+      labels: ubuntu-20.04-16core
+    steps:
+      - uses: {% data reusables.actions.action-checkout %}
+      - uses: {% data reusables.actions.action-setup-node %}
+        with:
+          node-version: '14'
+      - run: npm install -g bats
+      - run: bats -v
+```

data/reusables/actions/jobs/section-choosing-the-runner-for-a-job.md

@@ -1,5 +1,12 @@
-Use `jobs.<job_id>.runs-on` to define the type of machine to run the job on. {% ifversion fpt or ghec %}The machine can be either a {% data variables.product.prodname_dotcom %}-hosted runner or a self-hosted runner.{% 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 run on a self-hosted runner whose labels match all of the specified `runs-on` values, if available. If you would like to run your workflow on multiple machines, use [`jobs.<job_id>.strategy`](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategy).
+Use `jobs.<job_id>.runs-on` to define the type of machine to run the job on. 
 
+{% ifversion fpt or ghec %}- The destination machine can be either a [{% data variables.product.prodname_dotcom %}-hosted runner](#choosing-github-hosted-runners), [{% data variables.actions.hosted_runner %}](#choosing-runners-in-a-group), or a [self-hosted runner](#choosing-self-hosted-runners).{% else %}
+- 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. 
+- If you would like to run your workflow on multiple machines, use [`jobs.<job_id>.strategy`](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategy).
 
 {% ifversion fpt or ghec or ghes %}
 {% data reusables.actions.enterprise-github-hosted-runners %}
@@ -34,3 +41,21 @@ runs-on: [self-hosted, linux]
 ```
 
 For more information, see "[About self-hosted runners](/github/automating-your-workflow-with-github-actions/about-self-hosted-runners)" and "[Using self-hosted runners in a workflow](/github/automating-your-workflow-with-github-actions/using-self-hosted-runners-in-a-workflow)."
+
+{% ifversion target-runner-groups %}
+
+### Choosing runners in a group
+
+You can use `runs-on` to target runner groups, so that the job will execute on any runner that is a member of that group. For more granular control, you can also combine runner groups with labels.
+
+Runner groups can only have [{% data variables.actions.hosted_runner %}s](/actions/using-github-hosted-runners/using-larger-runners) or [self-hosted runners](/actions/hosting-your-own-runners) as members.
+
+#### Example: Using groups to control where jobs are run
+
+{% data reusables.actions.jobs.example-runs-on-groups %}
+
+#### Example: Combining groups and labels
+
+{% data reusables.actions.jobs.example-runs-on-labels-and-groups %}
+
+{% endif %}

data/reusables/actions/section-using-unique-names-for-runner-groups.md

@@ -0,0 +1,34 @@
+
+{% ifversion target-runner-groups %}{% ifversion ghec or ghae or ghes %}
+## Using unique names for runner groups
+
+{% data variables.product.prodname_actions %} requires that runner group names must be unique at the organization level. This means that an organization will no longer be able to create a runner group with the same name as one in the enterprise. In addition, users will see a warning banner on any runner groups that share the same name as a group in the enterprise, suggesting that the organization group should be renamed.
+
+To avoid ambiguity, a workflow will fail if there are duplicate runner groups in the organization and enterprise. To address this, you can either rename one of your runner groups in the organization or enterprise, or you can update your workflow file to add a prefix to the runner group name:
+
+- `org/` or `organization/`
+- `ent/` or `enterprise/`
+
+### Example: Using prefixes to differentiate runner groups
+
+For example, if you have a runner group named `my-group` in the organization and another named `my-group` in the enterprise, you can update your workflow file to use `org/my-group` or `ent/my-group` to differentiate between the two.
+
+Using `org/`:
+
+```yaml
+runs-on:
+  group: org/my-group
+  labels: [ self-hosted, label-1 ]
+```
+
+Using `ent/`:
+
+```yaml
+runs-on:
+  group: ent/my-group
+  labels: [ self-hosted, label-1 ]
+```
+
+{% endif %}
+
+{% endif %}