Adoption Quickstart

Adoption Quickstart

Deploy GloriousFlywheel on your cluster and enroll your first repo in 4 steps.

Prerequisites

  • A Kubernetes cluster (RKE2, EKS, GKE, k3s, etc.)
  • kubectl configured for your cluster
  • OpenTofu >= 1.6.0
  • A GitHub App (for GitHub adapter) or runner registration token (GitLab/Forgejo)

Step 1: Deploy Core Substrate

Clone the repo and deploy the ARC controller:

git clone https://github.com/tinyland-inc/GloriousFlywheel.git cd GloriousFlywheel

Copy and edit the example config

cp config/organization.example.yaml config/organization.yaml

Edit with your cluster details

Deploy the ARC controller (one per cluster)

just tofu-init arc-runners just tofu-plan arc-runners just tofu-apply arc-runners

Step 2: Enroll Your Forge

GitHub (Primary)

  1. Create a GitHub App at your org level

  2. Install it on the repos or org you want to serve

  3. Set the app credentials in your .env:

    GITHUB_APP_ID=… GITHUB_APP_INSTALLATION_ID=… GITHUB_APP_PRIVATE_KEY_PATH=…

  4. Configure honey.tfvars (or your cluster’s tfvars) with your org URL:

    github_config_url = ”https://github.com/your-org”

GitLab (Compatibility)

See Forge Adapter Matrix

Forgejo/Codeberg (Proof Path)

See Forge Adapter Matrix

Step 3: Choose Runner Pools

Default pools:

Label CPU/Mem Use Case
your-org-docker 2/4Gi General CI
your-org-nix 4/8Gi Nix builds
your-org-nix-heavy 8/16Gi Rust + Nix

Configure in your tfvars extra_runner_sets map.

Step 4: Attach Caches

Attic (Nix binary cache)

just tofu-init attic just tofu-plan attic just tofu-apply attic

Runner pods automatically receive ATTIC_SERVER and ATTIC_TOKEN env vars.

Bazel Remote Cache (optional)

Set BAZEL_REMOTE_CACHE in runner pod environment via tfvars.

Step 5: Use In Workflows

In your repo’s .github/workflows/*.yml:

jobs: build: runs-on: your-org-nix # or your-org-docker, your-org-nix-heavy steps:

  • uses: actions/checkout@v4
  • run: nix build .#default

Validating Enrollment

Run the enrollment check:

./scripts/benchmark/canary-enrollment-check.sh your-org/your-repo your-org-nix

The checker uses both repo runner inventory and recent successful job-label evidence, because scale-to-zero or shared runners may not appear in the repo inventory endpoint while idle.

Measuring Performance

Run the benchmark harness:

./scripts/benchmark/runner-benchmark.sh your-org-nix nix-build

GloriousFlywheel