Actions: disabling repository-level self-hosted runners (#37170)

Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Co-authored-by: Francesco Renzi <rentziass@gmail.com>
Co-authored-by: Siara <108543037+SiaraMist@users.noreply.github.com>
Co-authored-by: github-actions <github-actions@github.com>

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

@@ -284,6 +284,14 @@ Untrusted workflows running on your self-hosted runner pose significant security
 
 For more information about security hardening for self-hosted runners, see "[AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#hardening-for-self-hosted-runners)."
 
+{% ifversion actions-disable-repo-runners %}
+
+### Restricting the use of self-hosted runners
+
+{% data reusables.actions.disable-selfhosted-runners-crossrefs %} 
+
+{% endif %}
+
 {% ifversion ghec or ghes or ghae %}
 
 ## Further reading

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

@@ -52,6 +52,16 @@ You can register ephemeral runners that perform a single job before the registra
 
 You can add self-hosted runners to a single repository. To add a self-hosted runner to a user repository, you must be the repository owner. For an organization repository, you must be an organization owner or have admin access to the repository. For information about how to add a self-hosted runner with the REST API, see "[AUTOTITLE](/rest/actions#self-hosted-runners)."
 
+{% ifversion actions-disable-repo-runners %}
+
+{% note %}
+
+**Note**: {% data reusables.actions.disable-selfhosted-runners-crossrefs %} 
+
+{% endnote %}
+
+{% endif %}
+
 {% data reusables.repositories.navigate-to-repo %}
 {% data reusables.repositories.sidebar-settings %}
 {% data reusables.repositories.settings-sidebar-actions-runners %}

content/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners.md

@@ -18,6 +18,16 @@ shortTitle: Monitor & troubleshoot
  
 {% data reusables.actions.enterprise-github-hosted-runners %}
 
+{% ifversion actions-disable-repo-runners %}
+
+## Using repository-level self-hosted runners
+
+You may not be able to create a self-hosted runner for an organization-owned repository.
+
+{% data reusables.actions.disable-selfhosted-runners-crossrefs %} 
+
+{% endif %}
+
 ## Checking the status of a self-hosted runner
 
 {% data reusables.actions.self-hosted-runner-management-permissions-required %}

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

@@ -307,6 +307,12 @@ SBOMs are available for Ubuntu, Windows, and macOS runner images. You can locate
 
 {% ifversion fpt or ghec %}As a result, self-hosted runners should almost [never be used for public repositories](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security) 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, depending on its settings, can grant 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.
 
+{% ifversion actions-disable-repo-runners %}
+
+{% data reusables.actions.disable-selfhosted-runners-crossrefs %} 
+
+{% endif %}
+
 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 {% ifversion restrict-groups-to-workflows %}workflows, {% endif %}organizations and repositories can access runner groups. For more information, see "[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups)."
 
 You should also consider the environment of the self-hosted runner machines:

content/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise.md

@@ -87,7 +87,7 @@ You may need to upgrade the CPU and memory resources for {% data variables.locat
 
 {% ifversion ghec %}If you are using self-hosted runners, you have to decide whether you want to use physical machines, virtual machines, or containers.{% else %}Decide whether you want to use physical machines, virtual machines, or containers for your self-hosted runners.{% endif %} Physical machines will retain remnants of previous jobs, and so will virtual machines unless you use a fresh image for each job or clean up the machines after each job run. If you choose containers, you should be aware that the runner auto-updating will shut down the container, which can cause workflows to fail. You should come up with a solution for this by preventing auto-updates or skipping the command to kill the container.
 
-You also have to decide where to add each runner. You can add a self-hosted runner to an individual repository, or you can make the runner available to an entire organization or your entire enterprise. Adding runners at the organization or enterprise levels allows sharing of runners, which might reduce the size of your runner infrastructure. You can use policies to limit access to self-hosted runners at the organization and enterprise levels by assigning groups of runners to specific repositories or organizations. For more information, see "[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners)" and "[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups)."
+You also have to decide where to add each runner. You can add a self-hosted runner to an individual repository, or you can make the runner available to an entire organization or your entire enterprise. Adding runners at the organization or enterprise levels allows sharing of runners, which might reduce the size of your runner infrastructure. You can use policies to limit access to self-hosted runners at the organization and enterprise levels by assigning groups of runners to specific repositories or organizations. For more information, see "[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners)" and "[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups)." {% ifversion actions-disable-repo-runners %}You can also use policies to prevent people using repository-level self-hosted runners. For more information, see "[AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#disabling-repository-level-self-hosted-runners)."{% endif %}
 
 {% ifversion ghec or ghes %}
 You should consider using autoscaling to automatically increase or decrease the number of available self-hosted runners. For more information, see "[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners)."

content/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise.md

@@ -59,6 +59,32 @@ You can choose to disable {% data variables.product.prodname_actions %} for all
 {% data reusables.enterprise-accounts.actions-tab %}
 1. Under "Policies", select {% data reusables.actions.policy-label-for-select-actions-workflows %} and add your required actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} to the list.
 
+{% ifversion actions-disable-repo-runners %}
+
+## Disabling repository-level self-hosted runners
+
+{% data reusables.actions.disable-selfhosted-runners-overview %} For more information on creating self-hosted runners at the repository level, see "[AUTOTITLE](/enterprise-cloud@latest/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners#adding-a-self-hosted-runner-to-a-repository)."
+
+By default anyone with admin access to a repository can add a self-hosted runner for the repository. The enterprise settings allow you to disable the use of repository-level self-hosted runners across all repositories in your enterprise. If you allow repository-level self-hosted runners for your enterprise, organization owners can choose to allow or prevent creation of repository-level self-hosted runners for some or all repositories in their organization. For more information see, "[AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization)."
+
+{% data reusables.actions.disable-selfhosted-runners-note %} 
+
+{% data reusables.enterprise-accounts.access-enterprise %}
+{% data reusables.enterprise-accounts.policies-tab %}
+{% data reusables.enterprise-accounts.actions-tab %}
+1. In the "Runners" section, select **Disable for all organizations**.{% ifversion ghec %}
+
+   {% note %}
+   
+   **Note**: Owners of an {% data variables.enterprise.prodname_emu_enterprise %} can also choose to select **Disable in all Enterprise Managed User (EMU) repositories** to restrict runner creation for repositories that are owned by managed user accounts.
+   
+   {% endnote %}
+
+   {% endif %}
+1. Click **Save** to apply the change.
+
+{% endif %}
+
 ## Enforcing a policy for artifact and log retention in your enterprise
 
 {% data variables.product.prodname_actions %} can store artifact and log files. For more information, see "[AUTOTITLE](/actions/managing-workflow-runs/downloading-workflow-artifacts)."

content/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization.md

@@ -50,6 +50,42 @@ You can choose to disable {% data variables.product.prodname_actions %} for all
 1. Under "Policies", select {% data reusables.actions.policy-label-for-select-actions-workflows %} and add your required actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} to the list.
 1. Click **Save**.
 
