@klok-integration/cli 0.6.217 → 0.6.224

package/assets/agents/AGENTS.framework.md

@@ -13,7 +13,9 @@ templates). Changes here reach every tenant, so read the library's `klok-docs/`
 * Builds: `./gradlew build` must stay green, tests run on the JUnit Platform, and the extension's runtime and
   deployment modules must get exactly the same version (one timestamp per build).
 * Releases happen from `main` only, in dependency order (klok-common, broker client, extension), each waiting for
-  its publish and the catalog update before the next is merged. Maven Central is immutable: a version is never
-  republished.
+  its publish and the catalog update before the next is merged. After that catalog update the job starts the
+  pipeline of each library built against an older version (`klok catalog release-dependents`); a library that pins
+  its framework versions itself instead of following `gradle/klok-libs.versions.toml` is only warned about. Maven
+  Central is immutable: a version is never republished.
 * CI template changes are tested with a dry run (`KLOK_CATALOG_UPDATE_DRY_RUN=true`, a branch pointing at the
   template branch) before they are merged to `main`, because every project includes the templates from `main`.

package/assets/agents/AGENTS.workspace.md

@@ -179,7 +179,10 @@ Klok templates choose which jobs run from the type of the change.
 * Never pin or edit these versions by hand in a project. Refresh the project's copy with
   `./gradlew updateKlokLibsToml` and commit the refreshed `gradle/klok-libs.versions.toml`.
 * A change that spans framework libraries is merged and published in dependency order: klok-common, then the broker
-  client, then the Quarkus extension.
+  client, then the Quarkus extension. The catalog then releases the dependents automatically: when a library's
+  release reaches the catalog, its update job starts the pipeline of every framework library that follows the catalog
+  and was built against an older version of it (`klok catalog release-dependents`), so nobody releases the extension
+  again by hand.
 
 ## Pipelines, secrets and infrastructure
 

package/assets/agents/skills/klok-release/SKILL.md

@@ -24,6 +24,9 @@ roles and secrets, catalog update) before acting.
    catalog update of one before merging the next: the catalog's commit for that release, not the merge, which only
    starts the pipeline that produces it:
    `glab api --hostname git.klok.dev "projects/klok%2Fframework%2Fklok-gradle-dependency-catalog/repository/commits?ref_name=main&per_page=10" | jq -r '.[].title'`.
+   A library that needs no change of its own is not released by hand: after each catalog update the job runs
+   `klok catalog release-dependents`, which starts the pipeline of every framework library built against an older
+   version of what was released (its log says which; `--dry-run --library <artifact>` shows it by hand).
 5. **Never cancel, stop or restart a running job, pipeline or deployment without a human's explicit yes.** A
    release waiting on Maven Central or npm can take half an hour, and `main` pipelines queue behind each other or run
    in parallel, so a long wait is normal. Check the current time with `date -u` before judging how long anything has run. Report the
@@ -47,7 +50,10 @@ as a red pipeline. Vault CI login is not one of them: it needs nothing per proje
 
 * Nothing in Vault per project. Every job logs in with the tenant CI role `<tenant>-ci` (a Vault JWT role bound
   to `namespace_path` `<tenant>` and `<tenant>/*`, carrying `default` and the tenant CI read policy
-  `<tenant>-cicd-read`). The templates set `VAULT_AUTH_ROLE: $KLOK_TENANT-ci`. A tenant without the role fails
+  `<tenant>-cicd-read`, which reads the CI environment object only). The templates set
+  `VAULT_AUTH_ROLE: $KLOK_TENANT-ci`. The deploy key (`secret/<tenant>/CICD_KEY`, manifest, catalog and pin pushes)
+  is read only through the second role `<tenant>-ci-protected`, bound to `ref_protected: "true"` as well: klok-cli
+  logs in with it on its own, so a merge request pipeline cannot read the key. A tenant without `<tenant>-ci` fails
   every job at `auth/jwt/login` with `role "<tenant>-ci" could not be found`; the tenant setup is the
   *Onboarding a tenant* runbook in `klok docs read klok-framework-development-guide`, every credential and the step
   that uses it in `klok-docs/ci/authentication.md` of `klok/environment/build-ci-templates`.
@@ -71,6 +77,8 @@ field, and let a person run it.
 | `role "<tenant>-ci" could not be found` at `auth/jwt/login` | the tenant has no CI role yet (tenant onboarding) |
 | `claim "namespace_path" does not match` at `auth/jwt/login` | the project is outside the tenant's root group, or `VAULT_AUTH_ROLE` names another tenant's role |
 | `permission denied` reading `secret/.../cicd-environment-variables` | the CI role lacks the tenant CI read policy (has only `default`) |
+| `claim "ref_protected" does not match` at `auth/jwt/login` | a job that reads the deploy key runs for an unprotected branch; it belongs on `main` (or another protected branch) |
+| `permission denied` reading `secret/<tenant>/CICD_KEY` | the job read the key with `<tenant>-ci` (an inline `vault kv get`); log in with `<tenant>-ci-protected`, or use `klok manifest update` |
 | `403` on `groups/<tenant>/-/packages/maven/...` | job token allowlist of the package project lacks the reader's group |
 | `Could not find dev.klok...:<version>` | the version is not published yet, or the catalog copy is stale (`updateKlokLibsToml`) |
 | `already deployed` from JReleaser | Maven Central already has that version; a `main` build is a new timestamp, do not retry the same job |