GitHub Copilot Self-Hosted Runner Setup for Enterprise

GitHub Copilot self-hosted runners let you run workflows on your own infrastructure instead of GitHub-hosted runners. This setup is essential for enterprises that need to control costs, enforce security policies, or access private network resources during CI/CD pipelines. This article explains how to register, configure, and manage self-hosted runners for GitHub Copilot workflows in an enterprise environment. You will learn the prerequisites, installation steps, and common pitfalls to avoid.

Why Self-Hosted Runners for GitHub Copilot Workflows

GitHub Copilot workflows, such as code review automation or model fine-tuning jobs, require compute resources that can run for extended periods. Self-hosted runners give you full control over the operating system, installed software, and network connectivity. Enterprise teams use them to access on-premises databases, internal package registries, or VPN-protected services that GitHub-hosted runners cannot reach. You also avoid per-minute billing for compute time, which reduces costs for high-volume pipelines.

Prerequisites for Self-Hosted Runner Setup

Before you start, verify these requirements:

• A GitHub Enterprise Cloud or GitHub Enterprise Server account with admin access to the enterprise settings.
• A machine running a supported operating system: Ubuntu 20.04 or later, Windows Server 2019 or later, or macOS 11 or later.
• Minimum 2 vCPUs, 8 GB RAM, and 50 GB free disk space for Copilot-related workflows.
• Outbound HTTPS access to api.github.com or the GitHub Enterprise Server hostname.
• Git installed on the runner machine (version 2.30 or later).

Steps to Add a Self-Hosted Runner at the Enterprise Level

These instructions cover adding a runner that all organizations in your enterprise can use. If you need runner isolation per organization, repeat the process at the organization level instead.

1. Navigate to enterprise runner settings
   Sign in to GitHub.com. In the top-right corner, click your profile photo and select Your enterprises. Click the enterprise name. In the left sidebar, click Settings, then Actions, then Runners.
2. Click Add runner
   On the Runners page, click the green Add runner button. A modal appears with instructions for the operating system you select.
3. Choose the runner machine OS
   In the modal, select the operating system that matches your runner machine. GitHub provides download links for the runner agent binary and the config script specific to that OS.
4. Download and extract the runner agent
   On the runner machine, open a terminal or PowerShell as administrator. Run the download command shown in the modal. For Linux, the command looks like this:
   curl -o actions-runner-linux-x64-2.317.0.tar.gz -L https://github.com/actions/runner/releases/download/v2.317.0/actions-runner-linux-x64-2.317.0.tar.gz
   Extract the archive:
   tar xzf actions-runner-linux-x64-2.317.0.tar.gz
5. Run the config command with the registration token
   Copy the config command from the GitHub modal. It includes a unique registration token. Run it on the runner machine. Example for Linux:
   ./config.sh --url https://github.com/enterprises/YOUR_ENTERPRISE --token ABC123DEF456
   When prompted, enter the runner name, labels, and work folder. For Copilot workflows, add a custom label like copilot-runner to target it specifically.
6. Start the runner service
   After configuration, run the service installation command. On Linux:
   sudo ./svc.sh install
   Then start the service:
   sudo ./svc.sh start
   On Windows, use the provided PowerShell commands for service installation.
7. Verify the runner appears in GitHub
   Refresh the Runners page in GitHub. The new runner should appear with a green status indicator. Click the runner name to see its labels, IP address, and last active timestamp.

Runner Groups and Access Control

Runner groups let you restrict which repositories or organizations can use a specific self-hosted runner. By default, a new runner is placed in the Default group, which allows all organizations in the enterprise to use it. To create a restricted group:

1. Go to Runner groups
   In the enterprise settings, under Actions, click Runner groups.
2. Create a new group
   Click New group. Enter a name such as Copilot-Only.
3. Select organization access
   Choose Selected organizations and check the organizations that should have access. Click Save.
4. Move the runner to the new group
   Go back to the Runners page. Click the runner name, then click Settings. In the Runner group dropdown, select the new group and click Save.

Common Issues and Their Fixes

Runner shows offline after registration

The runner agent service might not be running. Check the service status with sudo ./svc.sh status on Linux or Get-Service -Name actions.runner. on Windows. If stopped, start the service. Also verify that the runner machine has outbound HTTPS access to api.github.com. Firewall rules or proxy configurations can block the connection.

Workflow jobs hang waiting for a runner

The workflow YAML file likely does not specify the correct runs-on label. Check the runner labels in GitHub. Update the workflow file to match. Example:
runs-on: [self-hosted, copilot-runner]
If the runner group restricts access, confirm the repository is in an allowed organization.

Runner agent fails to start after OS update

System libraries or dependencies may have changed. Uninstall the runner service, delete the _work folder, and re-run the config and service install steps. The runner agent binary remains compatible across minor OS updates, but major version upgrades require a fresh setup.

Item	GitHub-Hosted Runner	Self-Hosted Runner
Description	Ephemeral VM managed by GitHub	Persistent machine managed by your team
Cost model	Per-minute billing for compute	No per-minute charge; you pay for infrastructure
Network access	Public internet only	Private network, VPN, on-premises resources
Custom software	Limited to pre-installed tools	Any software you install
OS choice	Ubuntu, Windows, macOS versions selected by GitHub	Any OS version you choose and maintain
Job timeout	6 hours per job	No enforced timeout; set your own

Self-hosted runners give enterprises full control over the CI/CD environment for Copilot workflows. After setup, you can target specific runner labels in your workflow YAML files to route jobs to the correct machine. For large fleets, consider using the GitHub Actions Runner Controller for Kubernetes to auto-scale runners based on queue depth.