deploy-multidev

name

deploy-multidev

description

Deploy an arbitrary branch to a Pantheon multidev (review/feature) environment for ONE E-Heza site — build from the selected branch and push it to a named multidev env. Trigger when the user wants to deploy a branch to a multidev/review/feature/test env, spin up or update a review environment, or push a non-`main` branch to Pantheon for testing. NOT for production — use the `deploy-release` skill for the full `main` → Live release. Drives the safe steps itself and pauses for the interactive or production-affecting commands.

Deploy to Multidev (E-Heza → Pantheon)

This skill deploys a chosen git branch to a Pantheon multidev (review/feature) environment for one single site. It's the low-risk path: it only updates an isolated multidev env — never Dev/Test/Live, and it never cuts a release.

Releasing to production (main → Dev → Test → Live + GitHub release)? Use the deploy-release skill instead.

Shared reference (site table, RoboFile internals, one-time Pantheon clone setup, troubleshooting): .claude/skills/_deploy-common/deploy-reference.md — read it before running.

Execution model — who runs what

You (Claude) drive every step except the deploy command itself — that one needs a human to review the change-set.

• 🟢 You run (via Bash on the host): git prep, all preflight checks, ddev restart, ddev auth ssh, ddev gulp publish, and the terminus auth check/login. (The deploy command itself runs the post-deploy cc/updb/fra/uli.) None of these are destructive, and on a normal ddev setup they're non-interactive (SSH keys are already in the agent, TERMINUS_MACHINE_TOKEN is in the env). Only hand ddev auth ssh to the user if it actually prompts for a key passphrase.
• 🔴 User runs — only ddev robo deploy:pantheon <env>. It prints a git status of the Pantheon clone and an interactive "Commit changes and deploy?" prompt, so a human must review the change-set before confirming. Offer it tee'd to a log so you read the outcome yourself instead of asking for a paste:

  ddev robo deploy:pantheon <env> 2>&1 | tee /tmp/deploy-<env>.log
  

  Once it returns, Read /tmp/deploy-<env>.log to confirm the push and the auto-run cc all/updb/uli.

One site per run.

Site → config mapping

Look up the chosen site's EHEZA_SITE, PANTHEON_NAME, and Pantheon clone dir (server/.pantheon-<PANTHEON_NAME>) in the site table in .claude/skills/_deploy-common/deploy-reference.md.

⚠️ Two distinct Burundi sites (vhw, uvl) share EHEZA_SITE=burundi but have different PANTHEON_NAME. Always pin the exact Pantheon site with the user — never assume "burundi".

---

Step 0 — Gather inputs (ask the user)

Use AskUserQuestion (and free text where needed) to collect:

1. Target site — Rwanda / Burundi-vhw / Burundi-uvl / Somalia. Resolve to EHEZA_SITE + PANTHEON_NAME via the shared site table.
2. Source branch to deploy — any git branch (default: the current branch). This is what gets built; it is independent of the multidev env name.
3. Target multidev env name — the existing Pantheon multidev environment to deploy into (e.g. review-x). The build is pushed to the Pantheon branch of the same name.

Confirm the plan back in one line (site, PANTHEON_NAME, source branch → multidev <env>) before proceeding.

Step 1 — Preflight checks (🟢 you run; all must pass)

Report a ✅/❌ checklist. Stop and surface any ❌.

1. Config matches the target site. Read .ddev/config.local.yaml; confirm EHEZA_SITE and PANTHEON_NAME equal the chosen site's values.
   • If not: tell the user to fix .ddev/config.local.yaml (the mandatory restart in Step 2 loads the new values). Wrong PANTHEON_NAME pushes to the wrong Pantheon site.
2. Source branch exists & working tree clean. The branch is real, and the eheza-app working tree has no tracked changes (the deploy aborts on tracked changes; untracked files like .ddev/ are ignored):

   git rev-parse --verify <source-branch>   # exists locally...
   git ls-remote --heads origin <source-branch>   # ...or on origin
   git status -s -uno                        # expect empty (no tracked changes)
   

