What it is: A runner is the actual server — a real or virtual computer — that executes the steps of a job in a GitHub Actions workflow. When a workflow says “run this command” or “use this action,” the runner is the machine where that command genuinely runs and produces a real result.

Why it exists: A workflow file is only a description of what should happen — it contains no computing power of its own. Something has to provide an actual operating system, disk space, memory, and processing power to carry out each step for real. A runner exists to be exactly that: the concrete execution environment underneath the abstract instructions written in a workflow file.

Where it’s used: Every single job in every GitHub Actions workflow runs on some runner — there’s no such thing as a job without one. What varies is where that runner comes from: a machine GitHub itself provides and manages, or one an individual or organization sets up and maintains themselves.

Practical example: A team’s workflow includes a job that needs to install a specific programming language, download the project’s code, run its test suite, and report the results. All of this genuinely happens — files are actually downloaded, processes actually run, memory is actually used — on a runner machine that GitHub allocates the moment the job starts, and discards once it finishes.

Before automation platforms like GitHub Actions existed, teams needing to automatically test or build their software after every code change typically had to set up and maintain their own dedicated servers for that purpose — installing an operating system, keeping it updated, securing it, and making sure it always had enough capacity for however much automation the team needed to run. This was a real, ongoing operational burden, separate from the team’s actual software work.

The concept of a runner — specifically, a runner that GitHub itself can provide on demand — solves this by shifting that operational burden onto GitHub. Instead of a team owning and maintaining a server, GitHub allocates a brand-new, ready-to-use machine the instant it’s needed, and removes it the instant the job is done, so no one has to think about server maintenance at all for standard automation needs.

The core problem runners solve: automation needs somewhere real to execute, but teams generally don’t want the ongoing burden of owning and maintaining dedicated servers just for that purpose. Runners — especially GitHub-hosted ones — provide that execution environment on demand, without the maintenance responsibility.

A GitHub-hosted runner is a virtual machine that GitHub creates, on its own infrastructure, specifically for one job, and then permanently destroys once that job finishes. Because it’s created fresh every single time, it always starts in an identical, predictable, clean state — no leftover files, no configuration drift from a previous job, and no risk that something one job did accidentally affects a completely unrelated later job.

Choosing which operating system a job runs on is simply a setting in the workflow file — the same job’s steps can even be run once per operating system at the same time using the matrix pattern covered in a related guide on jobs, letting a team verify their software works correctly everywhere it needs to.

flowchart LR
    A["Job is ready to start"] --> B["GitHub provisions a fresh virtual machine"]
    B --> C["Runner registers itself and waits for instructions"]
    C --> D["Repository code and any needed setup are downloaded"]
    D --> E["Each step executes on the runner, in order"]
    E --> F["Job finishes (success or failure)"]
    F --> G["Runner machine is permanently destroyed"]
    

Step by step, in plain language: first, once a job is ready to begin — meaning any jobs it depends on have already succeeded — GitHub provisions a brand-new virtual machine specifically for it, matching whichever operating system the workflow requested. Second, that machine starts up, registers itself with GitHub as ready to receive work, and waits briefly for its assigned job. Third, the runner typically downloads a copy of the relevant repository code, since almost every job needs it, along with anything else the job’s steps require. Fourth, each step in the job runs on that machine, one at a time, in the exact order defined in the workflow file. Fifth, once every step has run — whether they all succeeded or one of them failed — the job is considered finished. Finally, and importantly, GitHub permanently destroys that specific virtual machine; it’s never reused for a future job, even one from the exact same repository moments later.

Notice that at no point does one job’s runner hand off directly to another job’s runner — they’re entirely separate machines, and any information passed between jobs travels through explicit mechanisms like artifacts, never through the runners themselves persisting or communicating directly.

A self-hosted runner is a machine — physical or virtual, on your own premises or your own cloud account — where you personally install and run GitHub’s runner software, registering it with your repository or organization so GitHub can send it jobs, exactly as it would send jobs to one of its own machines. From a workflow’s perspective, the steps run the same way either way; what changes is who owns, configures, and maintains the underlying machine.

Every runner, whether GitHub-hosted or self-hosted, is identified by one or more labels — short tags describing something about it, such as its operating system or a specific capability. A workflow’s job specifies which labels it requires, and GitHub matches the job to any available runner carrying those labels. This is exactly how a workflow requests “a Linux machine” versus “a Windows machine” from GitHub’s own hosted fleet, and it works the same way for self-hosted runners with custom labels of their own.

Organizations with many self-hosted runners often further organize them into runner groups — named collections of runners with shared access rules, letting an administrator control which repositories or teams within the organization are allowed to use which specific runners, an important control when some runners have access to particularly sensitive internal systems.

The core trade-off to internalize: GitHub-hosted runners trade some flexibility and network reach for near-zero operational burden, while self-hosted runners trade operational responsibility for full control, custom hardware, and access to private systems. Many organizations use both at once — GitHub-hosted for routine, general-purpose jobs, and self-hosted specifically where private network access or special hardware is genuinely required.

Because a self-hosted runner doesn’t automatically wipe itself between jobs, as covered in Chapter 6, teams that use them often deliberately configure the machine to reset to a clean state after every job anyway, specifically to recover some of the isolation guarantee that GitHub-hosted runners provide by default. This might mean running each job inside its own disposable container or virtual machine on top of the self-hosted infrastructure, rather than executing jobs directly on a long-lived, shared machine.

Runner groups and labels, covered in Chapter 8, are also a genuine security tool, not just an organizational convenience — carefully restricting which repositories or teams can use a runner with access to sensitive internal systems prevents an unrelated, lower-trust project from accidentally or maliciously reaching infrastructure it has no legitimate need to touch.

The Hosted-by-Default Pattern starts every new workflow on GitHub-hosted runners, and only introduces self-hosted infrastructure once a specific, genuine need arises — private network access, special hardware, or a proven cost concern at real scale — rather than self-hosting preemptively.

The Scoped-Runner-Group Pattern deliberately organizes self-hosted runners into groups matching trust boundaries, so a runner with access to sensitive production systems is only ever available to the specific, small set of repositories that genuinely need it.

The Container-Isolated Self-Hosted Pattern runs every job inside a fresh, disposable container on top of self-hosted infrastructure, deliberately recreating the clean-slate guarantee of GitHub-hosted runners even on machines the team manages itself.

Common anti-patterns to avoid: the Never-Reset Self-Hosted Runner (a long-lived machine that accumulates leftover files and configuration drift across many jobs over time); the Overprivileged Shared Runner (one runner, with broad access to sensitive systems, made available to every repository in an organization regardless of actual need); and the Unnecessary Self-Hosting pattern (maintaining your own runner infrastructure for standard, general-purpose jobs that GitHub-hosted runners would have handled perfectly well, taking on maintenance burden for no real benefit).

Common mistakes beginners make: assuming a self-hosted runner resets itself between jobs the way a GitHub-hosted one does; registering a self-hosted runner on a public repository without considering who might be able to trigger jobs on it; and self-hosting runners for ordinary, general-purpose work that GitHub-hosted runners would have handled just as well, taking on unnecessary maintenance for no real gain.