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.
x64is available today.
x86will 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!