Skip to content

Documentation

One product, two engines

Managed GitHub Actions runners and Terraform-compatible runs. The sections below are in reading order, starting with the quickstart.

QuickstartPricing
diff
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ghwarp-2vcpu-ubuntu-2404
     steps:
       - uses: actions/checkout@v4
       - run: make test

Getting started

What this is, how to connect it, and moving your first workflow over.

  • QuickstartMove a GitHub Actions job onto our runners: create an account, install the GitHub App on an organisation or a personal account, add a card, and change one line.
  • What runners.io isOne product with two execution engines — managed GitHub Actions runners and Terraform-compatible runs — on one meter and one bill.
  • Connect your accountInstall the GitHub App for CI runners, and issue a token for infrastructure runs. The two halves connect separately.
  • Moving from GitHub-hosted runnersThe label mapping table, what to check before widening the change, and what a mistyped label does: refused on your Runners page, or left waiting by GitHub.

Runners

Managed GitHub Actions runners: the labels, and what a job gets.

  • Runner labelsThe exact strings a runs-on accepts, the machine each one gets you, and why a misspelled label or one paired with self-hosted is refused, with the fix named on the job page.
  • The runner imageUbuntu 24.04 with what GitHub's own ubuntu-24.04 image carries: Docker, the language runtimes, cloud CLIs, passwordless sudo and the tool cache.
  • LimitsHow long one job may run, how many of your jobs run at once and how to lower that, and what a job cannot do.
  • Static IPA dedicated address your builds leave from, for allowlists. How to ask for one, and what Requested and Active mean.
  • SecurityOne virtual machine per job, no inbound connection from the internet or other jobs, cache credentials scoped to one repository, what of your code and builds we see, and who may change a sticky disk.

Caching

Three mechanisms for three different kinds of slow.

  • The Actions cacheactions/cache works unmodified and is included. What a job may read and write, and the two eviction policies.
  • The Docker layer cacheTurn it on with one line. An OCI registry beside the fleet that BuildKit pushes layers to, so an unchanged layer is not rebuilt on the next job.
  • Sticky disksA sticky disk is a block device kept between jobs for one repository, for build tools with their own on-disk caches. Asking for one, using it, and guarding for its absence.
  • Protecting a sticky diskWhich builds may change a repository's sticky disk, the credentials we refuse to keep, the record of what changed it, resetting it, and protected repositories.

Observability

Watching a job, stopping one, its test results, and getting run state into your own systems.

  • Watching a jobWhere a job's logs, timings and states appear, and how to tell a slow build apart from a long wait for a machine.
  • Cancelling a jobThe Cancel job button on a job's page, and cancelling a whole run on github.com: what each stops, what is billed, and what GitHub shows afterwards.
  • Test resultsThe Tests tab, read from the JUnit XML your build already writes: what we read, the bounds on it, and the optional comment on a pull request.
  • NotificationsSend CI jobs, billing changes and sticky-disk events to a signed webhook, an email address, Slack or Microsoft Teams, and check a webhook came from us.

Administration

Who is in your organisation, what each of them may do, and how they sign in.

  • Members and rolesThe four roles and what each may do, inviting people, handing the organisation over, and closing it.
  • Sign-in and securityEmail and password or GitHub sign-in, the password rules, two-factor authentication with recovery codes, and requiring it for everybody.

Billing

One meter and one invoice, and how the arithmetic works.

  • How you are billedOne meter and one invoice across both engines, what is measured, and why every amount is an integer of micro-dollars.
  • Spending alerts and the spending capA spending alert sends an email and stops nothing; the spending cap stops new CI jobs. How to set each, who may, and the day of usage the cap can lag by.
  • Invoices and paymentsAdding the card, the monthly invoice and the usage CSV, what happens day by day when a payment fails, and the details printed on an invoice.

Infrastructure runs

Terraform-compatible plans and applies, with state kept here, and moving from HCP Terraform.

  • Pointing a configuration at usThe cloud block, the hostname that serves discovery, and what a workspace holds — state versions, variables and their precedence.
  • The engine that executes your runsHosted runs execute OpenTofu, and there is no setting that changes it. What that licensing constraint does and does not mean for your configuration.
  • Dynamic provider credentialsAuthenticate a run to GCP, AWS or Azure with no static key. The issuer, the metadata endpoints, and the one subject-format difference from HCP Terraform.
  • Moving state from HCP TerraformMigrating existing state with terraform init -migrate-state, from a cloud block, the remote backend, or another backend entirely.
  • Notifications for infrastructure runsPush run state transitions to a webhook, Slack or Google Cloud Pub/Sub, using the Terraform Cloud notifications API.

API reference

The Terraform Enterprise API we implement, and where we differ.

  • The Terraform APIWe implement much of the Terraform Enterprise API. This is where we differ from it, including the endpoint that answers 501 on purpose.
  • API tokensUser and organisation tokens for the Terraform API: where they come from, how to give one to the CLI, and how to take one back.

Help

How to reach us, what response time to expect, and what we do not promise.

  • TroubleshootingA job that does not start, a job we stopped, a cache that never hits, an empty sticky disk: what the job page says, and the page that has the fix.
  • How we support youThe one channel we support through, the response time we aim for, and — just as important — what a small team does not promise.
  • The status pageWhat runners.io/status shows for the runners and Terraform runs, how a check reads Unknown rather than Operational, and what the page does not show.