Self-hosted runners reference

Find information about setting up and using self-hosted runners.

Requirements for self-hosted runner machines

You can use a machine as a self-hosted runner as long as it meets these requirements:

You can install and run the self-hosted runner application on the machine. See Supported operating systems and Supported processor architectures.
The machine can communicate with GitHub Actions.
The machine has enough hardware resources for the type of workflows you plan to run. The self-hosted runner application itself only requires minimal resources.
If you want to run workflows that use Docker container actions or service containers, you must use a Linux machine and Docker must be installed.

Supported operating systems

Linux

Red Hat Enterprise Linux 8 or later
CentOS 8 or later
Oracle Linux 8 or later
Fedora 29 or later
Debian 10 or later
Ubuntu 20.04 or later
Linux Mint 20 or later
openSUSE 15.2 or later
SUSE Enterprise Linux (SLES) 15 SP2 or later

Windows

Windows 10 64-bit
Windows 11 64-bit
Windows Server 2016 64-bit
Windows Server 2019 64-bit
Windows Server 2022 64-bit

macOS

macOS 11.0 (Big Sur) or later

Supported processor architectures

x64 - Linux, macOS, Windows.
ARM64 - Linux, macOS, Windows (currently in public preview).
ARM32 - Linux.

Routing precedence for self-hosted runners

When routing a job to a self-hosted runner, GitHub looks for a runner that matches the job's runs-on labels and groups:

If GitHub finds an online and idle runner that matches the job's runs-on labels and groups, the job is then assigned and sent to the runner.
- If the runner doesn't pick up the assigned job within 60 seconds, the job is re-queued so that a new runner can accept it.
If GitHub doesn't find an online and idle runner that matches the job's runs-on labels and groups, then the job will remain queued until a runner comes online.
If the job remains queued for more than 24 hours, the job will fail.

Autoscaling

Autoscaling allows you to dynamically adjust the number of self-hosted runners based on demand. This helps optimize resource utilization and ensures sufficient runner capacity during peak times while reducing costs during periods of low activity. There are multiple approaches to implementing autoscaling for self-hosted runners, each with different trade-offs in terms of complexity, reliability, and responsiveness.

Actions Runner Controller

GitHub-hosted runners inherently autoscale based on your needs. GitHub-hosted runners can be a low-maintenance and cost-effective alternative to developing or implementing autoscaling solutions. For more information, see GitHub-hosted runners.

Actions Runner Controller (ARC) is the reference implementation of GitHub's scale set APIs and the recommended Kubernetes-based solution for autoscaling self-hosted runners. ARC provides a complete, production-ready autoscaling solution for teams running GitHub Actions in Kubernetes environments.

GitHub recommends ARC for organizations with Kubernetes infrastructure and teams that have Kubernetes expertise. ARC handles the full lifecycle of runners within your cluster, from provisioning to job execution to cleanup.

For more information, see Actions Runner Controller and Support for Actions Runner Controller.

GitHub Actions Runner Scale Set Client

The GitHub Actions Runner Scale Set Client is a standalone Go-based module that empowers platform teams, integrators, and infrastructure providers to build custom autoscaling solutions for GitHub Actions runners across VMs, containers, on-premise infrastructure, and cloud services, with support for Windows, Linux, and macOS platforms.

The client orchestrates GitHub API interactions for scale sets while leaving infrastructure provisioning to you. You define how runners are created, scaled, and destroyed, and configure runners with multiple labels for flexible job routing and targeting. This gives organizations granular control over runner lifecycle management and real-time telemetry for job execution.

The client is designed to work out of the box with basic configurations, allowing teams to quickly implement autoscaling. However, its true power lies in its flexibility—the client is built to be extended and customized to meet each organization's specific infrastructure requirements, compliance constraints, and operational workflows. Whether you need simple scaling logic or complex, multi-environment provisioning strategies, the client adapts to your needs.

The GitHub Actions Runner Scale Set Client is an open source project. The actions/scaleset repository contains the complete source code, comprehensive documentation, and practical examples to help you get started. You'll find implementation guides, sample configurations for various infrastructure scenarios, and reference architectures demonstrating how to integrate the client with different provisioning systems. The repository also includes contributing guidelines for teams interested in extending the client or sharing their autoscaling patterns with the community.

Note: The Runner Scale Set Client is not a replacement for Actions Runner Controller (ARC), which remains the reference implementation of the scale set APIs and the recommended Kubernetes solution for autoscaling runners. Instead, the client is a complementary tool for interfacing with the same scale set APIs to build custom autoscaling solutions outside of Kubernetes.

Ephemeral runners for autoscaling

GitHub recommends implementing autoscaling with ephemeral self-hosted runners; autoscaling with persistent self-hosted runners is not recommended. In certain cases, GitHub cannot guarantee that jobs are not assigned to persistent runners while they are shut down. With ephemeral runners, this can be guaranteed because GitHub only assigns one job to a runner.

This approach allows you to manage your runners as ephemeral systems, since you can use automation to provide a clean environment for each job. This helps limit the exposure of any sensitive resources from previous jobs, and also helps mitigate the risk of a compromised runner receiving new jobs.

Warning

The runner application log files for ephemeral runners must be forwarded to an external log storage solution for troubleshooting and diagnostic purposes. While it is not required for ephemeral runners to be deployed, GitHub recommends ensuring runner logs are forwarded and preserved externally before deploying an ephemeral runner autoscaling solution in a production environment. For more information, see Monitoring and troubleshooting self-hosted runners.

