About self-hosted runners

You can host your own runners and customize the environment used to run jobs in your GitHub Actions workflows.

In this article

About self-hosted runners

Note: Currently, you can add a self-hosted runner to a single repository. The ability to add and manage self-hosted runners for an entire organization will come in a future release.

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, container, on-premises, or in a cloud.

The GitHub Actions runner application is open source. You can contribute and file issues in the runner repository.

For more information about installing and using self-hosted runners, see "Adding self-hosted runners" and "Using self-hosted runners in a workflow."

Differences between GitHub-hosted and self-hosted runners

GitHub-hosted runners offer a quicker, simpler way to run your workflows, while self-hosted runners are a highly configurable way to run workflows in your own custom environment.

GitHub-hosted runners:

  • Are automatically updated.
  • Are managed and maintained by GitHub.
  • Provide a clean instance for every job execution.
  • Use free minutes on your GitHub plan, with per-minute rates applied after surpassing the free minutes.

Self-hosted runners:

  • 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.

Requirements for self-hosted 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 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.
  • If you want to run workflows that use JavaScript actions, you must install Node.js on your runner machine.

Supported operating systems for self-hosted runners

The following operating systems are supported for the self-hosted runner application.

Linux

  • Red Hat Enterprise Linux 7
  • CentOS 7
  • 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

  • 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

  • macOS 10.13 (High Sierra) or later

Communication between self-hosted runners and GitHub

The self-hosted runner application communicates information about jobs to GitHub. The application must be running on the machine to accept and run GitHub Actions jobs.

The self-hosted runner application communicates with GitHub using the HTTPS protocol for inbound and outbound traffic. You must ensure that the machine has the appropriate network access to communicate with GitHub.

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" or "Enforcing security settings in your enterprise account".

You can also use self-hosted runners with a proxy server. For more information, see "Using a proxy server with self-hosted runners."

Self-hosted runner security with public repositories

We recommend that you do not use self-hosted runners with public repositories.

Forks of your public repository can potentially run dangerous code on your self-hosted runner machine by creating a pull request that executes the code in a workflow.

This is not an issue with GitHub-hosted runners because each GitHub-hosted runner is always a clean isolated virtual machine, and it is destroyed at the end of the job execution.

Untrusted workflows running on your self-hosted runner poses 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.

Ask a human

Can't find what you're looking for?

Contact us