Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 44 ยท GitHub Actions in Practice

Self-Hosted Runners and Runner Costs

Learn how runner labels and groups route jobs, when to use self-hosted or larger runners, how ephemeral runners stay safe, and how billing minutes add up.

Every job in a workflow needs a machine to run on. By default that is a GitHub-hosted runner: a fresh virtual machine that GitHub starts for the job and deletes afterwards. It is zero maintenance, which is why most projects never leave it. But there are good reasons to run your own machines: special hardware (GPUs, Arm boards), access to a private network, a pre-warmed toolchain that saves minutes per job, or simply a lower bill at high volume.

This lesson explains how a job finds a runner through labels, how runners are grouped and kept safe, why public repositories and self-hosted runners are a dangerous mix, what larger runners are, and how billing minutes work so you can reason about cost. The configuration is read-only (it needs real machines). The stand-in is a label matcher with a small job queue, so you can watch jobs being routed and see why one waits forever.

How a job finds a runner

The runs-on key is a request: "give me a machine that has all of these labels."

YAML
jobs:
  build:
    runs-on: ubuntu-latest        # one GitHub-hosted label

  gpu-tests:
    runs-on: [self-hosted, linux, x64, gpu]   # all four must match

Every runner advertises a set of labels. A GitHub-hosted runner has labels such as ubuntu-latest. A self-hosted runner automatically gets self-hosted, plus labels for its operating system and architecture (such as linux, x64 or arm64), and you can add custom labels like gpu or staging-network when you register it. A job is eligible for a runner only if the runner's labels include every label in runs-on. Extra labels on the runner do not hurt; a missing one does.

If no idle runner matches, the job waits in the queue. If no runner anywhere has all the labels (a typo, or the machine is offline), the job waits until the queue timeout and then fails, which is one of the most common confusing failures. When a job sits at "Waiting for a runner to pick up this job" for a long time, compare the labels character by character.

flowchart LR
    J["job<br/>runs-on: [self-hosted, linux, gpu]"] --> Q["queue"]
    Q --> M{"which idle runner<br/>has ALL labels?"}
    M -- "runner-a: linux, x64" --> N1["no match"]
    M -- "runner-b: linux, x64, gpu" --> Y["match: job starts"]

A job only starts on a runner whose label set contains every label it asked for.

Setting up a self-hosted runner

You download the runner application from your repository's (or organization's) Settings > Actions > Runners page, which shows exact commands and a short-lived registration token. The shape of the setup is:

Terminal
# On the machine that will run jobs (values come from the Settings page)
./config.sh --url https://github.com/acme/shop \
            --token <REGISTRATION_TOKEN> \
            --labels gpu,staging-network \
            --ephemeral

./run.sh        # starts listening for jobs

The runner application makes an outbound HTTPS connection to GitHub and polls for work, so the machine does not need an open inbound port. That makes firewalls simpler, but the machine does need to be able to reach GitHub and anything your jobs download.

Registration scope matters. A runner can belong to one repository, to an organization, or (on enterprise plans) to an enterprise. Organization-level runners can be organized into runner groups: named collections with an access policy such as "only these repositories may use this group". Groups are the main tool for keeping a powerful runner (say, one inside the production network) away from every repository in the organization. A job can target a group by name:

YAML
jobs:
  deploy:
    runs-on:
      group: production-network
      labels: [linux, x64]

Ephemeral runners and a clean machine

A traditional self-hosted runner is persistent: it runs job after job on the same machine. Files, caches, Docker images, environment changes and any malicious leftovers from one job are visible to the next. That is fast, but it breaks the clean-room guarantee that GitHub-hosted runners give you for free.

An ephemeral runner (registered with --ephemeral) accepts exactly one job, then unregisters itself. Combine it with an automated way to start a fresh machine, container or VM per job and you regain clean, isolated builds. Projects such as the Kubernetes-based Actions Runner Controller, and autoscaling setups built on cloud instances, do this: they watch the queue, start a runner per queued job and delete it afterwards. This also solves capacity: you pay for machines only while jobs run.

Best practices for a persistent runner that you cannot make ephemeral:

  • Run jobs as an unprivileged user, never as root.
  • Keep the machine in a network segment with only the access jobs genuinely need.
  • Clean the workspace at the start of each job (actions/checkout does git clean by default, but other files can remain).
  • Patch the operating system and update the runner application; old runner versions stop being accepted.

Never use self-hosted runners with untrusted code

This is the most important safety rule in the lesson. A workflow executes whatever code the workflow author wrote, including code from a pull request. On a public repository, anyone can fork it and open a pull request. If your workflow runs on a self-hosted runner and is triggered by pull requests, a stranger's code runs on your machine, inside your network, with whatever that machine can reach. Fork pull requests are restricted on GitHub-hosted runners (no secrets, read-only token, a throwaway VM), but those restrictions do not protect your own hardware from a persistent runner.

So the guidance is:

  • Do not attach self-hosted runners to public repositories, or use ephemeral, isolated runners in a locked-down network if you must.
  • In organization settings, restrict which repositories can use which runner groups.
  • Require approval before workflows from outside contributors run.
  • Treat anything a self-hosted runner can reach as exposed to every workflow allowed on it. See Securing Your Pipeline for the wider picture.

