Deploy
Trigger phrases: "deploy", "push to the server", "to the server", "onto the server", "build on the server", "install on the VPS", "ship it to the server", "go to production", "to production", "go live"
A deploy has a single idea, and it does not depend on where you are deploying: make the new version live in a way you can undo. Keep the previous version reachable until the new one has proved itself; if it fails the health gate, go back to the old one and nobody notices.
Two topologies implement that idea differently, and mixing them is where deploys go wrong. On a host you manage, "reversible" means the previous release still sits on disk and the swap is a pointer you can move back. On a platform that manages the host for you, "reversible" means the previous artefact is still addressable and you re-point the environment at it — you do not rebuild it. Phase 0 picks the branch; everything after follows.
Crewforth adaptation (local, .claude/): Any backend runtime (Docker recommended). Deploy requires explicit approval (§4.4); a backup before every swap and a health gate after are mandatory. If
.deploy.ymlcarries server credentials it goes into.gitignore. §4 Prohibitions apply.
Phase 0 — Which topology
Answer before anything else, because the rest of the skill forks here. Ask if it is not obvious; do not infer it from the language or the framework.
| A · Self-managed host | B · Managed platform | |
|---|---|---|
| You have | SSH to a machine you own or rent | an API/CLI, and no shell on the box |
| A release is | a directory on that host | an immutable artefact (image digest, build id, bundle) |
| "Deploy" means | put the files in place and restart | promote an existing artefact to an environment |
| Rollback means | move the pointer back to the previous directory | re-point the environment at the previous artefact |
| Owned by | references/topology-a.md (phases 1–5) |
references/topology-b.md (phases B1–B4) |
Signals for B: the platform builds from a push, or the runtime is described as containers/functions/dynos/pods that you do not administer. Signals for A: you are given a host, a user and a port. A Kubernetes cluster is B when a controller reconciles it from a manifest, and A only if you are genuinely hand-placing files on nodes.
If both are in play — a managed platform in front, a self-managed worker behind — run the branches separately and gate each on its own health check. One approval does not cover two topologies.
Checklist (A · self-managed host)
- Topology decided (Phase 0)
- Runtime + deploy method determined
- Config taken from
.deploy.yml/the user, SSH verified - Reverse proxy + (if there is a domain) SSL in place
- Running version backed up to
releases/ - User approved the deploy, new version deployed
- Health gate passed (otherwise automatic rollback performed)
- If requested, single-command scripts (
deploy.sh/adopt.sh) generated
Checklist (B · managed platform)
- Topology decided (Phase 0)
- Artefact built once and addressed immutably (digest / build id, not a moving tag)
- Which artefact is in which environment is recorded
- Config and secrets injected per environment, not baked into the artefact
- User approved the promotion to this environment
- Health gate passed from OUTSIDE — not the platform's own status
- Previous artefact still addressable, and the migration question settled before the deploy
The phases — read ONE branch
Phase 0 picked it; loading both is the mistake this skill opens with.
- A · self-managed host →
references/topology-a.md: runtime/method detection,.deploy.yml+ SSH, reverse proxy and SSL, the backup-then-swap for Docker and bare-metal, the health gate, the rollback. - B · managed platform →
references/topology-b.md: build once and address it immutably, promote without rebuilding, health-gate from outside the platform, roll back by re-pointing.
The invariant rules at the end of this file hold on both, and they are the half that must not be read from a reference file: they are what an approval is checked against.
Single-command scripts (optional)
After a successful deploy, ask whether to generate project-specific deploy.sh / adopt.sh (single-command
deploy/update). Derive the steps from the real project (package.json / Dockerfile / Makefile / compose), never a
generic template. Full guidance + what each script contains: references/scripts.md.
Invariant rules
These hold on BOTH branches; where the mechanism differs, the rule does not. 0. The topology is decided, not assumed — Phase 0, once, out loud. Everything downstream depends on it.
- No deploy without approval — show the method/host/domain/port plan, wait for approval.
- Always back up before the swap — timestamped into
releases/; if the backup fails, abort. - Always a health gate after the swap — HTTP + process; if it doesn't pass, automatic rollback.
- Keep the last 3 versions — don't delete them all.
- Don't deploy to prod without knowing the target — host/deploy_path/domain must be approved.
- Verify SSH first — if you can't connect, fail fast.
- Don't expose the port directly — the app binds to
127.0.0.1, outward only through the proxy. - SSL is mandatory when there's a domain — always set it up unless
sslis explicitlyfalse. - Never rebuild to roll back (B) — promote the previous artefact. A rebuild is a different artefact.
- The platform's own status is not the health gate (B) — verify from where a user stands.
- Rolling back code does not roll back a migration — settle the schema question before the deploy.