@catladder/cli 5.6.0 → 5.7.0

package/dist/skills/catladder-cli/references/commands.md

@@ -86,6 +86,19 @@ pin the review apps of a merge request (disable their auto-stop) by adding the p
 - `mr` (positional): merge request IID (defaults to the open MR of the current branch)
 - `--pipeline`: trigger a merge-request pipeline so the pin takes effect immediately
 
+## `catladder mr review-app-off [mr]`
+
+stop deploying the review apps of a merge request: switches the reviewApps label off (opt-in: removes it, opt-out: adds the skip label). Running review apps stay until the MR closes or they auto-stop
+
+- `mr` (positional): merge request IID (defaults to the open MR of the current branch)
+
+## `catladder mr review-app-on [mr]`
+
+deploy the review apps of a merge request: switches the reviewApps label on (opt-in: adds it, opt-out: removes the skip label) and triggers a pipeline, since gitlab doesn't start one for label changes
+
+- `mr` (positional): merge request IID (defaults to the open MR of the current branch)
+- `--pipeline`: trigger a merge-request pipeline so the review apps deploy now
+
 ## `catladder mr unpin [mr]`
 
 unpin the review apps of a merge request — the auto-stop timer re-arms with the next deploy

package/dist/skills/catladder-config/SKILL.md

@@ -104,6 +104,10 @@ Key concepts:
     affects both). The object form separates the axes:
     `inherit: { config: "dev" }` inherits config only,
     `inherit: { config: "dev", secrets: "dev" }` both.
