Restrict workflow access to runner groups (github#25463)

Author: Sarah Edwards

content/actions/hosting-your-own-runners/about-self-hosted-runners.md

@@ -51,7 +51,8 @@ For more information about installing and using self-hosted runners, see "[Addin
 - Can use cloud services or local machines that you already pay for.
 - Are customizable to your hardware, operating system, software, and security requirements.
 - Don't need to have a clean instance for every job execution.
-- Are free to use with {% data variables.product.prodname_actions %}, but you are responsible for the cost of maintaining your runner machines.
+- Are free to use with {% data variables.product.prodname_actions %}, but you are responsible for the cost of maintaining your runner machines.{% ifversion ghec or ghes or ghae %}
+- Can be organized into groups to restrict access to specific {% if restrict-groups-to-workflows %}workflows, {% endif %}organizations and repositories. For more information, see "[Managing access to self-hosted runners using groups](/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups)."{% endif %}
 
 ## Requirements for self-hosted runner machines
 

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

@@ -9,11 +9,12 @@ versions:
   ghae: '*'
   ghec: '*'
 type: tutorial
-shortTitle: Manage runner groups
+shortTitle: Manage access to runners
 ---
 
 {% data reusables.actions.enterprise-beta %}
 {% data reusables.actions.enterprise-github-hosted-runners %}
+{% data reusables.actions.restrict-runner-workflow-beta %}
 
 ## About self-hosted runner groups
 
@@ -30,9 +31,9 @@ If you use {% data variables.product.prodname_ghe_cloud %}, you can create addit
 {% endif %}
 
 {% ifversion ghec or ghes or ghae %}
-Self-hosted runner groups are used to control access to self-hosted runners at the organization and enterprise level. Enterprise admins can configure access policies that control which organizations in an enterprise have access to the runner group. Organization admins can configure access policies that control which repositories in an organization have access to the runner group.
+Self-hosted runner groups are used to control access to self-hosted runners at the organization and enterprise level. Enterprise owners can configure access policies that control which organizations {% if restrict-groups-to-workflows %}and workflows {% endif %}in an enterprise have access to the runner group. Organization owners can configure access policies that control which repositories{% if restrict-groups-to-workflows %} and workflows{% endif %} in an organization have access to the runner group.
 
-When an enterprise admin grants an organization access to a runner group, organization admins can see the runner group listed in the organization's self-hosted runner settings. The organizations admins can then assign additional granular repository access policies to the enterprise runner group.
+When an enterprise owner grants an organization access to a runner group, organization owners can see the runner group listed in the organization's self-hosted runner settings. The organization owners can then assign additional granular repository{% if restrict-groups-to-workflows %} and workflow{% endif %} access policies to the enterprise runner group.
 
 When new runners are created, they are automatically assigned to the default group. Runners can only be in one group at a time. You can move runners from the default group to another group. For more information, see "[Moving a self-hosted runner to a group](#moving-a-self-hosted-runner-to-a-group)."
 
@@ -42,13 +43,14 @@ All organizations have a single default self-hosted runner group. Organizations
 
 Self-hosted runners are automatically assigned to the default group when created, and can only be members of one group at a time. You can move a runner from the default group to any group you create.
 
-When creating a group, you must choose a policy that defines which repositories have access to the runner group.
+When creating a group, you must choose a policy that defines which repositories{% if restrict-groups-to-workflows %} and workflows{% endif %} have access to the runner group.
 
 {% ifversion ghec or ghes > 3.3 or ghae-issue-5091 %}
 {% data reusables.organizations.navigate-to-org %}
 {% data reusables.organizations.org_settings %}
 {% data reusables.actions.settings-sidebar-actions-runner-groups %}
 1. In the "Runner groups" section, click **New runner group**.
+1. Enter a name for your runner group.
  {% data reusables.actions.runner-group-assign-policy-repo %}
 
    {% warning %}
@@ -58,6 +60,7 @@ When creating a group, you must choose a policy that defines which repositories
    For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories)."
 
    {% endwarning %}
+{% data reusables.actions.runner-group-assign-policy-workflow %}{%- if restrict-groups-to-workflows %} Organization-owned runner groups cannot access workflows from a different organization in the enterprise; instead, you must create an enterprise-owned runner group.{% endif %}
 {% data reusables.actions.self-hosted-runner-create-group %}
 {% elsif ghae or ghes < 3.4 %}
 {% data reusables.organizations.navigate-to-org %}
@@ -88,7 +91,7 @@ When creating a group, you must choose a policy that defines which repositories
 
 ## Creating a self-hosted runner group for an enterprise
 
