Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
 
2022-11-28 (latest)

 

About self-hosted runners

In this article

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

About self-hosted runners

A self-hosted runner is a system that you deploy and manage to execute jobs from GitHub Actions on GitHub.com. For more information about GitHub Actions, see "Understanding GitHub Actions."

自托管运行器比 GitHub 托管的运行器提供更多的硬件、操作系统和软件工具控制。 使用自托管运行器，可以创建自定义硬件配置，以满足处理能力或内存需求，以运行更大的作业，在本地网络上安装可用的软件，并选择 GitHub 托管的运行器未提供的操作系统。 自承载运行器可以是物理设备、虚拟设备、在容器中、在本地或在云中。

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.

运行器机器使用 GitHub Actions 自托管运行器应用程序连接到 GitHub。 GitHub Actions 运行器应用程序是开源的。 可以参与 runner 存储库并在其中提交问题。 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 if it has not connected to GitHub Actions for more than 14 days.
An ephemeral self-hosted runner is automatically removed from GitHub if it has not connected to GitHub Actions for more than 1 day.

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:

  • Receive automatic updates for the operating system, preinstalled packages and tools, and the self-hosted runner application.
  • 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:

  • Receive automatic updates for the self-hosted runner application only, though you may disable automatic updates of the runner. For more information about controlling runner software updates on self-hosted runners, see "Autoscaling with self-hosted runners." 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.

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

Autoscaling your self-hosted runners

You can automatically increase or decrease the number of self-hosted runners in your environment in response to the webhook events you receive. For more information, see "Autoscaling with self-hosted runners."

Usage limits

There are some limits on GitHub Actions usage when using self-hosted runners. These limits are subject to change.

  • 工作流运行时间 - 每次工作流运行时间限制为 35 天。 如果工作流程运行时间达到此限制，其运行将被取消。 此时间段包括执行持续时间以及等待和审批所用的时间。
  • 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 请求 - 一个存储库中所有操作在一小时内最多可以执行 1000 条对 GitHub API 的请求。 如果超出请求数，其他 API 调用将失败，这可能导致作业失败。
  • Job matrix - 作业矩阵在每次工作流程运行时最多可生成 256 个作业。 此限制适用于 GitHub 托管和自托管运行器。
  • 工作流运行队列 - 每个存储库在 10 秒的间隔内可排队的工作流运行不超过 500 个。 如果工作流程运行达到此限制，该工作流程运行将会终止而无法完成。

Workflow continuity for self-hosted runners

如果 GitHub Actions 服务暂时不可用，则在触发后 30 分钟内没有排队时，运行的工作流程运行将被丢弃。 例如，如果触发了一个工作流程，而 GitHub Actions 服务在 31 分钟或更长时间内不可用，则该工作流程将不会被处理。

Supported architectures and operating systems for self-hosted runners

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

Linux

  • 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

  • Windows 7 64-bit
  • Windows 8.1 64-bit
  • Windows 10 64-bit
  • Windows Server 2012 R2 64-bit
  • Windows Server 2019 64-bit

macOS

  • macOS 10.13 (High Sierra) or later

Architectures

The following processor architectures are supported for the self-hosted runner application.

  • x64 - Linux, macOS, Windows.
  • ARM64 - Linux, macOS, Windows (currently in beta).
  • ARM32 - Linux.

Communication between self-hosted runners and GitHub

The self-hosted runner connects to GitHub to receive job assignments and to download new versions of the runner application. The self-hosted runner uses an HTTPS long poll that opens a connection to GitHub 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.

Since the self-hosted runner opens a connection to GitHub.com, you do not need to allow GitHub to make inbound connections to your self-hosted runner.

You must ensure that the machine has the appropriate network access to communicate with the GitHub hosts listed below. Some hosts are required for essential runner operations, while other hosts are only required for certain functionality.

Note: Some of the domains listed below 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 below will remain constant.

Needed for essential operations:

github.com
api.github.com

Needed for downloading actions:

codeload.github.com

Needed for runner version updates:

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

Needed for uploading/downloading caches and workflow artifacts: 

*.blob.core.windows.net

Needed for retrieving OIDC tokens:

*.actions.githubusercontent.com

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

*.pkg.github.com
ghcr.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. For more information, see "Managing allowed IP addresses for your organization" or "Enforcing policies for security settings in your enterprise" in the GitHub Enterprise Cloud documentation.

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

For more information about troubleshooting common network connectivity issues, see "Monitoring and troubleshooting self-hosted runners."

Self-hosted runner security

建议仅将自托管运行器用于私有仓库。 这是因为，通过创建在工作流中执行代码的拉取请求，公共存储库的分支可能会在自托管运行器计算机上运行危险代码。

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