Since we announced GitHub Actions support for CI/CD In August, self-hosted runners have been one of the most eagerly anticipated updates—and it’s now available in beta.

Advantages of self-hosted runners

Self-hosted runners offer a number of advantages when the hosted virtual environments don’t meet all your needs:

  • Your environment, your tools: Your workflow may require software that’s proprietary, expensive, or difficult to install on virtual environments. Or maybe you need more flexibility with platforms like a different Linux distribution or architecture. Self-hosted runners allow you to create the perfect environment for your workflow. See the product documentation for details on supported platforms and architectures.
  • Any size machine or configuration: Self-hosted runners allow you to use the specific hardware you need, whether that’s more memory or cores, or different configurations like GPUs or ARM-based CPUs. 
  • Secure access and networking: We received feedback that securely networking to and from hosted virtual environments can be challenging. Self-hosted runners make this easier by allowing you to more easily enable access to firewalled on-premises resources or RDP into the environment that’s running your job.
  • Large workload support: In some cases, your jobs benefit from using techniques like incremental source fetches, package caches, or other configurations that require persistence. Self-hosted runners give you the opportunity to persist whatever you like for your jobs and not be subject to the six-hour time-out in hosted virtual environments.

Downloading and configuring the runner

To get started, you must be an administrator to change any configurations. Once logged in, navigate to the Actions tab from your repository’s settings. You should see a new section where you can manage your self-hosted runners.

Click the Add runner button, select the platform you’re targeting, and then follow the sequence of shell commands to download, configure, and run your runner.

During configuration, the CLI will prompt you to answer a few questions, including naming the runner, and determining the output directory for any jobs.

Once your runner is successfully configured and listening for jobs, it will display as idle which means you’re ready to update your workflow.

Using the runner

To support using self-hosted runners in your workflows, we’ve expanded the experience of using the runs-on key. When registering your self-hosted runners, they’re each given a read-only label self-hosted which you can use with runs-on. Here’s an example:

# Use Any available Self-hosted runners connected to repo
runs-on: self-hosted

In addition to the self-hosted label, each runner is also given read-only labels that identify its platform and architecture.

    • Platforms: windows, linux, macos
    • Architectures: x64 is available today. ARM64, ARM32, and x86 will be available shortly after Actions GA

Since self-hosted runners have more than one label, you can provide a single label, or array of labels to runs-on. These allow you to filter the runners to only those that include the specific label values you specify. Here’s an example where we filter labels:

# Use an ARM32 linux based self-hosted runner
runs-on: [self-hosted, linux, ARM32]

# Use only macos based based self-hosted runners
runs-on: [self-hosted, macos]

Adding your own custom labels to self-hosted runners is currently not supported, but we hope to release it in a future iteration.

Get started today

We know that flexibility and control are critical when it comes to your CI/CD setup, so we’re excited to add self-hosted runners as a new way to use GitHub Actions. You can start adding your own self-hosted runners through the Actions tab in your repository’s setting page, and we look forward to hearing what other features you need!

Learn more about self-hosted runners for GitHub Actions

Tags: