@catladder/cli 0.0.0-main-8dbb6c76 → 0.0.0-main-a6b45abe

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

@@ -0,0 +1,125 @@
+---
+name: catladder-config
+description: Working with catladder, the framework that generates this repository's CI/CD pipelines (GitLab CI and/or GitHub Actions) from catladder.ts. Use when editing catladder.ts, adding or changing components, builds, deploys, environments or env vars, or when a change to generated pipeline files (.catladder-generated/, .gitlab-ci.yml, .github/workflows/) seems needed. Triggers on "catladder", "catladder.ts", "add a component", "change the pipeline", "deploy config".
+---
+
+# Working with catladder
+
+catladder generates this repository's CI/CD pipelines, deployments and
+environment files from the TypeScript config `catladder.ts` at the repo
+root. It is installed per project (`@catladder/cli`) — always use the
+locally installed version (`yarn catenv`, `yarn catladder`).
+
+## Golden rules
+
+1. **Never hand-edit generated files.** Everything under
+   `.catladder-generated/`, the generated parts of `.gitlab-ci.yml`, and
+   catladder-generated workflows under `.github/workflows/` are
+   overwritten on every regeneration (they carry a "generated by
+   catladder" header). To change them, change `catladder.ts` and
+   regenerate.
+2. **Regenerate after every `catladder.ts` change** by running
+   `yarn catenv`. With direnv set up, re-entering the project directory
+   does this automatically.
+3. **Commit the regenerated files together with the config change.**
+   Generated files are checked in; CI includes them directly.
+
+## Structure of catladder.ts
+
+```ts
+import type { Config } from "@catladder/cli";
+
+const config = {
+  appName: "my-app",
+  customerName: "pan",
+  pipelines: { gitlab: true, github: true }, // which CI systems to generate
+  components: {
+    www: {
+      dir: "frontend",          // working directory of this component
+      vars: { public: {}, secret: [] },  // env vars (see catladder-secrets skill)
+      build: { type: "node" },  // node | rails | meteor | custom — see catladder-builds
+      deploy: { type: "kubernetes" }, // kubernetes | google-cloudrun | dockerTag | custom — see catladder-deploys
+      env: {                    // enable/customize per environment
+        review: {},
+        dev: {},
+        stage: false,           // false disables the env for this component
+        prod: {},
+      },
+    },
+  },
+} satisfies Config;
+
+export default config;
+```
+
+Key concepts:
+
+- **Components** are the sub-apps/services of the project (frontend,
+  api, ...). Each has a build config and a deploy config.
+- **Environments**: `dev` (deployed on push to the main branch),
+  `review` (per merge/pull request), `stage` and `prod` (deployed on
+  tagged releases), `local` (only for local development via catenv).
+  Per-env overrides live under `env.<name>` and can override vars,
+  deploy settings, and more.
+- **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 manager**: yarn and pnpm are supported and autodetected
+  (from the `packageManager` field in package.json or the lockfile;
+  yarn is the fallback). `packageManager: "pnpm" | "yarn"` at the top
+  level overrides the detection. In pnpm projects, run the CLIs as
+  `pnpm catenv` / `pnpm catladder`.
+
+## Common tasks
+
+- **Add a component**: add an entry under `components`, run
+  `yarn catenv`, commit config + generated files.
+- **Change resources / deployment settings**: edit the component's
+  `deploy` (or per-env override), regenerate.
+- **Inspect the resulting pipeline**: read the generated files (e.g.
+  `.catladder-generated/gitlab/`, `.github/workflows/`) — but never
+  edit them.
+
+## Escape hatches — last resort, and a signal to file an issue
+
+catladder has two escape hatches for things it doesn't (yet) support
+natively:
+
+- **`customJobs`** (per component) — hand-written CI job specs injected
+  into the pipeline.
+- **transform `hooks`** (top-level `hooks`) —
+  `transformFileBeforeWrite` / `transformYamlBeforeWrite` rewrite the
+  generated files just before they're written to disk.
+
+Both work, but they are **fragile by design**: they depend on the exact
+shape of catladder's generated output, so a catladder upgrade can break
+them silently, and they sit outside everything the rest of the config
+gives you (rules, caching, images, per-env logic, snapshots). Prefer a
+first-class config option whenever one exists — check the `build`,
+`deploy`, `releases`, and env/vars surfaces (and the sibling skills)
+first.
+
+**When you do reach for one, treat it as a missing-feature signal.** If
+a dev needs `customJobs` or a transform hook, it almost always means
+catladder is missing a capability that other projects will need too.
+**Open an issue at
+https://github.com/panter/catladder/issues** describing the use
+case (what you're trying to achieve and why the existing config can't
+express it) so it can be generalized into a supported feature — and,
+where possible, offer to help the dev write that issue. The goal is for
+escape hatches to shrink over time, not accumulate.
+
+## Related skills
+
+- `catladder-builds` — the component `build` config (build types, Docker)
+- `catladder-deploys` — the component `deploy` config (k8s, Cloud Run, …)
+- `catladder-secrets` — env vars and secret management
+- `catladder-releases` — releasing (semantic-release / changesets)
+- `catladder-pipelines` — how the generated pipelines work, debugging CI
+- `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving a project between GitLab CI
+  and GitHub Actions
+- `catladder-migrate-release-method` — switching between
+  semantic-release and changesets
+- `catladder-migrate-package-manager` — switching a project between
+  yarn and pnpm

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

@@ -0,0 +1,146 @@
+---
+name: catladder-deploys
+description: Configuring how a component is deployed in a catladder project — the `deploy` config in catladder.ts (deploy types kubernetes / google-cloudrun / npmPackage / pages / dockerTag / custom, manual vs auto deploy, resources, autoscaling, health checks, CloudSQL/MongoDB, Cloud Run services/jobs/worker pools, cron jobs). Use when adding or changing a component's deploy, choosing a deploy target, setting resources/replicas/autoscaling, wiring a database, adding cron/scheduled jobs, publishing a component as an npm package, publishing a site on gitlab pages, or making a deploy manual. Triggers on "deploy config", "deploy type", "kubernetes", "cloud run", "cloudrun", "autoscale", "resources", "replicas", "cloudsql", "mongodb", "cronjob", "manual deploy", "npm package", "npm publish", "publish to npm", "gitlab pages", "static site", "docs site", "site preview".
+---
+
+# Component deploys with catladder
+
+Each component in `catladder.ts` has a `deploy` config that catladder
+turns into the deploy (and stop) CI jobs and the cloud resources. Change
+the deploy in `catladder.ts` and regenerate (`yarn catenv`) — never
+hand-edit generated files (see the `catladder-config` skill). Cloud
+resources themselves are provisioned separately with
+`yarn catladder project setup` (see the `catladder-cli` skill).
+
+```ts
+components: {
+  api: {
+    dir: "backend",
+    build: { /* see catladder-builds */ },
+    deploy: {
+      type: "kubernetes",         // kubernetes | google-cloudrun | npmPackage | pages | dockerTag | custom
+      cluster: { type: "gcloud", name: "…", projectId: "…", region: "…" },
+      values: { application: { replicas: 2 } },
+    },
+  },
+}
+```
+
+## Deploy types
+
+| Type | Deploys to | Requires |
+|---|---|---|
+| `kubernetes` | a GKE cluster via Helm | `cluster` |
+| `google-cloudrun` | Google Cloud Run | `projectId`, `region` |
+| `npmPackage` | publishes the component to an npm registry | nothing — see below |
+| `pages` | publishes a static site on gitlab pages | `script` — see below |
+| `dockerTag` | tags an image (no runtime) | `tag` — rarely used, not generally recommended |
+| `custom` | your own script | `requiresDocker`, `script` |
+
+## Manual vs automatic deploys
+
+`when: "manual" | "auto"` controls whether the deploy job runs
+automatically. **Default: `prod` is `manual`, every other environment
+is `auto`.** Set per component or per environment (`env.<name>.deploy`).
+
+`waitFor: ["otherComponent"]` (experimental) makes a deploy wait for
+another component to deploy first.
+
+## Kubernetes essentials
+
+`cluster` is required: `{ type: "gcloud", name, projectId, region, domainCanonical? }`.
+Everything app-level lives under `values`:
+
+- `application` — `replicas`, `autoscale` (`minReplicas`/`maxReplicas`/`metrics`),
+  `resources` (cpu/memory limits & requests), `healthRoute`,
+  `startupProbe`/`readinessProbe`/`livenessProbe`, `command`,
+  `redirects`, `worker` (a separate background deployment). Set
+  `application: false` for a component with no long-running deployment.
+- `cloudsql` — attach an (unmanaged) CloudSQL Postgres instance.
+- `mongodb` — a Bitnami MongoDB (`standalone` or `replicaset`).
+- `jobs` — Helm post-install/upgrade jobs; `cronjobs` — scheduled jobs.
+
+## Cloud Run essentials
+
+`projectId` and `region` are required. Then:
+
+- `service` — the main service (`minInstances`, `maxInstances`, `cpu`,
+  `memory`, `timeout`, `allowUnauthenticated`, `ingress`, `healthCheck`,
+  …). `service: false` disables it (job-only deployments).
+- `additionalServices`, `jobs`, `workerPools` — extra services, run-to-
+  completion jobs, and always-on background worker pools.
+- `cloudSql` — attach an (unmanaged) CloudSQL instance; choose the
+  connection-string format (`prisma` default, `rails`, `jdbc`).
+- `execute` — run a script/job/HTTP call at a deploy lifecycle point
+  (`preDeploy`/`postDeploy`/`preStop`/`postStop`) or on a `schedule`.
+  Prefer this over the deprecated `when`/`schedule` fields on `jobs`.
+
+## npm packages
+
+`type: "npmPackage"` publishes the component to an npm registry instead
+of deploying a service — "deploy" means `npm publish`. Version and
+dist-tag derive from the pipeline trigger:
+
+- tagged release (`prod` env): the tag's version (`v5.1.2` → `5.1.2`)
+  under dist-tag `latest`
+- main branch (`dev`) and merge requests (`review`): an installable
+  canary `0.0.0-<branch-slug>-<sha>`; branches named `next`/`beta` get
+  their own dist-tag, everything else publishes under `canary`
+
+Options (all optional): `access` (`"public"` default), `registry`
+(npmjs.org default), `distTag` (overrides the derivation).
+
+```ts
+lib: {
+  dir: "lib",
+  env: { stage: false },   // npm has no staging — publish latest directly
+  build: { type: "node" },
+  deploy: { type: "npmPackage" },
+},
+```
+
+Authentication uses the `NPM_TOKEN` secret (set it like any other
+catladder secret, see `catladder-secrets`). Disable the stage
+environment as shown — a tagged release then publishes `latest`
+directly from the auto-deploying prod env.
+
+## GitLab pages sites
+
+`type: "pages"` publishes a static site (docs, storybook, coverage
+report) on gitlab pages: the deploy job runs your build `script` and
+publishes `publishDir` (default `"public"`). Review environments
+automatically publish under an `mr-<iid>` path prefix — every merge
+request gets its own site preview (the prefix is exposed to the build
+as `$PAGES_PREFIX`). The gitlab environment url points at the
+published site. GitLab-only for now.
+
+```ts
+docs: {
+  dir: "docs",
+  env: { stage: false, prod: false },  // pages exist on main + MRs
+  build: false,
+  deploy: {
+    type: "pages",
+    requiresInstall: true,
+    script: ["yarn workspace docs build"],
+  },
+},
+```
+
+Pages deploys default to `allowFailure: true` (a broken site publish
+should not block the pipeline). `allowFailure` is also available on
+every other deploy type, and custom deploys can now declare
+`artifactsPaths` for output they produce.
+
+## Full option reference
+
+See [references/deploy-types.md](references/deploy-types.md) for every
+deploy type's options, required fields, and defaults.
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-builds` — the matching `build` config
+- `catladder-pipelines` — how deploy jobs, environments and review apps work
+- `catladder-cli` — `project setup` (provision cloud resources) and `project doctor`
+- `catladder-secrets` — env vars available at runtime

package/dist/bundles/skills/catladder-deploys/references/deploy-types.md

@@ -0,0 +1,83 @@
+# catladder deploy config reference
+
+Full options for `components.<name>.deploy` (and per-env
+`env.<name>.deploy`). Fix deploy problems in `catladder.ts` and
+regenerate — never edit generated files. Provision the underlying cloud
+resources with `yarn catladder project setup`; detect drift with
+`yarn catladder project doctor`.
+
+## Shared base (all deploy types)
+
+| Option | Type | Purpose / default |
+|---|---|---|
+| `when` | `"manual" \| "auto"` | prod → `manual`, other envs → `auto` |
+| `waitFor` | `string[]` | EXPERIMENTAL; wait for other components first |
+| `jobTags` | `string[]` | runner tags |
+| `jobVars` | `EnvVars` | env vars only in the deploy job |
+| `runnerVariables` | `Record<string,string>` | extra runner vars |
+
+(Cloud Run defines its own `execute`; otherwise the base applies to all.)
+
+## `kubernetes`
+
+- `cluster` — **required**: `{ type: "gcloud", name, projectId, region, domainCanonical? }`.
+- `debug?: boolean` — pass `--debug` to Helm.
+- `additionalHelmArgs?: string[]`.
+- `chartName?: string` — custom chart location (not recommended).
+- `values?` — app configuration (unknown props allowed, forwarded to the chart):
+  - `application?: false | { command?, enabled? (default true), redirects?, hostAliases?, replicas?, autoscale?: { minReplicas, maxReplicas, metrics[] }, updateStrategy?, resources?: { limits/requests: { cpu, memory } }, healthRoute?, startupProbe? / readinessProbe? / livenessProbe? (httpGet shape), worker?, jobDefaults? }`.
+  - `cloudsql?: { type: "unmanaged", enabled, instanceConnectionName, dbUser?, dbNamePrefix?, dbBaseName? }`.
+  - `mongodb?: { enabled?, dbName?, persistence?, resources?, tolerations? } & ({ architecture: "standalone" } | { architecture: "replicaset", replicaCount? (default 2) })`.
+  - `mailhog?: { enabled }` — dev mail catcher (injects `MAIL_URL`).
+  - `jobs?: Record<string, false | { command, hook? }>` — Helm hook jobs (default hook `post-install,post-upgrade`).
+  - `cronjobs?: Record<string, false | { schedule, command, concurrencyPolicy?, timeZone? }>`.
+  - `secretsFromOtherComponent?: { [envVar]: string }` — load secrets from another component in the same cluster.
+  - `mapServiceUrlToEnv?: { [envVar]: string }` — map another service's internal endpoint to an env var.
+
+## `google-cloudrun`
+
+- `projectId` — **required**.
+- `region` — **required** (`Gcloudregion` enum, e.g. `europe-west6`).
+- `service?: boolean | DeployConfigCloudRunService` (default enabled):
+  - `command?`, `args?`, `image?`, `minInstances?` (0), `maxInstances?` (100), `cpu?` (1|2|4|6|8), `memory?` (512MB), `timeout?` (5min), `noCpuThrottling?`, `allowUnauthenticated?` (true), `ingress?` (`all` | `internal` | `internal-and-cloud-load-balancing`, default `all`), `executionEnvironment?` (`gen1`|`gen2`), `http2?`, `gpu?`/`gpuType?`, `sessionAffinity?`, `healthCheck?` (`true` or `{ startupProbe, livenessProbe }`), plus cloud-storage volumes and VPC network config.
+- `additionalServices?: Record<string, service | false | null>`.
+- `jobs?: Record<string, DeployConfigCloudRunJob | false | null>` — `{ command, args?, image?, cpu?, memory? (512Mi), timeout? (10min), parallelism? (1), maxRetries? (0) }`. The per-job `when`/`schedule`/`waitForCompletion` fields are **deprecated** — use `execute`.
+- `workerPools?: Record<string, DeployConfigCloudRunWorkerPool | false | null>` — always-on background work, no endpoint, no autoscaling: `{ command, instances? (1), cpu?, memory?, image?, args?, gpu?/gpuType? }`.
+- `cloudSql?: DeployConfigCloudRunCloudSql | false` — `{ type: "unmanaged", instanceConnectionName, dbUser?, dbNamePrefix?, dbBaseName?, deleteDatabaseOnStop?, dbConnectionStringFormat? ("prisma" default | "rails" | "jdbc"), dbConnectionStringVariablesMode? ("embedded" default | "legacy"), dbAdditionalQueryParams? }`. Injects `DB_*` vars plus `DATABASE_URL`/`DATABASE_JDBC_URL`; in the default `"embedded"` mode the connection strings contain the component's final values (referenceable from other components, `vars.public` overrides of `DB_*` flow in). To share another component's database: `dbBaseName: "<owner>"` + `DB_PASSWORD: "${<owner>:DB_PASSWORD}"` in `vars.public`.
+- `execute?: Record<string, DeployConfigCloudRunExecute | null>` — run a script / job / HTTP call at a lifecycle point (`when`: `preDeploy` | `postDeploy` | `preStop` | `postStop`) or on a `schedule`.
+- `debug?: boolean`.
+- Service name and url: the service deploys as `<customerName>-<appName>-<env>[-<reviewSlug>]-<componentName>`, and `ROOT_URL`/`ROOT_URL_INTERNAL` are cloud run's deterministic url `https://<service>-<projectNumber>.<region>.run.app`. That url only exists while its first dns label stays within 63 characters, so catladder **shortens the component part** of the service name when it would not fit — otherwise cloud run would serve a legacy url with a random identifier and the generated hostname would never resolve. Review environments carry a runtime slug on top, for which 8 characters are reserved, so a name can fit `dev`/`prod` and still be shortened for `review`. Generation fails instead of shortening when two components would end up with the same name, or when customerName/appName/env/project number already leave no room.
+
+## `npmPackage`
+
+- `type: "npmPackage"` — **required**. Publishes the component as an npm package: the deploy job stamps the derived version into `package.json` and runs `npm publish` (via catci).
+- `access?: "public" | "restricted"` — npm access level, default `"public"`.
+- `registry?: string` — registry url, default `https://registry.npmjs.org/`.
+- `distTag?: string` — overrides the derived dist-tag.
+- Version/dist-tag derivation: tagged release (`prod`) → tag version under `latest`; branch/MR → `0.0.0-<branch-slug>-<sha>` under `canary` (branches `next`/`beta` publish under their own dist-tag).
+- Auth: the `NPM_TOKEN` secret (managed like any catladder secret), or — on github — **trusted publishing** with no stored token: register the package's trusted publisher on npmjs.com with the repo and the publishing **workflow filename** (`catladder-release.yml` for tagged releases). npm allows one trusted publisher per package, so canary publishes from the main/review workflows still need `NPM_TOKEN`. A set token always wins over OIDC.
+- Disable staging on the component (`env: { stage: false }`) so tagged releases publish directly.
+
+## `pages`
+
+- `type: "pages"` — **required**. Publishes a static site on gitlab pages or github pages. On github the repo's Pages source must be set to "GitHub Actions" once; per-merge-request previews are gitlab-only (github serves one site per repository).
+- `script: string[]` — **required**; produces the site.
+- `publishDir?: string` — output directory relative to the repo root, default `"public"`.
+- `requiresInstall?: boolean` — run the package-manager install (yarn/pnpm) first (`requiresYarnInstall` is a deprecated alias).
+- `jobImage?: GitlabJobImage`; also accepts `cache`.
+- Review envs publish under an `mr-<iid>` path prefix (parallel deployments → MR previews; exposed as `$PAGES_PREFIX`); other envs publish at the root. The environment url is the published pages url.
+- Defaults to `allowFailure: true`.
+
+## `dockerTag`
+
+- `type: "dockerTag"`, `tag: string` — **required**. Adds a custom tag on the image repo to deploy it. Only used in one project historically; not generally recommended (runtime env vars must be coordinated manually).
+
+## `custom`
+
+- `type: "custom"` — **required**.
+- `requiresDocker: boolean` — **required**; whether the deploy needs a built Docker image.
+- `script: string[]` — **required**; the deploy script.
+- `requiresInstall?: boolean` — whether the script needs the package-manager install (`requiresYarnInstall` is a deprecated alias).
+- `stopScript?: string[]` — script to stop/tear down the environment.
+- `jobImage?: GitlabJobImage`.
+- Also accepts `cache` (via `WithCacheConfig`).

package/dist/bundles/skills/catladder-migrate-ci-backend/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: catladder-migrate-ci-backend
+description: Guiding a catladder project from one CI backend to the other — GitLab CI → GitHub Actions or GitHub Actions → GitLab CI — using the `pipelines` config to run both in parallel first, then cutting over. Covers the blockers to check up front (unsupported features, secrets vault, release tokens, container registry) and the manual cleanup a cut-over needs. Use when moving a project between GitLab and GitHub, enabling a second CI backend, or decommissioning one. Triggers on "migrate to github", "move to github actions", "switch from gitlab to github", "migrate to gitlab", "enable github pipeline", "run both pipelines", "gitRemote", "secrets-sync-github".
+---
+
+# Migrating between GitLab CI and GitHub Actions
+
+catladder generates pipelines for both CI systems from the same
+`catladder.ts`, and **both can be enabled at once**. That is what makes
+this migration safe: run the new backend in parallel with the old one on
+the same commits, compare, and only then cut over.
+
+```ts
+pipelines: {
+  gitlab: true,
+  github: { gitRemote: "github" },
+}
+```
+
+(`pipelineType: "gitlab"` is the deprecated single-backend form —
+replace it with `pipelines` as the first step.)
+
+Never do this as one big-bang commit. Work through the steps below and
+**stop at each decision point that is the user's to make** — creating
+repositories, pushing to a new host, and moving secrets are all
+outward-facing actions that need their explicit go-ahead.
+
+## Step 0 — scope it with the user
+
+Ask up front (once, with your reading of the repo attached):
+
+- **Direction and end state**: is the old backend going away, or do both
+  stay live permanently (some projects keep GitLab for releases and
+  GitHub for PR checks)?
+- **Repository**: does the target repo already exist, or must it be
+  created and pushed?
+- **Which backend owns releases** during the parallel phase — see step 6.
+- **Where secret values live afterwards** — see step 5. This is the one
+  that blocks decommissioning, so raise it early rather than at the end.
+
+## Step 1 — check the blockers before changing anything
+
+Read the project's `catladder.ts` and report what will *not* carry over.
+Going **GitLab → GitHub**:
+
+- **`deploy: { type: "pages" }`** — not supported on the GitHub backend.
+  Those components simply generate no deploy jobs there (a warning, not
+  a generation error), so the site silently stops being published.
+- **`agents`** (the Claude agent integration) — GitLab-only; agent jobs
+  are skipped on GitHub.
+- **Default branch must be `main`** — the generated GitHub main-branch
+  workflow triggers on `push: branches: [main]`. A project on `master`
+  or `develop` gets a workflow that never runs.
+- **`hooks.transformYamlBeforeWrite` / `transformFileBeforeWrite`** —
+  hooks run for the GitHub files too. Any hook that keys on
+  `.gitlab-ci.yml` or on GitLab's YAML shape needs revisiting; a hook
+  that blindly rewrites `data.include` will corrupt workflow files.
+- **`customJobs`** do carry over (they are platform-neutral job specs),
+  but anything GitLab-shaped *inside* them — raw `rules:`, `only:`,
+  GitLab-specific job keys — does not.
+- **`secrets.vault: "gitlab"`** (the default) requires a GitLab project.
+  See step 5.
+
+Going **GitHub → GitLab** the feature list is easier (GitLab supports
+everything the GitHub backend does), but still check the hooks, and note
+that GitLab needs a real access token for releases (step 6).
+
+Report this list to the user before touching the config. If a blocker
+has no first-class solution, that is worth an issue on catladder —
+https://git.panter.ch/catladder/catladder/-/issues.
+
+## Step 2 — get the repository onto the target host
+
+For a new GitHub repo: create it and push `main` plus **all tags**
+(the release job derives the version from the nearest `v*` tag — a
+tagless mirror re-releases `1.0.0`).
+
+Add it as a **second remote** rather than replacing `origin`, so the old
+backend keeps working during the parallel phase:
+
+```bash
+git remote add github git@github.com:<owner>/<repo>.git
+git push github main --tags
+```
+
+Ask before creating the repository or pushing — this publishes the code
+to a new host.
+
+## Step 3 — enable both backends
+
+```ts
+pipelines: {
+  gitlab: true,
+  github: { gitRemote: "github" },
+}
+```
+
+`gitRemote` tells catladder which git remote points at that CI system's
+repository (default `origin`). Then regenerate and commit:
+
+```bash
+yarn catenv
+```
+
+The two file sets live side by side and never collide:
+
+| backend | generated files |
+|---|---|
+| gitlab | `.gitlab-ci.yml`, `.catladder-generated/gitlab/` |
+| github | `.github/workflows/catladder-*.yml`, `.catladder-generated/github/scripts/` |
+
+Shared (generated once for both): `.catladder-generated/images/` and
+`.catladder-generated/catci/`.
+
+If the hosted runners of the new backend are smaller than the old ones,
+tune them per backend instead of globally:
+
+```ts
+github: { gitRemote: "github", runnerVariables: { TURBO_CONCURRENCY: "2" } },
+```
+
+## Step 4 — mirror the secrets to the new backend
+
+GitHub Actions cannot read the vault at runtime, so the values must be
+pushed into GitHub:
+
+```bash
+gh auth login
+yarn catladder project secrets-sync-github
+```
+
+This creates one **GitHub environment per catladder env** and writes
+each secret/variable into the environment(s) whose generated jobs
+actually reference it. (Environments are not cosmetic: GitHub caps a
+repository at 100 secrets, which a multi-env project blows through; the
+cap applies per environment.) Re-run it after every secret change for as
+long as both backends are live.
+
+Then verify:
+
+```bash
+yarn catladder project doctor
+```
+
+It compares the secret/variable *names* the generated workflows
+reference against what is actually set, per environment, and prints the
+command that heals each gap. Values cannot be compared — GitHub secrets
+are write-only by design.
+
+## Step 5 — the secrets vault is what actually blocks decommissioning
+
+`secrets.vault` defaults to `"gitlab"`: the GitLab project variables
+double as the **readable source of truth**, and the CI backends only
+ever get mirrored copies. GitHub secrets can never serve as that source.
+
+So if GitLab is going away, move the vault **before** deleting anything:
+
+```ts
+secrets: {
+  vault: { type: "bitwarden", collection: "catladder" },
+}
+```
+
+A safe order:
+
+1. `yarn catladder project secrets-pull <env>: --out /tmp/secrets.yml`
+   against the old vault (unset values show as `🚨 FILL ME`)
+2. switch `secrets.vault` in `catladder.ts`, `yarn catenv`
+3. `yarn catladder project secrets-push <env>: --file /tmp/secrets.yml`
+4. `yarn catladder project doctor`, then delete the temp file
+5. only now decommission the GitLab project
+
+Never commit the intermediate file, and see the `catladder-secrets`
+skill for the exact command surface.
+
+## Step 6 — releases and tokens
+
+- **GitLab** needs a `GL_TOKEN` project access token (named
+  `semantic-release`) to push the release commit and tag. It is created
+  and rotated by `yarn catladder project setup`.
+- **GitHub** needs nothing extra — the release jobs use the built-in
+  `github.token`. Tags pushed by that token do not retrigger workflows,
+  so the release job dispatches the tagged-release workflow explicitly;
+  that is built in and needs no configuration.
+- **Only one backend should own releases at a time.** Both backends
+  generate release jobs, and with `releases: { when: "auto" }` both would
+  try to tag the same commit. During the parallel phase, agree with the
+  user which backend releases; the other one's release job must stay
+  unclicked (`when: "manual"`) or the parallel phase must be short.
+
+See the `catladder-releases` skill for how the release jobs differ
+(GitLab manual job vs. GitHub dispatch workflow).
+
+## Step 7 — registry and the first run
+
+The **job images** (the catladder runner images) always live in the CI
+system's own registry, so they change host with the backend:
+`$CI_REGISTRY_IMAGE` on GitLab, `ghcr.io/<owner>/<repo>` on GitHub. The
+first pipeline on the new backend therefore **rebuilds every job image**
+— it will be slow, and that is expected, not a bug.
+
+Where the **app image** goes depends on the deploy type:
+
+- **`google-cloudrun`** — the image goes to Google Artifact Registry
+  (`<region>-docker.pkg.dev/<projectId>/catladder-deploy/…`) on both
+  backends. Cloud Run can only pull from AR/GCR, so a backend migration
+  does not move the app image at all. Nothing to do here.
+- **`kubernetes`** — the app image lives in the CI registry and does
+  move. catladder handles the pull itself: every deploy runs
+  `kubernetesCreateSecret`, which writes a `docker-registry` secret
+  (`gitlab-registry-<component>`) into the namespace, and the chart wires
+  it in as `imagePullSecrets`. Note the secret keeps its historical name
+  on both backends.
+
+The credential behind that secret differs per backend, and this is the
+one thing to raise before a kubernetes component moves to GitHub:
+
+- **GitLab** provisions a durable one automatically —
+  `catladder project setup` creates a `gitlab-deploy-token` (scope
+  `read_registry`), GitLab exposes it to jobs as `CI_DEPLOY_USER` /
+  `CI_DEPLOY_PASSWORD`, and `project doctor` fails when it is missing.
+- **GitHub has no equivalent.** The deploy falls back to the workflow
+  token, which expires with the run: the initial pull succeeds and the
+  job goes green, but a pod rescheduled later cannot re-pull —
+  `ImagePullBackOff` weeks after a deploy that looked fine. Until that
+  is solved (catladder issue #75), a project moving kubernetes to GitHub
+  must supply a long-lived registry credential itself, declared as
+  secrets named `CI_DEPLOY_USER` / `CI_DEPLOY_PASSWORD` (a PAT with
+  `read:packages`), which take precedence in the deploy.
+
+## Step 8 — run both, compare, then cut over
+
+Let both pipelines run on the same commits until the new backend is
+green for all three triggers: a merge/pull request, the main branch, and
+a tagged release. Only then flip:
+
+```ts
+pipelines: { github: true }
+```
+
+```bash
+yarn catenv
+```
+
+⚠️ **catladder only cleans up backends that are still enabled** — the
+disabled backend's files stay behind and must be deleted by hand:
+
+- gitlab: `.gitlab-ci.yml` and `.catladder-generated/gitlab/`
+- github: `.github/workflows/catladder-*.yml` and
+  `.catladder-generated/github/scripts/`
+
+Then, if the new host becomes `origin`, update the remotes and drop the
+now-wrong `gitRemote`, regenerate once more, and finish with
+`yarn catladder project doctor`.
+
+## After the cut-over
+
+- **Set up merge gating — GitHub has none by default.** On GitLab,
+  "merge when pipeline succeeds" is built in; on a fresh GitHub repo a
+  PR is mergeable the moment it opens, checks still running, and the
+  auto-merge button does not even appear. `yarn catladder project setup`
+  configures it: auto-merge + delete-merged-branches on the repo, and a
+  branch protection rule on the default branch requiring the generated
+  **`catladder ✅`** aggregate check (the one stable context — never
+  require individual job names, they change with every component
+  add/rename and a stale required name blocks its own PR forever).
+  `project doctor` verifies it. Two things stay human choices: "Do not
+  allow bypassing" (leave it off — generated CI means a generation bug
+  can only be fixed via the admin bypass) and required reviews.
+- Tell the team where the pipeline lives now and how manual actions
+  work there (on GitHub, manual jobs are dispatch workflows in the
+  Actions sidebar — `🚀 catladder create release`, `▶️ catladder deploy`,
+  `⏹️ catladder stop`, `↩️ catladder rollback`).
+- Revoke tokens that are no longer needed (`GL_TOKEN`).
+- Keep the old host readable until the vault migration is verified in
+  practice — a rotated secret is much cheaper to recover than a deleted
+  one.
+
+## Related skills
+
+- `catladder-config` — `catladder.ts` structure, `pipelines`, regeneration
+- `catladder-secrets` — vault, `secrets-sync-github`, secret commands
+- `catladder-releases` — release jobs and how they differ per backend
+- `catladder-pipelines` — triggers, generated file layout, debugging CI
+- `catladder-cli` — `project doctor`, `project setup`, non-interactive usage
+- `catladder-migrate-package-manager` — migrating between yarn and pnpm