Justfile Commands

The project Justfile provides recipes for common development, build, and deployment tasks. Run just --list to see all available recipes or just <recipe> --help for usage details.

Proxy

Recipes for the compatibility SOCKS5 proxy path. The preferred operator model is direct or tailnet-private access to the honey cluster via ~/.kube/kubeconfig-honey.yaml and context honey.

Development

General development workflow recipes.

Nix

Recipes for Nix-based builds and maintenance.

OpenTofu

Infrastructure-as-code recipes for planning and applying changes. Each recipe takes a stack name argument (e.g., attic, gitlab-runners, runner-dashboard).

Note: tofu-plan expects a {ENV}.tfvars file (default dev.tfvars) in the stack directory. ENV=dev and ENV=prod are logical deployment environments and can both map to the same physical cluster, such as honey. For arc-runners, the local operator path also auto-includes {ENV}-policy.tfvars before local overrides and {ENV}-extra-runner-sets.tfvars when present, so the committed ARC baseline and additive lanes like tinyland-nix-heavy join the same local plan/apply path. For overlay deployments, create your tfvars there or use the per-stack Justfiles directly.

Current backend note:

• just tofu-init <stack> follows the active backend family declared in that stack’s backend.tf
• all four active stacks now use backend "s3" on the environment-owned honey state path
• TOFU_BACKEND_CONFIG_FILE, TOFU_BACKEND_CONFIG_DIR, and TOFU_BACKEND_S3_* are now the primary local init paths across those active stacks
• TF_HTTP_* remains compatibility-only for legacy or archived HTTP-backend repair paths
• when a stack flips to backend "s3", the same root entrypoint can use a matching backend HCL file or the live TOFU_BACKEND_S3_* environment path
• if config/backends/<stack>-<env>.hcl exists, just tofu-init <stack> now treats it as the implicit local default without requiring TOFU_BACKEND_CONFIG_DIR
• the post-#209 target direction remains environment-owned S3-compatible state on honey

just tofu-preflight <stack> is the shortest local check before init. It validates:

• config/organization.yaml
• the resolved ENV cluster context
• the resolved kubeconfig path and local context presence
• {ENV}.tfvars for the chosen stack
• for arc-runners, the baseline {ENV}-policy.tfvars file when present
• for arc-runners, the optional {ENV}-extra-runner-sets.tfvars file when present
• the currently configured backend-init path
• when the active family is s3, the TOFU_BACKEND_S3_* environment path and state-key resolution

just tofu-backend-audit runs the same preflight logic across all four active stacks and prints the current backend mode, backend ref, and first blocking reason for each one. This is the fastest way to confirm whether Slice 1 is blocked on local setup drift or on one shared backend-authority decision.

just tofu-state-authority-proof is the live runtime check for the proven RustFS-backed S3 candidate on honey. It reads the cluster-managed credentials secret, opens a bounded port-forward to attic-rustfs-openebs, runs signed aws s3api reads, and prints the current bucket and object-key view. Use this when the question is “does the environment-owned S3 state authority actually exist and answer now?” rather than “can the current local stack init path run?”

just tofu-state-contract <stack> prints the current state name and the proven ENV=dev honey S3 key when one is locked. Use this before writing or reviewing backend files so you do not silently fall back to the wrong object name during the remaining cutovers.

just tofu-state-audit checks the known legacy GitLab state paths for the four active stacks individually and reports which ones actually exist, along with their Terraform version and serial. This replaces the older blind project-level state listing assumption, which does not work against the current GitLab API shape used by the archived legacy mirror.

just arc-runtime-audit inspects the live ARC runtime on the active cluster context and prints:

• which runner sets are live
• the current CPU and memory envelope for each lane
• the current nodeSelector and tolerations
• the live ATTIC_SERVER value when present
• whether tinyland-nix-heavy exists yet
• whether the heavy lane is actually targeted at sting
• active runner job pod placement by scale set label
• a kubectl top nodes snapshot when metrics are available

Use this after an arc-runners rollout to confirm the live cluster matches the repo contract instead of trusting stale runtime state.

just honey-runner-workdir-audit inspects the default honey runner hosts (honey-am-1 and honey-am-2, or hosts you pass explicitly) over SSH and reports:

• visible repo workdirs under the runner _work/ root
• stale .git/index.lock files
• sample non-writable files that can break actions/checkout
• sample ownership mismatches
• largest workspace directories

