Downstream Migration Checklist

Use this guide when a downstream GitHub Actions repo is moving onto the current GloriousFlywheel runner and cache contract.

This is the shortest honest checklist for the tranche-1 migration lane tracked in #210.

Who This Is For

• org repos that want to use shared tinyland-* runner labels
• user-owned canary repos such as XoxdWM
• downstream repos that want GloriousFlywheel composite actions without manual platform archaeology

Current Downstream Contract

Shared runner labels:

Composite actions:

Default stance:

• prefer shared runner labels first
• use composite actions when you want the cache/runtime setup packaged for you
• do not depend on legacy Jesssullivan/GloriousFlywheel/... paths

Checklist

1. Inventory your workflows. Identify which jobs are general CI, Nix builds, or container builds.

2. Map each job to one shared runner label.

   For Nix jobs, choose explicitly between:

   • tinyland-nix for the ordinary 8Gi baseline lane
   • tinyland-nix-heavy for recurring memory-heavy jobs when that additive lane is deployed

3. Decide whether the repo needs composite actions. If plain shell steps are enough, labels alone are acceptable.

4. Remove or replace any stale personal upstream references. Prefer tinyland-inc/GloriousFlywheel/.github/actions/...@main.

5. Validate cache expectations. tinyland-nix gets Attic defaults; tinyland-docker and tinyland-nix get Bazel cache defaults on self-hosted runners.

6. Validate self-hosted Nix bootstrap. For raw nix commands on tinyland-nix, use DeterminateSystems/determinate-nix-action@v3 or the nix-job composite action instead of assuming Nix is preinstalled on the runner forever.

7. Run one canary workflow on the shared runner path before converting the full repo.

8. Keep a rollback path ready. A job can temporarily return to ubuntu-latest or another GitHub-hosted runner while the shared-runner contract is being stabilized.

Canonical Consumer Pattern

This is the reference downstream shape for a repo that wants one general CI job and one Nix job:

name: CI

on:
  push:
  pull_request:

jobs:
  test:
    runs-on: tinyland-docker
    steps:
      - uses: actions/checkout@v4
      - uses: tinyland-inc/GloriousFlywheel/.github/actions/docker-job@main
        with:
          command: make test

  build:
    runs-on: tinyland-nix
    steps:
      - uses: actions/checkout@v4
      - uses: tinyland-inc/GloriousFlywheel/.github/actions/nix-job@main
        with:
          command: nix build .#default
          push-cache: "false"

Why this is the reference pattern:

• it uses stable shared labels
• it uses the current public GloriousFlywheel action path
• it avoids assuming push-cache credentials are present by default

Verification

After the first shared-runner migration:

1. confirm the job lands on the expected runner label
2. confirm the workflow still passes without hidden repo-local assumptions
3. confirm Nix jobs see the expected cache environment
4. compare runtime against the previous GitHub-hosted baseline

Rollback

If the shared-runner path is not ready yet:

• move the affected job back to ubuntu-latest
• keep the repo-specific workflow change small and reversible
• leave the rest of the repo on the previous runner path until the shared contract is fixed

See Also

• GitHub Actions Runners
• Runner Selection Guide
• GitHub App Adoption
• GloriousFlywheel First Tranche Repo Contracts 2026-04-16