Skip to main content
GitHub Actions runners on AWS spot, on demand. ~10× cheaper than GitHub-hosted compute and twice as fast on warm cache.
tofu-runs-on provisions a RunsOn v3 control plane on AWS — API Gateway + Lambda + ECS/Fargate — plus the IAM and networking it needs to spin up EC2 spot runners on demand. Workflows opt in with a runs-on: label; runners launch in seconds, run the job, terminate. Cribl.Cloud Free collects OTLP telemetry for runner performance tracking.

​
What it does

  • Deploys the RunsOn control plane (ECS/Fargate + Lambda + API Gateway) on AWS
  • Spins up EC2 spot runners on demand across 3 availability zones in us-east-2
  • Falls back to on-demand instances automatically if spot capacity goes thin (spot circuit breaker)
  • Tags every runner with workflow/job/repo for AWS cost allocation
  • Optional managed WAF (enable_waf = true, on by default) protects the public ingress
  • Optional Bedrock IAM grant (enable_bedrock = true) lets CI invoke Bedrock models directly
  • Forwards OTLP runner telemetry to Cribl.Cloud Free (zero-cost observability tier)
Cost guardrails (Budgets thresholds, alarm targets, expected spend envelope) live in the repo’s own README — they’re tuned per-deployment and don’t belong in cross-repo docs.

​
How it fits

​
Post-setup hardening

After the first apply finishes and the GitHub App is registered through the ingress URL, flip enable_admin_routes = false and re-apply. That closes the public /admin and /setup routes; the runner + webhook paths keep working.

​
Getting started

1

Clone and let direnv activate the dev shell

git clone https://github.com/dryvist/tofu-runs-on.git && cd tofu-runs-on && direnv allow
2

Confirm the Terrakube workspace

The workspace receives short-lived AWS credentials from OpenBao’s native dynamic credentials path. The RunsOn license is read ephemerally from its OpenBao path.
3

Plan and apply

Run tofu plan, review the remote plan, then tofu apply. Terrakube owns state and locking.
4

Use a runner

In any workflow: runs-on: "runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/family=c7+m7". The github.run_id segment is what RunsOn correlates back to the originating workflow.

​
Migrating existing repos

The repo ships docs/migration-guide.md — the canonical per-repo playbook: which workflows benefit, which don’t, the runner-label catalog used across the org, rollout order, and how to verify a migrated workflow actually landed on a RunsOn runner instead of a GitHub-hosted one.

​
CI/CD safety

CI runs offline validation only. Credentialed plans and applies run in the Terrakube workspace, with approval and the full plan kept inside the homelab control plane.

Infrastructure overview

Where RunsOn fits in the broader AWS surface.

tofu-aws

The DR-tier AWS footprint these runners can deploy to.

Source on GitHub

Full module, migration guide, CI plan-output policy.