To add an ephemeral runner to your environment, include the --ephemeral parameter when registering your runner using config.sh. For example:

./config.sh --url https://github.com/octo-org --token example-token --ephemeral

The GitHub Actions service will then automatically de-register the runner after it has processed one job. You can then create your own automation that wipes the runner after it has been de-registered.

Note

If a job is labeled for a certain type of runner, but none matching that type are available, the job does not immediately fail at the time of queueing. Instead, the job will remain queued until the 24 hour timeout period expires.

Alternatively, you can create ephemeral, just-in-time runners using the REST API. For more information, see REST API endpoints for self-hosted runners.

Runner software updates on self-hosted runners

By default, self-hosted runners will automatically perform a software update whenever a new version of the runner software is available. If you use ephemeral runners in containers then this can lead to repeated software updates when a new runner version is released. Turning off automatic updates allows you to update the runner version on the container image directly on your own schedule.

To turn off automatic software updates and install software updates yourself, specify the --disableupdate flag when registering your runner using config.sh. For example:

./config.sh --url https://github.com/YOUR-ORGANIZATION --token EXAMPLE-TOKEN --disableupdate

If you disable automatic updates, you must still update your runner version regularly. New functionality in GitHub Actions requires changes in both the GitHub Actions service and the runner software. The runner may not be able to correctly process jobs that take advantage of new features in GitHub Actions without a software update.

If you disable automatic updates, you will be required to update your runner version within 30 days of a new version being made available. You may want to subscribe to notifications for releases in the actions/runner repository. For more information, see Configuring notifications.

For instructions on how to install the latest runner version, see the installation instructions for the latest release.

Warning

Any updates released for the software, including major, minor, or patch releases, are considered as an available update. If you do not perform a software update within 30 days, the GitHub Actions service will not queue jobs to your runner. In addition, if a critical security update is required, the GitHub Actions service will not queue jobs to your runner until it has been updated.

Webhooks for autoscaling

You can create your own autoscaling environment by using payloads received from the workflow_job webhook. This webhook is available at the repository, organization, and enterprise levels, and the payload for this event contains an action key that corresponds to the stages of a workflow job's life-cycle; for example when jobs are queued, in_progress, and completed. You must then create your own scaling automation in response to these webhook payloads.

For more information about the workflow_job webhook, see Webhook events and payloads.
To learn how to work with webhooks, see Webhooks documentation.

Note: This approach relies on the timeliness of webhook delivery for making scaling decisions, which can introduce delays and reliability concerns. Consider using Actions Controller or the Scale Set Client for larger volume autoscaling scenarios.

Authentication requirements

You can register and delete repository and organization self-hosted runners using the API. To authenticate to the API, your autoscaling implementation can use an access token or a GitHub app.

Your access token will require the following scope:

For private repositories, use an access token with the repo scope.
For public repositories, use an access token with the public_repo scope.
For organizations, use an access token with the admin:org scope.

To authenticate using a GitHub App, it must be assigned the following permissions:

For repositories, assign the administration permission.
For organizations, assign the organization_self_hosted_runners permission.

You can register and delete enterprise self-hosted runners using the API. To authenticate to the API, your autoscaling implementation can use an access token.

Your access token will require the manage_runners:enterprise scope.

Communication

Self-hosted runners connect to GitHub to receive job assignments and download new versions of the runner application.

The GitHub Actions runner application is open source. You can contribute and file issues in the runner repository. When a new version is released, the runner application automatically updates itself when a job is assigned to the runner, or within a week of release if the runner hasn't been assigned any jobs.

Requirements for communication with GitHub

The self-hosted runner application must be running on the host machine to accept and run GitHub Actions jobs.
The host machine must have appropriate network access with at least 70 kilobits per second upload and download speed.
The host machine must be able to make outbound HTTPS connections over port 443.
Depending on the function of the workflows assigned to your self-hosted runner, the host machine must be able to communicate with the GitHub domains listed below.

Accessible domains by function

Note

Some of the domains listed are configured using CNAME records. Some firewalls might require you to add rules recursively for all CNAME records. Note that the CNAME records might change in the future, and that only the domains listed will remain constant.

Needed for essential operations:

github.com
api.github.com
*.actions.githubusercontent.com

Needed for downloading actions:

codeload.github.com

Needed for uploading/downloading job summaries, logs, workflow artifacts, and caches:

results-receiver.actions.githubusercontent.com
*.blob.core.windows.net

Needed for runner version updates:

objects.githubusercontent.com
objects-origin.githubusercontent.com
github-releases.githubusercontent.com
github-registry-files.githubusercontent.com

Needed for retrieving OIDC tokens:

*.actions.githubusercontent.com

Needed for downloading or publishing packages or containers to GitHub Packages:

*.pkg.github.com
pkg-containers.githubusercontent.com
ghcr.io

Needed for Git Large File Storage

github-cloud.githubusercontent.com
github-cloud.s3.amazonaws.com

Needed for jobs for Dependabot updates

dependabot-actions.githubapp.com

Needed for downloading release assets:

release-assets.githubusercontent.com

Needed for VNet:

api.snapcraft.io

In addition, your workflow may require access to other network resources.

If you use an IP address allow list for your GitHub organization or enterprise account, you must add your self-hosted runner's IP address to the allow list. See Managing allowed IP addresses for your organization or Enforcing policies for security settings in your enterprise in the GitHub Enterprise Cloud documentation.