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, and ECS/Fargate. It also provisions the IAM and networking needed to spin up EC2 spot runners on demand. Workflows opt in with a runs-on: label. Runners launch in seconds, run the job, and end. 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 are tuned per-deployment and do not 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 and 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. It covers which workflows benefit, which don’t, the runner-label catalog used across the org, and rollout order. It also explains 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 (private)

The DR-tier AWS footprint these runners can deploy to. Private infrastructure. No public source.

Source on GitHub

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