Skip to main content

How catladder pipelines work

All pipeline files are generated from catladder.ts — fix pipeline problems in the config (see catladder-config skill), never in the generated YAML.

Triggers and environments​

TriggerRuns onDeploys to
mainBranchpush to the main branchdev
mrmerge/pull requestsreview (one app per MR/PR)
taggedReleasegit tagsstage, prod

Generated layout:

  • GitLab: .gitlab-ci.yml includes generated files from .catladder-generated/gitlab/ (one per trigger).
  • GitHub: workflows in .github/workflows/ (generated ones carry a "generated by catladder" header; others are unmanaged). Manual actions are per-kind workflow_dispatch workflows, visually grouped by their emoji prefix in the Actions sidebar: 🚀 catladder create release, â–ļī¸ catladder deploy (manual-gated deploys), 🛑 catladder stop, ↩ī¸ catladder rollback — when all of a kind's tasks target one env the name carries it (e.g. â–ļī¸ catladder deploy prod); otherwise pick the task from the workflow's dropdown. Review apps are stopped automatically when their pull request closes (🛑 catladder stop review app); the same workflow can be dispatched with a PR number to tear one down while the pull request is still open (gitlab runs these as manual jobs inside the pipeline instead).

Stages: setup → test → build → deploy → verify (post-deploy checks), plus stop jobs for review-app teardown.

Review-app auto-stop and pinning (GitLab)​

GitLab review environments stop automatically after 1 week, dev environments after 4 weeks. Configure with top-level autoStop in catladder.ts ({ review, dev }, gitlab natural language like "3 days" or "never"). Merging or closing the MR always stops its review apps, independent of the timer.

To keep an MR's review apps alive longer, pin the MR:

  • yarn catladder mr pin — adds the pin label (default catladder::pin-review, configurable via autoStop.pinLabel) to the current branch's open MR and triggers a pipeline so the pin takes effect immediately. While the label is set, ALL components' review apps deploy with auto_stop_in: never.
  • yarn catladder mr unpin — removes the label; the auto-stop timer re-arms with the next deploy.

The pin lives on the MR (a label), not on the environment, so it survives redeploys — unlike gitlab's per-environment pin button, which the next successful deploy resets. Adding/removing the label by hand works too; a label change takes effect from the MR's next pipeline.

GitHub has no auto-stop: review apps run until the pull request is closed (pinning does not apply there).

Job images and catci​

Jobs run in catladder-provided images (đŸŗ catladder image <name> build jobs). Their definitions are materialized into .catladder-generated/images/ and built in the project's own registry under catladder/ (content-hashed, rebuilt only on change). .catladder-generated/catci/ holds a small bundled CI companion used by generated jobs (e.g. the release security audit) — all generated, never edit.

Projects can declare their own job images under images in catladder.ts (đŸŗ image <name> build jobs, pushed to job-images/ in the registry) and reference them in any jobImage field via { image: "<name>" } — see the catladder-builds skill. A declared Dockerfile directory is used in place; an inline dockerfile is materialized into .catladder-generated/images/project/<name>/. Either way the build job is skipped when the content hash already exists in the registry.

Caching​

Cache configuration is generated per build type. yarn node builds cache node_modules and the .yarn zip cache; GitLab uses mutable caches with fallback keys (review branches fall back to the dev cache), GitHub immutable lockfile-keyed caches where only the build job writes. pnpm builds cache nothing: measured on a 3800-package monorepo, moving the store or node_modules through a CI cache costs more than pnpm's from-registry install. Caching behavior is changed via the build config in catladder.ts, not in the YAML.

Releases​

With releases configured, tagged releases are created by a release job (method: semantic-release or changesets). The release job also runs a dependency security audit that gates the release. See the catladder-releases skill for the full flow.

Debugging CI​

Useful CLI commands (see the catladder-cli skill for invocation):

  • yarn catladder project ci job-log / project ci job-open — fetch or open a CI job
  • yarn catladder project doctor — detect drift between catladder.ts and the actually provisioned infrastructure (missing IAM roles, stale secrets, ...). Run this when a deploy/teardown fails with permission errors even though the config looks right; fix findings with yarn catladder project setup [component].
  • yarn catladder project logs open, project k8s list-pods, project k8s get-shell — inspect the running deployments
  • catladder-config — catladder.ts structure and regeneration
  • catladder-builds — build jobs and Docker images
  • catladder-deploys — deploy jobs, environments and review apps
  • catladder-releases — the taggedRelease flow and security-audit gate
  • catladder-secrets — env vars and secret management
  • catladder-cli — non-interactive CLI usage and command reference
  • catladder-migrate-ci-backend — moving between GitLab CI and GitHub Actions (running both in parallel, then cutting over)