[2026-04-02] Organization-level runner controls for Copilot coding agent (#60594)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: timrogers <116134+timrogers@users.noreply.github.com>
Co-authored-by: Tim Rogers <timrogers@github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Sunbrye Ly <56200261+sunbrye@users.noreply.github.com>
Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com>

Author: 5 people

content/copilot/how-tos/administer-copilot/manage-for-organization/add-copilot-coding-agent.md

@@ -57,6 +57,7 @@ Organization owners can configure the {% data variables.copilot.copilot_coding_a
 ## Next steps
 
 * Tell the members of repositories where {% data variables.copilot.copilot_coding_agent %} is available that they can delegate work to the {% data variables.copilot.copilot_coding_agent_short %}.
+* Configure the default runner type for {% data variables.copilot.copilot_coding_agent %} in your organization. For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/configure-runner-for-coding-agent).
 * Encourage members to educate themselves about setting up their repository to get the most from {% data variables.copilot.copilot_coding_agent %}. Useful resources:
 
    * [AUTOTITLE](/copilot/tutorials/coding-agent/best-practices)

content/copilot/how-tos/administer-copilot/manage-for-organization/configure-runner-for-coding-agent.md

@@ -0,0 +1,52 @@
+---
+title: Configuring runners for GitHub Copilot cloud agent in your organization
+shortTitle: Configure agent runners
+allowTitleToDifferFromFilename: true
+intro: 'Configure the {% data variables.product.prodname_actions %} runners used by {% data variables.copilot.copilot_coding_agent %} and control whether repositories can customize the runner type.'
+permissions: Organization owners
+product: '{% data reusables.gated-features.copilot-coding-agent %}<br><a href="https://github.com/github-copilot/purchase?ref_product=copilot&ref_type=trial&ref_style=button&ref_plan=enterprise" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Sign up for {% data variables.product.prodname_copilot_short %}</span> {% octicon "link-external" height:16 %}</a>'
+versions:
+  feature: copilot
+contentType: how-tos
+category:
+  - Manage Copilot for a team
+---
+
+## About organization-level runner controls
+
+By default, {% data variables.copilot.copilot_coding_agent %} runs on a standard {% data variables.product.prodname_dotcom %}-hosted {% data variables.product.prodname_actions %} runner (`ubuntu-latest`). As an organization owner, you can change the default runner type for all repositories in your organization, and choose whether individual repositories are allowed to override this default.
+
+This is useful if your organization requires all {% data variables.copilot.copilot_coding_agent %} sessions to run on specific runners—for example, to use larger runners for better performance, or to use self-hosted runners that have access to internal resources.
+
+You can configure:
+
+* **Runner type**: Choose between a standard {% data variables.product.prodname_dotcom %}-hosted runner or a labeled runner from a specific runner group.
+* **Allow repositories to customize the runner type**: Control whether repositories can override the organization default using a {% data variables.product.prodname_copilot_short %} setup steps workflow defined at `.github/workflows/copilot-setup-steps.yml`.
+
+## Configuring the default runner type
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+{% data reusables.copilot.coding-agent-settings %}
+1. Next to "Runner type," click the pencil icon ({% octicon "pencil" aria-label="Edit" %}).
+1. Select the runner type to use by default for {% data variables.copilot.copilot_coding_agent %} across your organization.
+   * **Standard {% data variables.product.prodname_dotcom %} runner**: {% data variables.copilot.copilot_coding_agent %} will use `ubuntu-latest`.
+   * **Labeled runner**: {% data variables.copilot.copilot_coding_agent %} will use a runner matching the group name and/or label you specify. Enter values in the **Runner group name** and/or **Runner label** fields.
+1. Click **Save runner selection**.
+
+## Preventing repositories from customizing the runner type
+
+By default, repositories can override the organization-level runner configuration using a {% data variables.product.prodname_copilot_short %} setup steps workflow located at `.github/workflows/copilot-setup-steps.yml`. If you want to enforce a consistent runner type across all repositories, you can disable this option.
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+{% data reusables.copilot.coding-agent-settings %}
+1. Under "Allow repositories to customize the runner type," toggle the setting to enable or disable repository-level customization.
+   * When enabled, repositories can override the default runner by setting the `runs-on` field in the `copilot-setup-steps` job of `copilot-setup-steps.yml`. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment#configure-the-runner).
+   * When disabled, all repositories in your organization will use the organization-level runner type.
+1. Click **Save**.
+
+## Further reading
+
+* [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment)
+* [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/add-copilot-coding-agent)

content/copilot/how-tos/administer-copilot/manage-for-organization/index.md

@@ -15,6 +15,7 @@ children:
   - /manage-access
   - /manage-policies
   - /add-copilot-coding-agent
+  - /configure-runner-for-coding-agent
   - /prepare-for-custom-agents
   - /review-activity
   - /use-your-own-api-keys

content/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment.md

@@ -33,6 +33,9 @@ In addition, you can:
 * [Set environment variables in {% data variables.product.prodname_copilot_short %}'s environment](#setting-environment-variables-in-copilots-environment)
 * [Disable or customize the agent's firewall](/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent).
 
+> [!NOTE]
+> Organization owners can configure the default runner type for {% data variables.copilot.copilot_coding_agent %} across all repositories in their organization, and choose whether repositories are allowed to override this default. For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/configure-runner-for-coding-agent).
+
 ## Customizing {% data variables.product.prodname_copilot_short %}'s development environment with {% data variables.product.prodname_copilot_short %} setup steps
 
 You can customize {% data variables.product.prodname_copilot_short %}'s environment by creating a special {% data variables.product.prodname_actions %} workflow file, located at `.github/workflows/copilot-setup-steps.yml` within your repository.