-Enterprises can add their self-hosted runners to groups for access management. Enterprises can create groups of self-hosted runners that are accessible to specific organizations in the enterprise account. Organization admins can then assign additional granular repository access policies to the enterprise runner groups. For information about how to create a self-hosted runner group with the REST API, see the enterprise endpoints in the [{% data variables.product.prodname_actions %} REST API](/rest/reference/actions#self-hosted-runner-groups).
+Enterprises can add their self-hosted runners to groups for access management. Enterprises can create groups of self-hosted runners that are accessible to specific organizations in the enterprise account{% if restrict-groups-to-workflows %} or to specific workflows{% endif %}. Organization owners can then assign additional granular repository{% if restrict-groups-to-workflows %} or workflow{% endif %} access policies to the enterprise runner groups. For information about how to create a self-hosted runner group with the REST API, see the enterprise endpoints in the [{% data variables.product.prodname_actions %} REST API](/rest/reference/actions#self-hosted-runner-groups).
 
 Self-hosted runners are automatically assigned to the default group when created, and can only be members of one group at a time. You can assign the runner to a specific group during the registration process, or you can later move the runner from the default group to a custom group.
 
@@ -115,17 +118,21 @@ When creating a group, you must choose a policy that defines which organizations
 
    ![Add runner group options](/assets/images/help/settings/actions-enterprise-account-add-runner-group-options-ae.png)
    {%- endif %}
+{% data reusables.actions.runner-group-assign-policy-workflow %}
 1. Click **Save group** to create the group and apply the policy.
 
 {% endif %}
 
 ## Changing the access policy of a self-hosted runner group
 
-You can update the access policy of a runner group, or rename a runner group.
+For runner groups in an enterprise, you can change what organizations in the enterprise can access a runner group{% if restrict-groups-to-workflows %} or restrict what workflows a runner group can run{% endif %}. For runner groups in an organization, you can change what repositories in the organization can access a runner group{% if restrict-groups-to-workflows %} or restrict what workflows a runner group can run{% endif %}.
+
+### Changing what organizations or repositories can access a runner group
+
 {% ifversion fpt or ghec or ghes > 3.3 or ghae-issue-5091 %}
 {% data reusables.actions.self-hosted-runner-groups-navigate-to-repo-org-enterprise %}
 {% data reusables.actions.settings-sidebar-actions-runner-groups-selection %}
-1. Modify the access options, or change the runner group name.
+1. For runner groups in an enterprise, under **Organization access**, modify what organizations can access the runner group. For runner groups in an organization, under **Repository access**, modify what repositories can access the runner group.
 
    {%- ifversion fpt or ghec or ghes %}
    {% warning %}
@@ -142,6 +149,35 @@ You can update the access policy of a runner group, or rename a runner group.
 {% data reusables.actions.self-hosted-runner-configure-runner-group-access %}
 {% endif %}
 
+{% if restrict-groups-to-workflows %}
+### Changing what workflows can access a runner group
+You can configure a self-hosted runner group to run either selected workflows or all workflows. For example, you might use this setting to protect secrets that are stored on self-hosted runners or to standardize deployment workflows by restricting a runner group to run only a specific reusable workflow. This setting cannot be overridden if you are configuring an organization's runner group that was shared by an enterprise. 
+{% data reusables.actions.self-hosted-runner-groups-navigate-to-repo-org-enterprise %}
+{% data reusables.actions.settings-sidebar-actions-runner-groups-selection %}
+1. Under **Workflow access**, select the dropdown menu and click **Selected workflows**.
+1. Click {% octicon "gear" aria-label="the gear icon" %}.
+1. Enter a comma separated list of the workflows that can access the runner group. Use the full path, including the repository name and owner. Pin the workflow to a branch, tag, or full SHA. For example: `octo-org/octo-repo/.github/workflows/build.yml@v2, octo-org/octo-repo/.github/workflows/deploy.yml@d6dc6c96df4f32fa27b039f2084f576ed2c5c2a5, monalisa/octo-test/.github/workflows/test.yml@main`.
+
+   Only jobs directly defined within the selected workflows will have access to the runner group.
+   
+   Organization-owned runner groups cannot access workflows from a different organization in the enterprise; instead, you must create an enterprise-owned runner group.
+
+1. Click **Save**.
+
+{% endif %}
+
+## Changing the name of a runner group
+
+{% ifversion fpt or ghec or ghes > 3.3 or ghae-issue-5091 %}
+{% data reusables.actions.self-hosted-runner-groups-navigate-to-repo-org-enterprise %}
+{% data reusables.actions.settings-sidebar-actions-runner-groups-selection %}
+1. Change the runner group name.
+
+{% elsif ghae or ghes < 3.4 %}
+{% data reusables.actions.self-hosted-runner-configure-runner-group %}
+1. Change the runner group name.
+{% endif %}
+
 {% ifversion ghec or ghes or ghae %}
 ## Automatically adding a self-hosted runner to a group
 

content/actions/security-guides/security-hardening-for-github-actions.md

@@ -265,7 +265,7 @@ This list describes the recommended approaches for accessing repository data wit
 
 {% ifversion fpt or ghec %}As a result, self-hosted runners should almost [never be used for public repositories](/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories) on {% data variables.product.product_name %}, because any user can open pull requests against the repository and compromise the environment. Similarly, be{% elsif ghes or ghae %}Be{% endif %} cautious when using self-hosted runners on private or internal repositories, as anyone who can fork the repository and open a pull request (generally those with read access to the repository) are able to compromise the self-hosted runner environment, including gaining access to secrets and the `GITHUB_TOKEN` which{% ifversion fpt or ghes > 3.1 or ghae or ghec %}, depending on its settings, can grant {% else %} grants {% endif %}write access to the repository. Although workflows can control access to environment secrets by using environments and required reviews, these workflows are not run in an isolated environment and are still susceptible to the same risks when run on a self-hosted runner.
 
-When a self-hosted runner is defined at the organization or enterprise level, {% data variables.product.product_name %} can schedule workflows from multiple repositories onto the same runner. Consequently, a security compromise of these environments can result in a wide impact. To help reduce the scope of a compromise, you can create boundaries by organizing your self-hosted runners into separate groups. For more information, see "[Managing access to self-hosted runners using groups](/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups)."
+When a self-hosted runner is defined at the organization or enterprise level, {% data variables.product.product_name %} can schedule workflows from multiple repositories onto the same runner. Consequently, a security compromise of these environments can result in a wide impact. To help reduce the scope of a compromise, you can create boundaries by organizing your self-hosted runners into separate groups. You can restrict what {% if restrict-groups-to-workflows %}workflows, {% endif %}organizations and repositories can access runner groups. For more information, see "[Managing access to self-hosted runners using groups](/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups)."
 
 You should also consider the environment of the self-hosted runner machines:
 - What sensitive information resides on the machine configured as a self-hosted runner? For example, private SSH keys, API access tokens, among others.

content/actions/using-workflows/reusing-workflows.md

@@ -307,3 +307,5 @@ For information about using the REST API to query the audit log for an organizat
 ## Next steps
 
 To continue learning about {% data variables.product.prodname_actions %}, see "[Events that trigger workflows](/actions/learn-github-actions/events-that-trigger-workflows)."
+
+{% if restrict-groups-to-workflows %}You can standardize deployments by creating a self-hosted runner group that can only execute a specific reusable workflow. For more information, see "[Managing access to self-hosted runners using groups](/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups)."{% endif %}

data/features/restrict-groups-to-workflows.yml

@@ -0,0 +1,6 @@
+# Issue 6137
+# Restrict self-hosted runner groups to specific workflows
+versions:
+  ghec: '*'
+  ghes: '>=3.5'
+  ghae: 'issue-6137'

data/reusables/actions/restrict-runner-workflow-beta.md

@@ -0,0 +1,7 @@
+{% if restrict-groups-to-workflows %}
+{% note %}
+
+**Note:** Configuring the workflows that can access a runner group is currently in beta and subject to change.
+
+{% endnote %}
+{% endif %}

data/reusables/actions/runner-group-assign-policy-org.md

@@ -1,3 +1,3 @@
-1. Enter a name for your runner group, and assign a policy for organization access.
+1. Assign a policy for organization access.
 
     You can configure a runner group to be accessible to a specific list of organizations, or all organizations in the enterprise.{% ifversion ghec or ghes %} By default, only private repositories can access runners in a runner group, but you can override this. This setting can't be overridden if configuring an organization's runner group that was shared by an enterprise.{% endif %}

data/reusables/actions/runner-group-assign-policy-repo.md

@@ -1,3 +1,3 @@
-1. Enter a name for your runner group, and assign a policy for repository access.
+1. Assign a policy for repository access.
 
     You can configure a runner group to be accessible to a specific list of repositories, or to all repositories in the organization.{% ifversion ghec or ghes %} By default, only private repositories can access runners in a runner group, but you can override this. This setting can't be overridden if configuring an organization's runner group that was shared by an enterprise.{% endif %}

data/reusables/actions/runner-group-assign-policy-workflow.md

@@ -0,0 +1,6 @@
+{%- if restrict-groups-to-workflows %}
+1. Assign a policy for workflow access.
+
+   You can configure a runner group to be accessible to a specific list of workflows, or to all workflows. This setting can't be overridden if you are configuring an organization's runner group that was shared by an enterprise. If you specify what workflow can access the runner group, you must use the full path to the workflow, including the repository name and owner, and you must pin the workflow to a branch, tag, or full SHA. For example: `octo-org/octo-repo/.github/workflows/build.yml@v2, octo-org/octo-repo/.github/workflows/deploy.yml@d6dc6c96df4f32fa27b039f2084f576ed2c5c2a5, monalisa/octo-test/.github/workflows/test.yml@main`. 
+   
+   Only jobs directly defined within the selected workflows will have access to the runner group.{%- endif %}

data/reusables/actions/self-hosted-runner-configure-runner-group-access.md

@@ -1,6 +1,5 @@
-1. In the {% ifversion fpt or ghes > 3.1 or ghae or ghec %}"Runners"{% else %}"Self-hosted runners"{% endif %} section of the settings page, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} next to the runner group you'd like to configure, then click **Edit name and [organization|repository] access**.
-    ![Manage repository permissions](/assets/images/help/settings/actions-runner-manage-permissions.png)
-1. Modify your policy options, or change the runner group name.
+{% data reusables.actions.self-hosted-runner-configure-runner-group %}
+1. Modify your policy options.
 
    {% ifversion not ghae %}
    {% warning %}