Deploy

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.yml carries 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.

1. The topology is decided, not assumed — Phase 0, once, out loud. Everything downstream depends on it.
2. No deploy without approval — show the method/host/domain/port plan, wait for approval.
3. Always back up before the swap — timestamped into releases/; if the backup fails, abort.
4. Always a health gate after the swap — HTTP + process; if it doesn't pass, automatic rollback.
5. Keep the last 3 versions — don't delete them all.
6. Don't deploy to prod without knowing the target — host/deploy_path/domain must be approved.
7. Verify SSH first — if you can't connect, fail fast.
8. Don't expose the port directly — the app binds to 127.0.0.1, outward only through the proxy.
9. SSL is mandatory when there's a domain — always set it up unless ssl is explicitly false.
10. Never rebuild to roll back (B) — promote the previous artefact. A rebuild is a different artefact.
11. The platform's own status is not the health gate (B) — verify from where a user stands.
12. Rolling back code does not roll back a migration — settle the schema question before the deploy.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: crewforth
• Source: crewforth/crewforth
• License: MIT
• Homepage: https://crewforth.com/

Install and usage instructions live in the source repository linked above.