Best VPS for GitHub Actions Self-Hosted Runners

How to choose a VPS for GitHub Actions self-hosted runners: sizing, provider checklist, ephemeral setup, security rules and how to verify the runner is online.

Published

At a glance

Last reviewed
Versions referenced
actions/checkout@v7
Reading time
5 min read

Code samples are not run in a live repository. See our editorial standards.

On this page

Pick the provider that bills by the hour, has an API or Terraform provider, and offers a region close to your artifact storage. DigitalOcean, Vultr, Hetzner Cloud and Linode all meet those requirements. The differences that matter are price per vCPU, included transfer and the CPU type, and those change often, so read each provider’s pricing page before you commit.

A self-hosted runner is a machine you deploy and manage to execute GitHub Actions jobs. A VPS is a good fit when you need more CPU or RAM than a standard GitHub-hosted runner, a persistent cache, or access to private resources. It is a poor fit if you need a clean machine for every job and don’t want to build the automation for it. For a related walkthrough, see How to Choose a Hosting Provider for GitHub Actions Deploys.

What to look for in a VPS

Choose by workload, not by brand. These are the criteria that decide whether a runner stays fast and affordable.

Criterion What to check Why it matters
Hourly billing Plans billed per hour, not only per month Lets you create a VM per job or per day and pay only for the time used
API, CLI and Terraform provider Official provider and CLI Needed to create and destroy runners automatically
CPU type Shared vs. dedicated vCPU Shared vCPUs give variable build times; dedicated ones are more predictable
RAM and disk At least enough for your largest build plus Docker images Out-of-memory kills and No space left on device are the most common causes of flaky self-hosted jobs
Region Close to your registry, cache and artifact storage Most job time goes to pulling dependencies and pushing artifacts
Included transfer Allowance and overage price Docker pulls and artifact uploads count against it
Firewall and private networking Provider-level firewall, private network or VPC Lets you keep the runner off the public internet except for outbound traffic
Snapshots or custom images Ability to bake a base image Cuts startup time for ephemeral runners

Check pricing, plan names and transfer allowances on the provider’s own pricing page. They change, and a number copied into an article goes stale.

Provider comparison

All four providers below offer the capabilities in the table. Verify plan details on their pricing pages.

Provider Terraform provider Official CLI Notes
DigitalOcean digitalocean/digitalocean doctl Droplets, Cloud Firewalls and VPCs
Vultr vultr/vultr vultr-cli Cloud Compute, firewall groups and private networks
Hetzner Cloud hetznercloud/hcloud hcloud Servers, firewalls and private networks
Linode (Akamai) linode/linode linode-cli Linodes, Cloud Firewalls and VLANs

If you have no existing preference, start with the provider whose data center is closest to your registry and storage. Run your real pipeline on it for a week before you decide.

Size the machine

Start with 2 vCPUs and 4 GB of RAM for typical build-and-test jobs, then adjust from observed usage. Add swap or RAM if jobs are killed during linking or Docker builds. Use at least 40 GB of disk if you build container images, because layers and caches accumulate. For a related walkthrough, see GitHub Actions Docker Build and Push with Layer Caching.

Run one job at a time per runner. A runner process executes a single job at once, so a bigger VM only helps if you run several runner instances on it, and those instances then share the same filesystem and Docker daemon.

Provision a VPS with Terraform

This example creates a DigitalOcean Droplet. The same pattern applies to the other providers with their own resource types.

terraform {
  required_providers {
    digitalocean = {
      source = "digitalocean/digitalocean"
    }
  }
}

variable "do_token" {
  type      = string
  sensitive = true
}

variable "ssh_key_fingerprint" {
  type = string
}

provider "digitalocean" {
  token = var.do_token
}

resource "digitalocean_droplet" "runner" {
  name     = "gh-runner"
  image    = "ubuntu-22-04-x64"
  region   = "nyc1"
  size     = "s-2vcpu-4gb"
  ssh_keys = [var.ssh_key_fingerprint]
}

output "runner_ip" {
  value = digitalocean_droplet.runner.ipv4_address
}

Run terraform init, then terraform apply. Confirm the machine exists with doctl compute droplet list, which shows the droplet with status active. Choose the region and size from the provider’s current list, since available slugs change.

Install and register the runner

Register the runner as a non-root user. Get the download URL and a registration token from your repository’s Settings > Actions > Runners > New self-hosted runner page. Registration tokens expire quickly, so generate one right before you use it.

mkdir actions-runner && cd actions-runner
# Download and extract the runner package using the commands
# shown on the "New self-hosted runner" page, then:
./config.sh \
  --url "$REPO_URL" \
  --token "$RUNNER_TOKEN" \
  --labels vps \
  --unattended
sudo ./svc.sh install
sudo ./svc.sh start

Set REPO_URL to your repository or organization URL and RUNNER_TOKEN to the token from that page. The svc.sh script installs the runner as a service so it survives reboots.

Target the runner from a workflow with its labels:

jobs:
  build:
    runs-on: [self-hosted, linux, vps]
    steps:
      - uses: actions/checkout@v7
      - run: make test

Verify the runner is online

Open Settings > Actions > Runners in the repository or organization. The runner appears with the status Idle when it is connected and waiting for jobs. On the VPS, run sudo ./svc.sh status in the runner directory to confirm the service is active.

Then trigger a workflow that uses runs-on: [self-hosted, linux, vps]. The runner status changes to Active while it runs the job. If the runner shows Offline, check that the VM has outbound HTTPS access to GitHub and that the service is running.

Security and isolation

Never attach a self-hosted runner to a public repository. Anyone who can open a pull request can try to run code on your machine through a workflow. Use self-hosted runners with private repositories, or restrict which repositories and workflows can use them through runner groups.

Apply these rules on any provider:

  • Allow outbound HTTPS (port 443) and block all other inbound traffic except SSH from your own IP addresses. The runner connects out to GitHub, so it needs no inbound ports.
  • Put the VM in a private network or VPC if it talks to internal services.
  • Don’t store long-lived cloud credentials on the VM. Pass secrets through GitHub secrets and prefer short-lived tokens.
  • Don’t mount the Docker socket into untrusted containers. It gives root access to the host.

Use ephemeral runners for clean builds

A persistent runner keeps files, caches and installed tools between jobs. Leaked credentials and stale state carry over from one job to the next. To avoid that, register the runner with --ephemeral. It then accepts one job and is removed from GitHub afterward.

./config.sh \
  --url "$REPO_URL" \
  --token "$RUNNER_TOKEN" \
  --ephemeral \
  --labels vps \
  --unattended
./run.sh

An ephemeral runner only helps if something creates a fresh VM or process for each job and destroys the old one. Build a snapshot or custom image with the runner dependencies preinstalled, and use the provider’s API to create and delete machines. Without that automation, the runner stays unregistered after its first job.

Common problems

  • Jobs queue forever. No online runner matches the labels in runs-on. Compare the labels shown in Settings > Actions > Runners with your workflow.
  • Runner goes offline after a reboot. The service was not installed. Run sudo ./svc.sh install and sudo ./svc.sh start.
  • Builds fail with No space left on device. Docker images and caches filled the disk. Prune with docker system prune on a schedule, or use ephemeral VMs.
  • Registration fails. The token expired. Generate a new one from the runner settings page and rerun ./config.sh.

Spotted an error? Report it on our Contact page and see our editorial standards for how we correct articles.