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 self-hosted runners to repositories. 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. You can use any machine as a self-hosted runner as long at it meets these requirements:

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.

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.
  • Depending on your usage, can be more cost-effective than GitHub-hosted runners.

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. You must ensure that the machine has the appropriate network access to communicate with GitHub.

Using a proxy server with self-hosted runners

If you need a self-hosted runner to communicate via a proxy server, the self-hosted runner application uses proxy configurations set in the following environment variables:

  • https_proxy: Proxy URL for HTTPS traffic. You can also include basic authentication credentials, if required. For example:

    • http://proxy.local
    • http://192.168.1.1:8080
    • http://username:password@proxy.local
  • http_proxy: Proxy URL for HTTP traffic. You can also include basic authentication credentials, if required. For example:

    • http://proxy.local
    • http://192.168.1.1:8080
    • http://username:password@proxy.local
  • no_proxy: Comma separated list of hosts that should not use a proxy. Only hostnames are allowed in no_proxy, you cannot use IP addresses. For example:

    • example.com
    • example.com,myserver.local:443,example.org

The proxy environment variables are read when the self-hosted runner application starts, so you must set the environment variables before configuring or starting the self-hosted runner application. If your proxy configuration changes, you must restart the self-hosted runner application.

On Windows machines, the proxy environment variable names are not case-sensitive. On Linux and macOS machines, we recommend that you use all lowercase environment variables. If you have an environment variable in both lowercase and uppercase on Linux or macOS, for example https_proxy and HTTPS_PROXY, the self-hosted runner application uses the lowercase environment variable.

Using a .env file to set the proxy configuration

If setting environment variables is not practical, you can set the proxy configuration variables in a file named .env in the self-hosted runner application directory. For example, this might be necessary if you want to configure the runner application as a service under a system account. When the runner application starts, it reads the variables set in .env for the proxy configuration.

An example .env proxy configuration is shown below:

https_proxy=http://proxy.local:8080
no_proxy=example.com,myserver.local:443

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