Air traffic control for AI coding

Nool with GitHub Actions

Nool does not replace CI. It records the local reason and impact of a change before GitHub Actions validates the pushed result.

  • Use CI for tests, builds, and deployment checks.
  • Use Nool before push for intent and impact analysis.
  • Attach CI outcomes to already-governed transitions.

Keep CI as validation

Nool does not replace CI. Use CI for build, test, and deployment checks after governed local transitions.

Preserve local evidence

Record the local reason for a change before pushing so CI results attach to an already-explained transition.

nool propose --path <file> --intent "Prepare CI-safe change"

After a GitHub merge button: advance the mirror pointer

A squash, rebase or merge-commit merge of a Nool side branch moves `main` on GitHub but not `refs/nool/mirror/main`, which lags until some replica runs `nool pull` and `nool push`. A small workflow can be that replica: on every push to `main` it installs the released `nool`, pulls the merge so Nool reconciles it, and moves only the pointer. It stops if `main` carries a commit no knot accounts for, so the pointer never passes foreign history.

  • `NOOL_CI_KEY` is a repository secret holding the runner's signing seed (`openssl rand -hex 32`); without it the job should skip cleanly.
  • Push only the pointer, never `nool push`: `nool init` on a fresh clone makes a local configuration commit that must not leave the runner.
  • If the pull reports a foreign commit, a replica runs `nool bridge adopt` before the pointer can move.
  • `nool pr merge` and `nool push` already move the pointer with `main`; the workflow finds nothing to do after them.
# .github/workflows/nool-mirror-advance.yml (core step)
on:
  push:
    branches: [main]
permissions:
  contents: write
concurrency:
  group: nool-mirror-advance
  cancel-in-progress: false
# … after actions/checkout with fetch-depth: 0, skip unless
# refs/nool/mirror/main lags $GITHUB_SHA, then:
curl -fsSL https://www.nool.dev/nool-install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
export NOOL_IDENTITY_KEY="$NOOL_CI_KEY" NOOL_NO_DAEMON=1
nool init --from-git main --skip-discovery
nool pull origin 2>&1 | tee pull.log
grep -q "foreign commit" pull.log && exit 1
git push --force-with-lease="refs/nool/mirror/main:$POINTER" origin \
  "$GITHUB_SHA:refs/nool/mirror/main" "$GITHUB_SHA:refs/nool/git-mirror"