+{% ifversion actions-disable-repo-runners %}
+
+## Limiting the use of self-hosted runners
+
+{% data reusables.actions.disable-selfhosted-runners-overview %} 
+
+{% ifversion ghec or ghes %}
+
+{% note %}
+
+**Note**: If your organization belongs to an enterprise, creation of self-hosted runners at the repository level may have been disabled as an enterprise-wide setting. If this has been done, you cannot enable repository-level self-hosted runners in your organization settings. For more information, see "[AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise)."
+
+{% endnote %}
+
+{% endif %}
+
+If a repository already has self-hosted runners when you disable their use, these will be listed with the status "Disabled" and they will not be assigned any new workflow jobs.
+
+![Screenshot of the "Runners" list showing a self-hosted runner with the status "Disabled."](/assets/images/help/actions/actions-runners-disabled.png)
+
+{% data reusables.actions.disable-selfhosted-runners-note %} 
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+{% data reusables.organizations.settings-sidebar-actions-general %}
+1. Under "Runners," use the dropdown menu to choose your preferred setting:
+   - **All repositories** - self-hosted runners can be used for any repository in your organization.
+   - **Selected repositories** - self-hosted runners can only be used for the repositories you select.
+   - **Disabled** - self-hosted runners cannot be created at the repository level.
+1. If you choose **Selected repositories**:
+   1. Click {% octicon "gear" aria-label="Select repositories" %}.
+   1. Select the check boxes for the repositories for which you want to allow self-hosted runners.
+   1. Click **Select repositories**.
+
+{% endif %}
+
 {% ifversion fpt or ghec %}
 ## Configuring required approval for workflows from public forks
 

data/features/actions-disable-repo-runners.yml

@@ -0,0 +1,6 @@
+# Reference: #10198
+# Documentation for the ability to disable repo-level self-hosted runners
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>= 3.10'

data/reusables/actions/disable-selfhosted-runners-crossrefs.md

@@ -0,0 +1 @@
+{% ifversion ghec or ghes %}Enterprise owners and organization {% elsif fpt %}Organization {% endif %}owners can disable the ability to create self-hosted runners at the repository level. For more information, see {% ifversion ghec or ghes %}"[AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#disabling-repository-level-self-hosted-runners)" and {% endif %}"[AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#limiting-the-use-of-self-hosted-runners)."

data/reusables/actions/disable-selfhosted-runners-note.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note**: When creation of repository-level self-hosted runners is disabled, workflows can still access self-hosted runners that have been set up at the enterprise or organization level.
+
+{% endnote %}

data/reusables/actions/disable-selfhosted-runners-overview.md

@@ -0,0 +1,5 @@
+There is no guarantee that self-hosted runners for {% data variables.product.product_name %} will be hosted on ephemeral, clean virtual machines. As a result, they may be compromised by untrusted code in a workflow. 
+
+Similarly, anyone who can fork the repository and open a pull request (generally those with read access to the repository) can compromise the self-hosted runner environment, including gaining access to secrets and the `GITHUB_TOKEN` which, depending on its settings, can grant 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.
+
+For these and other reasons, you may decide to prevent people creating self-hosted runners at the repository level.