Use this for checkout failures that happen before downstream repo code runs, such as EACCES unlink errors in persistent _work/* paths.

just honey-runner-workdir-remediate <host> <repo> [--mode unlock|remove] [--apply] is the bounded remediation pair for that audit:

• dry-run by default
• scoped to one repo workdir on one runner host
• unlock restores owner write bits so the tree can be inspected or removed
• remove restores owner write bits and deletes the contaminated repo workdir

Use this only after the affected runner has been stopped or drained. See Honey Runner Workdir Contract for the lifecycle boundary and escalation rules around that flow.

just honey-runner-workdir-reconcile sits between those two commands. It scans the selected honey runner hosts, classifies contaminated repo workdirs, and then:

• prints a bounded remediation plan when exactly one repo workdir is dirty on a host
• stops at escalation when more than one repo workdir is contaminated on the same host
• can run the safe single-repo remediation automatically when used with --apply --confirm-drained

Use this as the default operator entrypoint after a checkout-failure audit when the question is “which hosts can I recover safely right now without widening cleanup past the contract boundary?”

just honey-runner-checkout-triage starts one step earlier when you already have the failing GitHub Actions run id or run URL. It:

• pulls the run metadata and full log with gh
• extracts honey host and repo-workdir targets from the checkout failure lines
• runs the bounded host reconcile surface for those hosts
• previews the targeted bounded repo remediation for the extracted workdir
• can apply that bounded remediation only when --apply --confirm-drained is supplied and the reconcile result still says each host is a safe one-repo candidate

Examples:

just honey-runner-checkout-triage \
  https://github.com/Jesssullivan/acuity-middleware/actions/runs/24525417273

just honey-runner-checkout-triage \
  --repo Jesssullivan/acuity-middleware \
  24525417273 \
  --parse-only

Use --parse-only when you want the repo-owned run/log archaeology without touching the remote honey hosts from the current shell.

just orgwide-enrollment-scoreboard is the live reporting path for the orgwide enrollment contract. It scans the configured owners from config/orgwide-enrollment-scoreboard.json, inspects recent non-fork repos with workflows through the GitHub API, and prints:

• real runner authority on the default branch
• template consumers by mode
• named authority exceptions when non-default branches are still relevant

Use just orgwide-enrollment-scoreboard --format json when you want to feed the result into another report or compare the current live census with the earlier research baselines.

just orgwide-enrollment-queue is the follow-on execution surface for that scoreboard. It combines the live scoreboard with config/orgwide-enrollment-queue.json and prints:

• claim-protection repos that still make platform wording fragile
• template-contract cleanup repos that should stay visible but not be confused with runner enrollment
• platform-prereq repos whose promotion story is blocked on missing shared runner reachability or similar authority debt
• real promotion candidates that are ready for actual rollout energy
• repos that should stay hosted and out of the active migration metric

Use just orgwide-enrollment-queue --format json when you want the queue in a machine-readable form for issue updates or PM rollups.

For arc-runners, local tofu-plan, tofu-refresh, and tofu-destroy also accept GHCR_USERNAME and GHCR_TOKEN. When those are set, the root operator path passes them through as ghcr_username and ghcr_token so OpenTofu can create or rotate an explicitly configured GHCR pull secret. The current honey runtime does not use imagePullSecrets on the ARC lanes by default, so public-image plans can leave those variables unset without causing artificial drift.

just tofu-backend-scaffold <stack> creates the expected local backend file in config/backends/. Once that file exists, it becomes the implicit local default for just tofu-init <stack>. Preflight will still fail until you replace the example placeholder values with a real current backend endpoint and credentials.

just tofu-backend-scaffold-s3 <stack> writes the same local filename, but with the migration-prep S3-compatible example instead of the active HTTP one. That is preparation only. Preflight will reject that file until the matching stack backend.tf also switches to the s3 backend family.

If you are repairing a legacy generic HTTP backend path and already have the coordinates exported in your shell, just tofu-backend-materialize-http <stack> will capture those TF_HTTP_* values into the local backend file for that stack.

If you already have the target-direction S3-compatible coordinates exported in your shell, just tofu-backend-materialize-s3 <stack> will capture those TOFU_BACKEND_S3_* values into the local backend file for that stack. That still does not change the active stack backend family by itself.

For the current proven honey baseline, that helper now uses the live dev key map instead of assuming <stack>-<env>.tfstate:

• attic -> attic/terraform.tfstate
• arc-runners -> arc-runners/terraform.tfstate
• gitlab-runners -> tinyland-infra/gitlab-runners/terraform.tfstate
• runner-dashboard -> tinyland-infra/runner-dashboard/terraform.tfstate

If you are preparing a different environment or a non-baseline layout, set TOFU_BACKEND_S3_KEY explicitly before running the helper.

If you still rely on legacy GitLab HTTP state and you know the real gitlab.project_id, just tofu-backend-materialize-gitlab-legacy <stack> will write the local backend file for you from config/organization.yaml plus TF_HTTP_PASSWORD. That is compatibility-only; the four active stacks on current main now use backend "s3".

Bazel

Build system recipes for the Bzlmod-based build.

Kubernetes

Cluster inspection and debugging recipes. All commands route through the proxy when HTTPS_PROXY is set, but the preferred path is direct or tailnet-private access to honey.

For the current Tinyland on-prem rollout, the cache-oriented helper defaults now use the live nix-cache namespace.

App (Runner Dashboard)

Recipes for the SvelteKit runner-dashboard application.

Runners

Shortcut recipes for the GitLab Runner infrastructure stack (gitlab-runners).

Cache Platform

Shortcut recipes for the cache platform stack (tofu/stacks/attic/). This stack deploys the complete Nix binary cache platform: CNPG Operator, PostgreSQL cluster, MinIO Operator, MinIO tenant, Attic API server, GC worker, DNS records, cache init job, warming CronJob, and optional Bazel remote cache.

The stack directory is named attic for state backend compatibility, so just tofu-deploy attic also works.

Docs

Recipes for the documentation site.

TeX

Recipes for building the research document.

Related

• Environment Variables — variables consumed by these recipes
• Configuration Reference — organization.yaml used by tofu recipes
• Pipeline Overview — CI equivalents of local recipes