3. Pantheon clone exists, clean, and has the target multidev branch. The deploy runs git checkout <env> inside the clone and aborts with "Specified branch <env> does not exist" if that branch isn't there:

   git -C server/.pantheon-<PANTHEON_NAME> status -s -uno              # clean
   git -C server/.pantheon-<PANTHEON_NAME> fetch origin                # refresh
   git -C server/.pantheon-<PANTHEON_NAME> rev-parse --verify <env> 2>/dev/null \
     || git -C server/.pantheon-<PANTHEON_NAME> rev-parse --verify origin/<env>
   

   • If the multidev branch is missing: the env must exist on Pantheon first. Tell the user to create the multidev environment in the Pantheon dashboard (or via terminus), then in the clone git fetch origin && git checkout <env>. Without it, the deploy can't proceed.
4. Terminus authenticated. ddev auth ssh covers the git push to Pantheon, but the deploy's post-deploy terminus remote:drush (cc all / updb / uli) has separate auth — without it the deploy pushes code and then fails with "You are not logged in", leaving the env on new code with a stale cache/registry:

   ddev exec terminus auth:whoami   # expect an email, not "You are not logged in"
   

   • If not logged in: run ddev terminus-auth (logs terminus in from TERMINUS_MACHINE_TOKEN, or ddev terminus-auth <token>). If the token isn't set yet, add TERMINUS_MACHINE_TOKEN to .ddev/config.local.yaml (see shared reference) and ddev restart.

Step 2 — Local prep

1. 🟢 You run: git checkout <source-branch> && git pull (pull only if it tracks a remote).
2. Restart DDEV — always, deciding reinstall first. Ask the user (AskUserQuestion) whether to reinstall the project on this restart — default No:
   • No (default): ensure the post-start hook in .ddev/config.local.yaml is in its default state (only - exec-host: ddev client-install active; everything below commented). No reinstall.
   • Yes: uncomment the entire commented post-start block (see Reinstall-on-restart toggle in the shared reference) so the restart runs site-install + migrations + feature flags for the selected $EHEZA_SITE. Re-comment afterward if future restarts shouldn't reinstall. Then run ddev restart (local-only and safe to run; the reinstall answer is the confirmation for the destructive local-DB wipe a reinstall performs).
3. 🟢 You run: ddev auth ssh — injects SSH keys so the deploy can push to Pantheon. (Hand to the user only if it prompts for a key passphrase.)
4. 🟢 You run: ddev gulp publish — minified production build of the Elm client from the checked-out branch. Long (allow several minutes); let it finish before deploying.

Step 3 — Deploy to the multidev env

🔴 User runs (the one human-review step) — offer it tee'd to a log so you read the outcome yourself:

ddev robo deploy:pantheon <env> 2>&1 | tee /tmp/deploy-<env>.log

Tell the user explicitly: at the "Commit changes and deploy?" prompt, review the printed git status of the Pantheon clone and confirm only if the change-set is exactly what they expect. When it returns, Read /tmp/deploy-<env>.log to verify the push + auto-run cc all/updb/fra/uli — don't ask for a paste.

What this does automatically (so you don't double-run it): rsyncs the build into the clone, checks out the <env> branch, commits + pushes to it, then runs on that multidev env cc all (twice), updb -y, fra -y, cc all, and uli. It touches only that multidev env.

Step 4 — Post-deploy / verify

The deploy already ran cc all/updb/fra/cc all/uli itself — confirm in the log. So just verify: open the uli login link from the deploy output (or the multidev URL https://<env>-<PANTHEON_NAME>.pantheonsite.io) and smoke-test. Run any manual steps the change introduced (new variables, migrations).

---

Wrap-up

Report: site, PANTHEON_NAME, source branch, multidev <env> deployed to, and that fra was run. No Test/Live promotion and no release happen here — for that, switch to deploy-release. Note any preflight ❌ that blocked progress.