DEV Community

Play Button Pause Button
Brian Douglas for GitHub

Posted on • Updated on

Bring your own (self-hosted) environment for GitHub Action Workflows

You can self-host your runners with customized environments in your GitHub Actions workflows. These runners are available thanks to the fact that GitHub open-sourced their runners on GitHub of course.

GitHub logo actions / runner

The Runner for GitHub Actions πŸš€

GitHub Actions Runner

Actions Status

The runner is the application that runs a job from a GitHub Actions workflow. It is used by GitHub Actions in the hosted virtual environments, or you can self-host the runner in your own environment.

Get Started

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

Runner releases:

win Pre-reqs | Download

macOS Pre-reqs | Download

linux Pre-reqs | Download


We accept contributions in the form of issues and pull requests. The runner typically requires changes across the entire system and we aim for issues in the runner to be entirely self contained and fixable here. Therefore, we will primarily handle bug issues opened in this repo and we kindly request you to create all feature and enhancement requests on the GitHub Feedback page. Read more about our guidelines here before contributing.

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

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.

3 Steps to add your own runner

1: Head over to GitHub repo's settings and scroll down to the to add a runner.

add a runner

2: Here you will find instructions that can be copy and pasted into a virtual or on-premise environment.

runner setup

I will be using a 2018 Macbook Pro (touchbar) and show how to install self-hosted runners to leverage in a workflow in the demo.

running self-hosted runner

3: Finally, replace the runs-on: self-hosted to your action workflow.

Some things to consider

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

  • Workflow run time - Each workflow run is limited to 72 hours. If a workflow run reaches this limit, the workflow run is canceled.
  • 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 requests - You can execute up to 1000 API requests in an hour across all actions within a repository. If exceeded, additional API calls will fail, which might cause jobs to fail.
  • Job matrix - A job matrix can generate a maximum of 256 jobs per workflow run. This limit also applies to self-hosted runners.

To learn more about self-hosted runners, check out the GitHub Documentation

This is part of my 28 days of Actions series. To get notified of more GitHub Action tips, follow the GitHub organization right here on Dev. Learn how to build action with Node.js

Top comments (0)