Warning: Self-hosted runners are long-lived, and any compromise to the host machine could leak secrets or credentials or enable other attacks. For more information about the risks of using self-hosted runners, see "Security hardening for GitHub Actions." For more information about the management of access to GitHub Actions for your enterprise, see "Enforcing GitHub Actions policies for your enterprise."
Self-hosted runners offer more control of hardware, operating system, and software tools than GitHub-hosted runners provide. With self-hosted runners, you can choose to create a custom hardware configuration with more processing power or memory to run larger jobs, install software available on your local network, and choose an operating system not offered by GitHub-hosted runners. Self-hosted runners can be physical, virtual, in a container, on-premises, or in a cloud.
You can add self-hosted runners at various levels in the management hierarchy:
- Repository-level runners are dedicated to a single repository.
- Organization-level runners can process jobs for multiple repositories in an organization.
- Enterprise-level runners can be assigned to multiple organizations in an enterprise account.
Your runner machine connects to GitHub AE using the GitHub Actions self-hosted 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.
A self-hosted runner is automatically removed from GitHub AE if it has not connected to GitHub Actions for more than 30 days.
Self-hosted runners are a highly configurable way to run workflows in your own custom environment. Self-hosted runners:
- Receive automatic updates for the self-hosted runner application only. You are responsible for updating the operating system and all other software.
- 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 GitHub Actions, but you are responsible for the cost of maintaining your runner machines.
You can use any machine as a self-hosted runner as long at it meets these requirements:
- You can install and run the self-hosted runner application on the machine. For more information, see "Supported architectures and operating systems for self-hosted runners."
- The machine can communicate with GitHub Actions. For more information, see "Communication between self-hosted runners and GitHub."
- 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.
There are some limits on GitHub Actions usage when using self-hosted runners. These limits are subject to change.
- Workflow run time - Each workflow run is limited to 72 hours. If a workflow run reaches this limit, the workflow run is cancelled.
- Job queue time - Each job for self-hosted runners can be queued for a maximum of 24 hours. If a self-hosted runner does not start executing the job within this limit, the job is terminated and fails to complete.
- API requests - You can execute up to 1000 API requests in an hour across all actions within a repository. If exceeded, additional API calls will fail, which might cause jobs to fail.
- Job matrix - A job matrix can generate a maximum of 256 jobs per workflow run. This limit also applies to self-hosted runners.
- Workflow run queue - No more than 500 workflow runs can be queued in a 10 second interval per repository. If a workflow run reaches this limit, the workflow run is terminated and fails to complete.
If GitHub Actions services are temporarily unavailable, then a workflow run is discarded if it has not been queued within 30 minutes of being triggered. For example, if a workflow is triggered and the GitHub Actions services are unavailable for 31 minutes or longer, then the workflow run will not be processed.
The following operating systems are supported for the self-hosted runner application.
- Red Hat Enterprise Linux 7 or later
- CentOS 7 or later
- Oracle Linux 7
- Fedora 29 or later
- Debian 9 or later
- Ubuntu 16.04 or later
- Linux Mint 18 or later
- openSUSE 15 or later
- SUSE Enterprise Linux (SLES) 12 SP2 or later
- Windows 7 64-bit
- Windows 8.1 64-bit
- Windows 10 64-bit
- Windows Server 2012 R2 64-bit
- Windows Server 2016 64-bit
- Windows Server 2019 64-bit
- macOS 10.13 (High Sierra) or later
The following processor architectures are supported for the self-hosted runner application.
x64- Linux, macOS, Windows.
ARM64- Linux only.
ARM32- Linux only.
The self-hosted runner polls GitHub AE to retrieve application updates and to check if any jobs are queued for processing. The self-hosted runner uses a HTTPS long poll that opens a connection to GitHub AE for 50 seconds, and if no response is received, it then times out and creates a new long poll. The application must be running on the machine to accept and run GitHub Actions jobs.
The connection between self-hosted runners and GitHub AE is over HTTP (port 80) and HTTPS (port 443).
You must ensure that the self-hosted runner has appropriate network access to communicate with the GitHub AE URL and its subdomains.
For example, if your instance name is
octoghae, then you will need to allow the self-hosted runner to access
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. For more information, see "Managing allowed IP addresses for your organization."
You must ensure that the machine has the appropriate network access to communicate with your enterprise.
You can also use self-hosted runners with a proxy server. For more information, see "Using a proxy server with self-hosted runners."
Untrusted workflows running on your self-hosted runner pose significant security risks for your machine and network environment, especially if your machine persists its environment between jobs. Some of the risks include:
- Malicious programs running on the machine.
- Escaping the machine's runner sandbox.
- Exposing access to the machine's network environment.
- Persisting unwanted or dangerous data on the machine.
For more information about security hardening for self-hosted runners, see "Security hardening for GitHub Actions."