@catladder/cli 0.0.0-fix-github-release-deploy-key-8a37ce13 → 0.0.0-fix-ghcr-lowercase-image-names-c09dd5a2

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

@@ -167,8 +167,13 @@ A safe order:
    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
+4. `yarn catladder project setup` — the *provisioned* credentials (the
+   gcloud deploy service account key, the kubernetes deploy
+   credentials) are hidden keys and therefore not part of the document
+   the pull/push round trip moves; setup re-provisions them into the
+   new vault
+5. `yarn catladder project doctor`, then delete the temp file
+6. only now decommission the GitLab project
 
 Never commit the intermediate file, and see the `catladder-secrets`
 skill for the exact command surface.
@@ -199,6 +204,17 @@ system's own registry, so they change host with the backend:
 first pipeline on the new backend therefore **rebuilds every job image**
 — it will be slow, and that is expected, not a bug.
 
+GHCR paths must be lowercase (the OCI spec allows no uppercase in a
+repository name). If the GitHub owner or repo name is mixed-case
+(`AcmeCorp/Nautilus`), catladder resolves the repository from the git
+remote at generation time and writes the lowercased path
+(`ghcr.io/acmecorp/nautilus`) into the workflows; an all-lowercase
+repository keeps the portable `${{ github.repository }}` expression.
+Set `pipelines.github.repository: "AcmeCorp/Nautilus"` when generation
+cannot see the remote — without it, every docker job fails with
+`repository name must be lowercase`. `catladder project doctor` reports
+this.
+
 Where the **app image** goes depends on the deploy type:
 
 - **`google-cloudrun`** — the image goes to Google Artifact Registry

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, or when deployments misbehave. Triggers on "pipeline", "CI job", "gitlab-ci", "workflow", "deploy failed", "cache", "release".
+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".
 ---
 
 # How catladder pipelines work
@@ -37,6 +37,32 @@ Generated layout:
 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
@@ -56,6 +82,30 @@ materialized into `.catladder-generated/images/project/<name>/`. Either
 way the build job is skipped when the content hash already exists in
 the registry.
 
+### GHCR image paths are lowercased (GitHub)
+
+Image repository names may not contain uppercase characters, but
+GitHub's `${{ github.repository }}` context interpolates the display
+casing of the owner and repo. For a mixed-case repository
+(`AcmeCorp/Nautilus`) catladder therefore resolves the repository from
+the git remote at generation time and writes the lowercased literal
+(`ghcr.io/acmecorp/nautilus/...`) into the workflows — GHCR serves that
+org under the lowercased namespace, so it is the correct address.
+An all-lowercase repository keeps the `${{ github.repository }}`
+expression, which stays correct in forks.
+
+If a docker job fails with `invalid tag ...: repository name must be
+lowercase`, the committed workflows were generated before this was
+fixed (or hand-edited): regenerate with `yarn catenv` and commit. When
+generation cannot see the git remote, pin it explicitly:
+
+```ts
+pipelines: { github: { repository: "AcmeCorp/Nautilus" } },
+```
+
+`yarn catladder project doctor` reports a mixed-case repository whose
+generated workflows still carry the expression.
+
 ## Caching
 
 Cache configuration is generated per build type. **yarn** node builds

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

@@ -52,6 +52,11 @@ workflows the same way (`▶️ catladder deploy`, `⏹️ catladder stop`,
 
 ## `method` — how the version is decided
 
+Whichever method runs, the release ends the same way: a `vX.Y.Z` tag, a
+`CHANGELOG.md` entry, a `chore(release): <version>` commit, and an
+entry on the releases page of the git host (gitlab `/-/releases`,
+github `/releases`) carrying the release notes.
+
 ### `semantic-release` (default)
 The version is derived automatically from **conventional commit
 messages** since the last release (`fix:` → patch, `feat:` → minor,
@@ -63,8 +68,10 @@ Developers declare changes intentionally as **`.changeset/*.md` files**
 (the official changesets format: a bump type + a human-written summary).
 The release job consumes all pending changesets, takes the highest bump,
 computes the next version from the last `v*` git tag, writes the
-changelog, commits `chore(release): <version>`, and pushes the tag. An
-empty `.changeset/` folder means there is nothing to release.
+changelog, commits `chore(release): <version>`, pushes the tag and
+creates the release entry on the git host (gitlab `/-/releases`,
+github `/releases`) with the changelog as its description. An empty
+`.changeset/` folder means there is nothing to release.
 
 Add a changeset by creating `.changeset/<name>.md`:
 
@@ -121,6 +128,13 @@ the `security` commands in the `catladder-cli` reference.
   MR adding a changeset describing the accumulated work.
 - Wrong version bump → check commit types (semantic-release) or the bump
   levels in the changeset files (changesets).
+- Tag pushed but nothing on the releases page → with `changesets` the
+  entry is created via the host api after the push and never fails the
+  job (the release itself is done); look for the `could not create the
+  release entry` warning at the end of the release job log. On gitlab
+  it needs `GL_TOKEN` (`catladder project renew-token`). Releases
+  tagged before catladder created entries have none — that is not fixed
+  retroactively, create them by hand from the tag.
 - Inspect the job with `yarn catladder project ci job-log` (see the
   `catladder-cli` skill).
 

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

@@ -80,6 +80,22 @@ All of these write to the secrets vault (the source of truth) and
 automatically mirror to the enabled CI backends — which vault is
 configured makes no difference to the commands.
 
+## Provisioned secrets
+
+A few secrets are not typed in by a human but created by
+`yarn catladder project setup`: the gcloud deploy service account key
+(`GCLOUD_DEPLOY_credentialsKey`) and the kubernetes deploy credentials
+(`KUBE_TOKEN`, `KUBE_CA_PEM`, `KUBE_URL`). They travel the same route as
+every other secret — vault first, then the enabled CI backends — but
+they are *hidden*: they never show up in `secrets-list`, in the editor
+or in a pulled document, and they must never be set by hand.
+
+Re-running `project setup` **rotates** them (a fresh credential is
+created and the old one revoked). That is also the answer whenever they
+are missing somewhere — after switching `secrets.vault`, for instance:
+a `secrets-pull`/`secrets-push` round trip does not carry hidden keys
+over, so re-run `project setup` to provision them into the new vault.
+
 ## GitHub pipelines
 
 GitHub Actions cannot read the vault at runtime; secrets are mirrored