Spoke Onboarding

Spoke Onboarding (Self-Service, ≤ 1 PR)

A spoke is a tinyland.dev PR-environment repo that consumes the shared GloriousFlywheel RBE / cache / runner substrate as REAPI instance_name spoke-<slug>. This page is the W4.5 / TIN-1476 contract: onboarding a spoke to GloriousFlywheel’s view of the substrate is one PR that adds one entry to a single registry, validated end-to-end by CI.

The registry

config/spoke-registry.json is the single source of truth for onboarded spokes. Each entry:

Field Constraint (enforced from the spoke-* modules)
slug ^[a-z][a-z0-9-]{1,62}$, unique → REAPI instance_name spoke-<slug>
github_repository <owner>/<repo>, unique
brand_domain a hostname, e.g. <slug>.tinyland.dev (drives *.pr.<brand_domain>)
installation_id positive integer — the spoke’s Blahaj GitHub App install id
allowed_runner_classes non-empty subset of the master runner-class enum
cache_gib integer in (0, 2048]
ttl_days positive integer
eviction_policy lru | fifo | manual
enforcement_mode deny | warn | dry-run

The constraints are not duplicated in the validator — they are read directly from the spoke-* OpenTofu modules (spoke-runner-binding, spoke-cache-quota, spoke-state-namespace, spoke-blahaj-app-install), so the registry can never accept a spoke the modules would reject at apply time.

The contract test

tests/spoke_onboarding_contract.sh (script: scripts/validate-spoke-registry.py) validates every registry entry against the module contract and runs a synthetic-new-spoke self-test (a valid spoke that must pass plus a battery of invalid mutations that must each be rejected). It runs:

  • locally via just spoke-onboarding-contract-check, and
  • in CI as part of the Validate job (Validate RBE proof contracts).

A green check therefore means the spoke is contract-valid.

Onboard a spoke

  1. Get the spoke’s Blahaj GitHub App installation id: gh api /app/installations.
  2. Open a PR using the spoke-onboarding PR template (.github/PULL_REQUEST_TEMPLATE/spoke-onboarding.md, i.e. ?template=spoke-onboarding.md) and add one entry to config/spoke-registry.json.
  3. Run just spoke-onboarding-contract-check; fix any reported issue.
  4. Merge. The spoke’s own repo separately applies the five spoke-* modules to stand up its state namespace, DNS, cache quota, runner binding, and Blahaj install.

Scope

This delivers the GloriousFlywheel-side single-PR onboarding + contract. The per-spoke OpenTofu apply (the spoke repo’s own tofu/main.tf calling the five modules) and the cross-org scaffold live in tinyland-inc/site.scaffold. Wiring the registry into the deployed gf-reapi-cell config (GF_REAPI_QUOTAS / GF_REAPI_EXECUTOR_POOLS templated from registry entries) is downstream operator work.

GloriousFlywheel