Skip to content
compiler.dev
Start free

What Is a Runner in GitHub Actions?

Last updated

A runner in GitHub Actions is the machine, virtual or physical, that executes one job of a workflow. GitHub picks a runner whose labels match the job's runs-on value, runs the job's steps on it, and reports the result back.

How it works

When a workflow is triggered, each job is queued with its runs-on labels. A runner that has all of those labels and is idle picks the job up. The runner downloads the actions your steps need, runs each step in order, streams logs to GitHub, and then reports success or failure.

Jobs do not share a machine. Two jobs in the same workflow run on two different runners, so files from one job are not visible to the next unless you pass them as an artifact or cache.

There are three common kinds of runner:

  • GitHub-hosted: virtual machines GitHub creates for each job and deletes afterward. Labels like ubuntu-latest, windows-latest, macos-latest.
  • Larger runners: GitHub-hosted machines with more CPU and RAM, billed per minute at a higher rate.
  • Self-hosted runners: machines you or a provider run, matched by custom labels.

Each runner is also a billing unit. Every minute a job holds a runner counts toward your CI minutes.

Example

jobs:
  test:
    runs-on: ubuntu-latest        # GitHub-hosted, 2-core
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

  build:
    runs-on: [self-hosted, Linux, compiler-ci]   # matched by labels
    steps:
      - uses: actions/checkout@v4
      - run: make build

Common mistakes

  • Assuming state persists. A hosted runner is wiped after every job. Anything you want later must be cached or uploaded.
  • Typos in labels. If no runner matches the labels, the job sits queued until it times out. Check spelling and capitalisation.
  • Using the biggest runner by default. Bigger machines only help if your job is actually CPU bound. Measure first with the runner size picker.
  • Ignoring the job time limit. Jobs have a maximum run time; see GitHub Actions time limits.

If your jobs are slow, a faster runner is the cheapest fix because it needs no workflow changes. The faster runners guide compares options, and compiler.dev runs your existing jobs on 8 vCPU machines for one line of YAML. See pricing.

Related terms

FAQ

Is a runner the same as a workflow?

No. A workflow is the YAML file that defines what to do. A runner is the machine that does it. One workflow can use many runners, one per job.

Can one runner run several jobs at once?

A standard runner runs one job at a time. Parallel jobs get separate runners. Some self-hosted setups start several runner processes on one host, but each still runs a single job.

What does ubuntu-latest give me?

A GitHub-hosted Linux virtual machine. Its size depends on the repository type and plan, so check GitHub's current runner reference before assuming specs.

Related