docs(runbooks): continuously deployed Kubernetes agents with Actions

[ncrmro]

A fourth runbook: a merge to a catalog moves the resident agent fleet to that revision, with no stored cluster credential.

Distilled from two independent working implementations — one GitHub Actions → AWS OIDC → EKS, one Forgejo Actions → OIDC → a self-hosted cluster. They agree on every load-bearing detail, which is why this is worth writing down once:

• CI moves objects that already exist; an administrator bootstraps. Every other rule follows from that split, and the RBAC preflight asserts it.
• Placeholder rendering with a fail-closed check. An unrendered __CATALOG_REVISION__ is not a syntax error — it applies cleanly and deploys nothing.
• The revision is pinned in more than one place per agent and the operator does not compare them. The runbook verifies the count per rendered document.
• Bidirectional RBAC assertions. Positive checks catch RBAC that drifted narrower and would fail mid-apply; negative checks catch RBAC that drifted wider, which nothing else would notice.
• Ready alone lies. Convergence is generation == observedGeneration && Ready && resolved revision == pushed revision.

Also records three failures that produce no useful error, each learned the hard way on both forges: a renamed workflow file breaks the OIDC subject; job-level env with ${{ }} fails at run creation with no logs; a shallow checkout silently breaks path-based leg selection.

Not ready to merge. Two reasons, both deliberate:

1. The agents/<id>/deployment.yaml convention this assumes exists in zero catalogs today — both references use deploy/<agent>.yaml. The convention lands first.
2. No org has run this workflow yet. Holding the merge until one green deploy run exists, so the docs do not lead the code again.

The "Done when" section deliberately cites no SDLC signal, because link has none for continuous deployment. It verifies against the cluster directly instead. A scanner signal can follow later as its own change.

Filename fixes a typo-duplication in the requested name (deploying … deployed); happy to rename. It also breaks the short-imperative pattern of the other three runbooks — noted, and kept, because it says what it is.

🤖 Generated with Claude Code