Verifying and recovering Orgabot's own repository
Where each check for this repository runs, how to run them on your own machine, and how to verify a repair when a broken change has taken down the CLI.
Last updated
Why this page exists
Orgabot verifies and repairs its own repository with Orgabot. That leaves one failure that needs a path of its own: a merged change that breaks the CLI also breaks the tool you would use to prove the fix. This page describes the path that does not depend on the CLI, and where every check for this repository runs.
One command set
Every command a GitHub workflow in this repository runs lives in a script under scripts/ci/. The workflow step is one line that calls the script, and scripts/ci/targets.json records which workflow step runs which script. A local run calls the same files, so the hosted check and the local check cannot drift apart. A framework test fails if a workflow step goes back to an inline command or a script loses its pairing.
Edit the script, never the workflow step.
Where each check runs
scripts/ci/routing.json accounts for every registered project in this repository and for every buildable directory, registered or not:
| Job | Runs | Covers |
|---|---|---|
framework-ci.framework | locally | framework typecheck, entrypoint parity, dashboard budgets, PostgreSQL integration tests |
framework-ci.framework-tests | locally | the framework suite in four shards |
framework-ci.site | locally | site tests: docs front matter, links, images |
orgabot-skills.validate | locally | the skills installer parses, and every skill's front matter names its directory |
app.verify | on a macOS host only | the OrgaVoice Swift build and tests |
deploy.deploy | only in its hosted workflow | the site build and publish to Firebase Hosting |
The site deploy stays hosted on purpose. It signs in with a short-lived identity that GitHub issues to that workflow alone, so there is no stored credential for it anywhere, and there must never be one. The local runner refuses to run it.
The hosted Framework CI workflow runs only when someone starts it by hand, so missions on this repository do not start hosted checks.
Run the checks on your machine
From the repository root, with Node 20 or newer:
node scripts/ci/run.mjs list
node scripts/ci/run.mjs plan orgabot
node scripts/ci/run.mjs run orgabot-site
node scripts/ci/run.mjs run framework-ci.frameworkrun takes a job id or a registered project name. Steps run in order and a failing step ends its job. Matrix entries run one after another, and every entry runs even when an earlier one failed. Only one local run is allowed at a time per checkout.
The PostgreSQL step needs a throwaway database. Set ORGABOT_TEST_POSTGRES_URL to one before running framework-ci.framework. Without it the step is reported as blocked, never as passed.
Reading the result
Each run writes a record under .orgabot-run/ci/ and prints its path. The exit code is the verdict:
| Exit | Status | Meaning |
|---|---|---|
| 0 | passed | at least one step ran and every step that ran exited 0 |
| 1 | failed or timed_out | a step failed or ran past its job's time budget |
| 2 | blocked | a step needs a service you have not configured, a native job needs a different host, or nothing could run here |
| 3 | refused | you asked for a job that never runs locally, such as the deploy |
| 130 | cancelled | the run was interrupted |
node scripts/ci/run.mjs status <record> reads a record back. A record whose runner died before finishing reads as abandoned and exits 1, so a crashed run can never be mistaken for a pass. The next run cleans up any step the dead runner left behind.
Recovering from a broken change
The runner uses nothing but Node itself. It does not load the Orgabot framework, so it still works when a change has left the framework unable to compile or the CLI unable to start.
- Check out the repair in its own worktree or branch, as you would for any change.
- From that checkout, run
node scripts/ci/run.mjs run orgabot. This runs every local job for the repository and reports the deploy as hosted. - If the CLI itself is what broke, run Orgabot from a known good commit in a separate worktree and point it at the repair. A known good commit is the last commit on
mainwhose run record showspassed. Each record names the commit it verified. - Merge the repair only when the run passed. The site deploy then runs in its hosted workflow exactly as before, once per merge, so a recovery never publishes twice.