Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.jacobpevans.com/llms.txt

Use this file to discover all available pages before exploring further.

GitHub Actions runners on AWS spot, on demand. ~10× cheaper than GitHub-hosted compute and twice as fast on warm cache.
terraform-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

TriggerRuntime
runs-on=... label in any workflow runs-on: clauseA fresh EC2 spot instance per job, terminating on completion

​
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 --bare https://github.com/JacobPEvans/terraform-runs-on.git terraform-runs-on/.git && cd terraform-runs-on && git worktree add main main && cd main && direnv allow
2

Supply credentials via aws-vault + Doppler

Profile is tf-runs-on; Doppler config is inherited from iac-conf-mgmt/prd. RUNSON_LICENSE_KEY is mapped into license_key via terragrunt.hcl.
3

Bootstrap

aws-vault exec tf-runs-on -- doppler run -- terragrunt init && terragrunt apply. The bootstrap creates its own S3 state + DynamoDB lock table on first run.
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

PR plans are posted via tf-summarize as a redacted structural summary — resource addresses + change actions only. Resolved attribute values never appear in PR comments. Merge to main triggers an OIDC-authenticated terragrunt apply (gated by the production GitHub Environment approval). See docs/ci-plan-output-policy.md for the full rationale.

Infrastructure overview

Where RunsOn fits in the broader AWS surface.

terraform-aws

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

Source on GitHub

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