Orchestrata Ultimate / Deployment / Deployment sequence
Deployment sequence
This page is the map: every script, the order the scripts run in, what each produces, and where each component lands. Its companions are ship and deploy, which covers what ship does, and the deployment inventory, which holds the measured state. The hub with every deployment's verification and rollback is Deployment.
Updated 2026-10-23 from deploy/ in wt-MAP-PRECOMMIT at 8a2cb42ad and from the ~/bin launchers. Three statements on the 2026-08-30 page no longer held, and they are corrected here:
shipno longer callsdeploy.sh.- Prod is
/opt/orchestrata, not~/prod/orchestrata-ultimate. - The readiness gate is
deploy/orchestrata-kg-ready.py, run asExecStartPre. It is no longer a binary installed into~/.local/bin.
1. Every script in deploy/, and the launchers
| Script | Role | Called by | Produces |
|---|---|---|---|
ship.sh |
gate, push, merge, deploy, verify, promote | a human, or ship on PATH (the copy in /opt/orchestrata-tools/bin) |
a pushed, deployed, verified commit |
ship-merge-master.sh |
step 2b: fetch, refuse if behind, fast-forward master | ship.sh |
master at the shipped commit |
install-claude-config.sh |
user-level Claude config, the orchestrata plugin, the MCP registrations | ship.sh steps 3 and 4 (--verify), deploy.sh |
~/.claude/**, ~/.claude/VERSION, ~/.claude/mcp-registered.json |
install-tools.sh |
the project-agnostic tools | ship.sh step 3; tools-deploy (the approved launcher) |
/opt/orchestrata-tools/** |
restart-tool-instances.sh |
restart every active ast-daemon@/codemod-daemon@ instance after a tools promote |
install-tools.sh |
daemons on the new code |
retire-plain-units.sh |
remove the plain checkout-bound daemon units | install-tools.sh |
only the @ templates remain |
install-orchestrata.sh |
the prod tree /opt/orchestrata at a pinned sha (--bootstrap-only, --verify) |
operator; promotion | /opt/orchestrata, its .venv, .env (0600), VERSION |
orchestrata-kg-ready.py |
readiness gate: the KG serves reads | seven units, as ExecStartPre (--timeout 215) |
exit 0 only when the KG answers |
systemd/install.sh |
install and converge the user units | promote's assets stage, deploy.sh |
units in ~/.config/systemd/user |
deploy.sh |
one call: ~/.claude, units, tools, test fleet |
ship.sh only with ORCHESTRATA_SHIP_DEPLOY_ALL=1 |
checklist and reports/deploy-*.log |
provision_environments.sh |
a whole fleet: project, bridge, ACLs, containers, orchgraph DBs | deploy.sh (test only) |
a converged Incus environment |
orchestrata-test/provision_app_container.sh |
the app container and the product copy inside it |
provision_environments.sh |
/opt/orchestrata inside orchestrata-test:app |
install-gitlab-runner-executor.sh |
the CI runner's Incus custom executor | ship.sh step 3 |
the executor under /opt |
toolchain.sh |
load_toolchain: the compiler from env/toolchain.env |
install-orchestrata.sh, install-tools.sh |
a refused or a declared CC/CXX |
scripts/promote_env.py |
dev to test to prod promotion, gated, with rollback | ship.sh step 5 |
/opt/orchestrata at origin/master |
~/bin/tools-deploy |
run the committed install-tools.sh from a sparse worktree |
operator, Claude (pre-approved) | /opt/orchestrata-tools |
~/bin/ct-install |
codetools install, then identity and smoke, then rollback on failure | operator, Claude (pre-approved) | /opt/codetools/releases/<id> |
~/bin/hermes-deploy |
fast-forward master, run hermes deploy/install.sh |
operator, Claude (pre-approved) | /opt/hermes/releases/<commit> |
pi-harness/artifacts/pi-worker/install.sh |
pi-task release | operator | /opt/pi-worker/releases/<commit> |
2. The sequence
3. Stage, script, expected output
| # | Stage | Script | Expected output | Fails when |
|---|---|---|---|---|
| 1 | gate | ruff, black --check, check_ai_attribution.py, run_tests.py --affected, gen_plugin.py --check, check_env_fleet_agreement.py |
All checks passed!, N tests passed, 0 failed |
any check red; a run that collects 0 tests is invalid, never a pass |
| 2 | push | git push origin HEAD |
<old>..<new> HEAD -> <branch> |
pre-push blast radius red |
| 2b | master ff | ship-merge-master.sh |
fast-forwarded | branch behind origin/master |
| 3 | ~/.claude |
install-claude-config.sh |
DEPLOYED <sha> -> /home/mohamed/.claude |
ref not on origin/master; plugin pin or bytes differ |
| 3 | tools | install-tools.sh |
DEPLOYED <sha> -> /opt/orchestrata-tools |
any of the verification checks |
| 3 | unknown installer | KNOWN_INSTALLERS check |
none | an unrecognised deploy/install*.sh or deploy/deploy*.sh |
| 4 | verify | install-claude-config.sh --verify |
DEPLOYED <sha> with no mutation |
anything differs from the recorded commit |
| 5 | test record | promote_env.py test test |
a GREEN ledger row for the sha | the suite is red |
| 5 | promote | promote_env.py promote --to prod --yes --skip-ingest |
prod tree at origin/master |
verify fails (rolled back) |
| 5a | tree check | git -C /opt/orchestrata rev-parse HEAD |
equals origin/master |
the tree did not advance |
| 5b | unit check | systemctl --user list-units --plain |
N unit(s) live |
a prod unit not active; 0 live units |
| 6 | wire (wiki only) | wiki-rag-ingest |
Saved store to .../rag-store |
ingest error |
4. What lands where
| Component | Deployed to | By | Pinned |
|---|---|---|---|
| hooks, tools, agents, skills, commands, workflow | ~/.claude/{hooks,tools,agents,skills,commands,workflow} |
install-claude-config.sh (rsync --delete) |
git archive at the sha |
| orchestrata plugin | ~/.claude/plugins/cache/orchestrata/orchestrata/1.5.0 |
claude plugin install from the git remote |
gitCommitSha (a4cbc2bdfcf9 on 2026-10-23) |
| config record | ~/.claude/VERSION |
install-claude-config.sh |
commit, ref, source, deployed |
| config venv | ~/.claude/.venv |
uv on python3.14t |
free-threaded, verified |
| config backups | ~/.claude/.backup-<timestamp>/ (newest 3) |
install-claude-config.sh |
the previous subtrees |
| MCP registrations | user scope: codetools, orchestrata; record ~/.claude/mcp-registered.json |
install-claude-config.sh |
the commands resolve inside their releases |
| user units and timers | ~/.config/systemd/user/*.{service,timer} |
systemd/install.sh |
content-compared |
| tools | /opt/orchestrata-tools/{bin,lib,shim,.venv}, links in /usr/local/bin |
install-tools.sh |
/opt/orchestrata-tools/VERSION |
the product (kernel, gateway, volks, src/) |
/opt/orchestrata on the host |
install-orchestrata.sh, promote_env.py |
/opt/orchestrata/VERSION |
| product secrets | /opt/orchestrata/.env (0600) from ~/.config/orchestrata/.env |
install-orchestrata.sh |
ADR-0066 R16 |
| the product in the test fleet | /opt/orchestrata inside orchestrata-test:app |
provision_app_container.sh |
VERSION there: 22363abb2, deployed 2026-10-12 |
| codetools | /opt/codetools/releases/<id>, current, bin, VERSION |
ct-install / codetools deploy install |
VERSION via current |
| hermes-subagent | /opt/hermes/releases/<commit>, current, bin |
hermes-deploy / deploy/install.sh |
release VERSION |
| pi-task | /opt/pi-worker/releases/<commit>, current, bin/pi-task |
pi-worker install.sh |
release VERSION |
| fleet containers | Incus default (10.53.1.x, prod), orchestrata-test (10.53.2.x), orchestrata-dev (10.53.3.x) |
OpenTofu (infra/terraform), provisioning scripts |
/var/lib/orchestrata/terraform/fleet.tfstate |
5. Rules the sequence encodes
- Code is copied, never linked. The container used to bind-mount the checkout, so the kernel executed a developer's uncommitted tree.
- Only pushed commits deploy to
~/.claudeand prod. The plugin installs from the git remote, and bothinstall-claude-config.shandinstall-orchestrata.shrefuse a sha thatorigin/masterhas never seen. - Verification asks; it never trusts. Reading the deployer's own output proves only that the deployer ran (ADR-0053).
- A verifier never repairs.
install-claude-config.sh --verifyskips every mutation. - Gates run themselves. Step 5 runs the test-env record the prod gate needs, instead of printing a refusal for a human to act on.