+- **Review apps**: top-level `reviewApps: { deploy, label, skipLabel,
+  drafts }` decides whether merge/pull requests deploy their review
+  apps — every MR/PR (default), opt-in or opt-out by label, or on
+  request; and what drafts run. See the `catladder-pipelines` skill.
 - **Pipelines**: `pipelines: { gitlab: true, github: true }` selects
   which CI systems get generated files. Options objects instead of
   `true` allow per-pipeline settings (e.g. `runnerVariables`,

package/dist/skills/catladder-deploys/SKILL.md

@@ -46,6 +46,12 @@ is `auto`.** Set per component or per environment (`env.<name>.deploy`).
 `waitFor: ["otherComponent"]` (experimental) makes a deploy wait for
 another component to deploy first.
 
+Whether merge/pull requests deploy review apps at all (opt-in/opt-out
+by label, drafts, deploy on request for all components at once) is the
+project-wide top-level `reviewApps` config — see the
+`catladder-pipelines` skill. With it set, per-component `when` of the
+review env is ignored.
+
 ## Environment lifetimes
 
 Review apps auto-stop after 1 week, dev environments after 4 weeks

package/dist/skills/catladder-pipelines/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: catladder-pipelines
-description: Understanding and debugging the CI/CD pipelines catladder generates (GitLab CI and GitHub Actions) — pipeline triggers, stages, environments, caching, job images, releases, and infrastructure drift. Use when investigating failing CI jobs, when asked why/when a job runs, when changing caching or job behavior, when deployments misbehave, or when a review app stopped/expired or should be kept alive (pinning). Triggers on "pipeline", "CI job", "gitlab-ci", "workflow", "deploy failed", "cache", "release", "auto-stop", "review app stopped", "pin review app", "keep review app".
+description: Understanding and debugging the CI/CD pipelines catladder generates (GitLab CI and GitHub Actions) — pipeline triggers, stages, environments, caching, job images, releases, and infrastructure drift. Use when investigating failing CI jobs, when asked why/when a job runs, when changing caching or job behavior, when deployments misbehave, when a review app should (not) be deployed for a merge/pull request (opt-in/opt-out labels, drafts, deploy on request), or when a review app stopped/expired or should be kept alive (pinning). Triggers on "pipeline", "CI job", "gitlab-ci", "workflow", "deploy failed", "cache", "release", "auto-stop", "review app stopped", "pin review app", "keep review app", "deploy review app", "review app label", "skip review app", "draft PR", "reviewApps".
 ---
 
 # How catladder pipelines work
@@ -82,6 +82,84 @@ started keeps _itself_ alive — under gitlab's own default
 (`conservative`, which catladder overrides) it would shield the whole
 pipeline from cancellation.
 
+## When review apps deploy (`reviewApps`)
+
+By default every merge/pull request deploys its review apps. Projects
+with many MRs/PRs (e.g. opened by agents) can put the review delivery
+chains — docker image → deploy → verify, for all components — behind
+ONE switch per MR/PR with the top-level `reviewApps` config. Tests,
+lint and audit always run; only the delivery waits.
+
+```ts
+reviewApps: {
+  deploy: "optIn",   // auto (default) | manual | optIn | optOut
+  // label: "catladder:review-app",       // optIn label (default)
+  // skipLabel: "catladder:no-review-app", // optOut label (default)
+  drafts: "checksOnly", // likeReady (default) | checksOnly (no review apps) | skip (no pipeline)
+},
+```
+
+- `optIn`: deploys only while the MR/PR carries `label`.
+- `optOut`: deploys unless it carries `skipLabel`.
+- `manual`: never on its own — only on request.
+- `drafts: "checksOnly"`: drafts run tests, lint and audit only, the review apps deploy once the
+  MR/PR is marked ready; `"skip"`: drafts run nothing.
+- Per-component `deploy.when` of the review env is ignored then.
+
+**GitHub** — like gitlab, the review workflow decides at its start
+from the PR's labels and draft state: when the policy says deploy, the
+chains run in the same run (one app build). Whatever changes later goes
+through the `▶️ catladder deploy review` workflow
+(`catladder-deploy-review.yml`, which rebuilds the app):
+
+- when the review workflow is green but didn't deploy, its last job
+  (`▶️ trigger review deploy`) reads the PR's labels/draft state again
+  and dispatches the deploy if the policy now says so — a label set
+  while CI ran counts;
+- switching the label on (opt-in: add `label`, opt-out: remove
+  `skipLabel`) deploys right away if the PR's `catladder ✅` is green;
+  switching it off stops the review apps (`🛑 catladder stop review
+  app`), and so does closing the PR — the stop first waits for a
+  review run of the PR that may still be deploying (on close it
+  cancels it), so a late deploy can't outlive the teardown;
+- on request, any time (agents included):
+  `gh workflow run catladder-deploy-review.yml --ref <pr-branch> -f pr=<number>`
+  — explicit requests always deploy, but need the PR open and its CI
+  green (the run reuses the green CI instead of re-running tests);
+- merge gates wait for **`catladder review app ✅`** (stable name,
+  independent of the components), the last job of whichever run
+  deploys. It also sets the commit status `catladder review app` on
+  the PR head (`success`/`failure`; the deploy workflow marks it
+  `pending` first) — dispatched runs are attached to the commit but not
+  listed on the pull request, the commit status is. A run that doesn't
+  deploy, or is cancelled (superseded, stopped), reports nothing — a
+  gate must treat a missing or `pending` status on the current head as
+  "wait". In the review run a skipped chain doesn't
+  fail `catladder ✅`, a failed one does;
+- `gh pr edit <number> --add-label catladder:review-app` is the
+  agent-friendly opt-in. Labels set with the workflow's own
+  `GITHUB_TOKEN` (from inside a workflow) trigger nothing — use a user
+  or app token;
+- the dispatch only works once the workflow exists on the default
+  branch (github rule) — the PR introducing `reviewApps` can't dispatch
+  yet.
+
+A single component with `env.review.deploy.when: "manual"` (and no
+`reviewApps`) uses the same workflow for just that component, without
+the automatic trigger.
+
+**GitLab** — a `🚀 deploy review` job in the MR pipeline is the
+switch: the docker and deploy jobs of all components `need` it. The
+policy decides whether it starts on its own (label set / opt-out not
+set) or waits as a manual job; playing it any time deploys (early
+clicks wait for builds and tests). It has `allow_failure: true`, so an
+unplayed switch leaves the pipeline green. Label changes don't start
+a pipeline on gitlab — use `yarn catladder mr review-app-on` (sets the
+label and triggers a pipeline) / `mr review-app-off`. Drafts are
+detected by their title prefix (`Draft:`, `[Draft]`, `(Draft)`); with
+`drafts: "skip"` marking an MR ready starts no pipeline, the next push
+does.
+
 ## Review-app auto-stop and pinning (GitLab)
 
 GitLab review environments stop automatically after 1 week, dev