Larger runners

GitHub also offers larger runners: GitHub-hosted, managed machines with more CPU cores, more memory or special architectures, which you create in the organization settings and give a name and a runner group. You target them with runs-on: my-8-core-runners. They keep the "fresh VM per job, no maintenance" benefit and add capacity (and, depending on the setup, static IP addresses useful for firewall allow-lists). They are billed per minute and are not covered by the free minutes of a plan. The choice between larger runners and self-hosted ones is usually this: larger runners cost more per minute but need no operations work; self-hosted runners can be cheaper at volume but you pay in maintenance and security effort.

Billing minutes

Cost comes from two things: how long jobs run and which machine they run on.

  • GitHub-hosted runners are billed by the minute of job run time, rounded up per job. Each plan includes a monthly allowance of minutes, and public repositories on standard runners have been free. Beyond the allowance you pay.
  • Minutes are weighted by operating system: a Linux minute costs the least, and Windows and macOS minutes cost a multiple of it. The exact multipliers and prices change, so read the current pricing page instead of memorizing numbers.
  • Runs cost money even when they fail or are cancelled, up to the point they stopped.
  • Self-hosted runners do not use the included GitHub-hosted minutes, although you pay for the machines yourself, and GitHub's policy for self-hosted usage has been adjusted over time, so check the current billing documentation.

Because cost scales with minutes, the cheapest optimizations are the same ones that make developers happier:

  1. Cancel superseded runs with a concurrency group and cancel-in-progress: true for tests.
  2. Filter by path so documentation edits do not trigger the full pipeline (see Triggers).
  3. Cache dependencies and Docker layers.
  4. Set timeout-minutes on jobs so a hung test does not burn the default six-hour limit.
  5. Run Linux unless you truly need Windows or macOS.
  6. Move slow, parallelizable work into a matrix and see Making Pipelines Fast for deeper tuning.

Stand-in: a label matcher and a queue

The simulation below holds a pool of runners with labels and a queue of jobs with runs-on requirements. It assigns jobs in order to the first idle runner whose labels contain all the required labels, and reports jobs that nobody can ever run. Time is simulated in whole "ticks", so the result is the same each time.

JS Routing jobs to runners by label

Press Run (or Ctrl + Enter) to see the console output here.

No output.

You can see gpu-bench wait for box-gpu because it is the only runner with the gpu label, even while box-a and the hosted machines are idle. The deploy job asks for gpus (a typo) and never starts. In the real product it would sit in the queue until it times out.

Stand-in: what a month of CI costs

Cost estimates are simple arithmetic, which is exactly why they are worth doing before you add a heavy matrix. The numbers below are made up for illustration; use your own run counts and the current price list.

JS A back-of-the-envelope minutes estimate

Press Run (or Ctrl + Enter) to see the console output here.

No output.

One short macOS job dominates the bill in this example. Running such a job only on the main branch, or only when the relevant paths change, is often the single biggest saving.

Performance tuning on your own machines

Self-hosted runners can beat hosted ones when you use their advantages: bake common tools and base Docker images into the machine image so jobs do not download them; keep a persistent local dependency cache (safe only if you trust every workflow on that runner); use fast local SSDs; and place runners near your artifact storage and registry. With ephemeral runners, a prebuilt image plus a warm pool of idle runners gives you both isolation and fast start.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A job has runs-on: [self-hosted, linux, gpu]. Which runner can pick it up?

    A runner must have every requested label. Extra labels are fine; a missing one disqualifies the runner.
  2. 2. What does registering a runner with --ephemeral do?

    An ephemeral runner handles a single job and is then removed, which gives each job a clean machine when combined with automated provisioning.
  3. 3. Why is it risky to attach a persistent self-hosted runner to a public repository?

    Anyone can fork a public repository and propose a workflow change. On a persistent runner, that code runs on your hardware inside your network.
  4. 4. A job has been stuck on 'Waiting for a runner' for an hour, and the YAML says runs-on: [self-hosted, linux, gpus]. Your runner is labeled gpu. What is the likely problem?

    No runner has all three requested labels, so the job waits. Compare labels character by character.
  5. 5. Which change most directly reduces the minutes billed for a workflow?

    Billing follows run time. Timeouts stop hung jobs, and cancelling outdated runs avoids paying for results nobody needs.

Summary

  • runs-on is a set of required labels; a runner qualifies only if it has all of them.
  • Self-hosted runners are registered with config.sh, connect outbound to GitHub, and can carry custom labels and belong to runner groups with access policies.
  • Ephemeral runners take one job and disappear, restoring clean-room isolation.
  • Never expose persistent self-hosted runners to untrusted code, especially fork pull requests on public repositories.
  • Larger runners are managed, bigger GitHub-hosted machines billed per minute; self-hosted runners trade money for operations work.
  • Cost is minutes times an OS weight: cancel superseded runs, filter by path, cache, set timeouts and prefer Linux.

You have now covered the practical side of GitHub Actions. Next, move on to another popular CI server: Jenkins: Controller, Agents and Jobs.