CI/CD Branch Follower

SPEC: PJ2026-01060703 CI/CD branch follower draft-2026-07-03-p0-branch-follower

Entrypoints

bun scripts/cli.ts cicd branch-follower plan
bun scripts/cli.ts cicd branch-follower apply --confirm --wait
bun scripts/cli.ts cicd branch-follower status
bun scripts/cli.ts cicd branch-follower status --live
bun scripts/cli.ts cicd branch-follower run-once --all --dry-run
bun scripts/cli.ts cicd branch-follower run-once --follower <id> --confirm --wait
bun scripts/cli.ts cicd branch-follower events --follower <id>
bun scripts/cli.ts cicd branch-follower logs --follower <id>

apply --confirm --wait is the one-command deploy/update entry for the K8s controller. status is the default intermediate-state query; add --live only when a fresh adapter status read is needed.

Source Authority

Follower decisions must not read host source worktrees, target dev directories, .worktree/*, local git state, or direct GitHub branch refs.
Controller pods use EmptyDir and clone UniDesk controller source from the YAML-declared k8s git-mirror read URL, then run the CLI with the mounted registry.
Runtime source commits, build contexts, publish inputs and closeout status remain owned by each adapter's k8s git-mirror snapshot and runtime objects.
Dirty, stale, or missing-dependency host worktrees are non-authoritative and must not change observed sha, trigger sha, PipelineRun, GitOps, or status output.

YAML Ownership

config/cicd-branch-followers.yaml owns only controller settings and the follower registry: id, adapter, source/target configRefs, command argv, closeout check labels and budgets.

It must not copy runtime/GitOps/Secret details from owning configs:

HWLAB node lanes: config/hwlab-node-lanes.yaml
AgentRun lanes: config/agentrun.yaml
Web sentinel profiles/scenarios/reports/secrets: config/hwlab-web-probe-sentinel/*.yaml

Use configRef summaries in plan/status; do not create a full.md or super Markdown index.

First Followers

hwlab-jd01-v03: follows pikasTech/HWLAB@v0.3, adapter hwlab-node-runtime, trigger hwlab nodes control-plane trigger-current --node JD01 --lane v03 --confirm --wait.
agentrun-jd01-v02: follows pikasTech/agentrun@v0.2, adapter agentrun-yaml-lane, trigger agentrun control-plane trigger-current --node JD01 --lane jd01-v02 --confirm --wait.
web-probe-sentinel-master: follows pikasTech/unidesk@master, adapter web-probe-sentinel-cicd, trigger web-probe sentinel publish-current --node JD01 --lane v03 --sentinel jd01-web-probe-sentinel --confirm --wait.

Status Contract

Default status output must show follower id, phase, adapter, source branch + observed sha, target sha, last triggered sha, last succeeded sha, in-flight job/PipelineRun, budget source and next drill-down commands.

State machine phases are Observed, Noop, PendingTrigger, Triggering, ClosingOut, Succeeded, Failed, Superseded, Blocked, and Skipped.

run-once --dry-run is read-only: it may query K8s state and adapter status, but it must not write the state ConfigMap or trigger adapters.

3.1 KiB Raw Blame History