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. status --live and local run-once must submit a bounded K8s reconcile Job; the Job performs all source, Tekton, Argo and runtime reads inside the cluster and writes the state ConfigMap.

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 plus the YAML-declared k8s git-mirror cache PVC, sync GitHub refs from inside Kubernetes, clone UniDesk controller source from /cache, 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.
trans or SSH may be used only by the operator CLI as a transport to create/read Kubernetes objects on the target cluster. It must not be part of branch-follower source sync, GitHub communication, status collection, decision making or closeout.

YAML Ownership

config/cicd-branch-followers.yaml owns controller settings and the follower registry: id, adapter, source/target configRefs, command argv, native status object refs, 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.

Status and decision inputs are Kubernetes-native:

source: k8s git-mirror cache ref and immutable snapshot ref;
CI: Tekton PipelineRun.status.conditions;
deployment: Argo Application.status.sync and Application.status.health;
runtime: selected Deployment/StatefulSet readiness plus source commit labels, annotations or env.

The branch follower must not parse downstream CLI stdout/stderr, kubectl human tables, argo text, tkn text, or curl output to infer observed sha, target sha, readiness or closeout. kubectl -o json may be used inside the controller/Job as a structured Kubernetes API transport only.

run-once --dry-run is read-only for deployment: it may refresh the state ConfigMap with current native observations, but it must not trigger adapters.

4.1 KiB Raw Blame History