docs backend evidence cd CD 02

CD-02 — Pull-based staging planner, dry run

Status: LOCAL_DONE / INTEGRATION_PENDING Validation: local PASS; real VPS installation and timer run OWED Scope: staging continuous-deploy plan, Phase 2 only. No rollout, backup, migration, landing switch, VPS, k8s, nginx, production or Phase 3 work.

Delivered

• infra/deploy/agent/abastevo-deploy-agent fetches ghcr.io/<owner>/abastevo-release:staging, validates the OCI artifact structure, verifies the manifest layer digest and the cosign keyless certificate identity/issuer, validates abastevo-release-manifest-v1, and checks that the release SHA is an ancestor of main through the anonymous GitHub compare API.
• The agent compares the target release with /var/lib/abastevo-deploy/current.json and writes a mode-600 abastevo-deploy-plan-v1 receipt. It never writes current.json and never calls docker, kubectl, helm or systemctl.
• infra/deploy/agent/systemd/abastevo-deploy-agent.service runs as a dedicated user with flock, ProtectSystem=strict, NoNewPrivileges=yes, PrivateTmp=yes, a read-only home and a two-minute timer.
• infra/deploy/agent/README.md documents the only host config file (/etc/abastevo-deploy/agent.env, mode 600, never committed), prerequisites, installation, receipt/current schemas and scope limits. No secret, token, host, IP or operator-specific path is committed.
• infra/README.md links the planner; make test-deploy-agent runs the failure-behavior harness.

Local validation

• make test-deploy-agent and the Quick gate run the same harness: 33 passed, 0 failed. The harness stubs oras, cosign, curl, docker, kubectl, helm and systemctl and covers: new-release planning, no-change planning, tampered/unsigned manifest, foreign identity, commit ahead/diverged, GitHub 404/403/network failure, registry failure, invalid schema, digest mismatch, missing signature layer, invalid current state and missing configuration. Successful cases assert no deployment-tool call and no current.json creation.
• shellcheck and bash -n pass for the agent and harness.
• Live dry run against the real signed staging artifact from run 40498638802 (SHA 44b7b915...): the agent fetched the public OCI artifact, verified the Sigstore bundle with the exact workflow identity at refs/heads/main, confirmed the SHA is reachable from main, and wrote a plan-only receipt. A second run with a matching current.json wrote no-change; current.json was not modified.
• A real tampered manifest with the original bundle was refused by cosign (invalid signature) before any receipt was written. A direct cosign verify-blob with a foreign workflow identity was refused with no matching CertificateIdentity found.
• The live checks used only anonymous GHCR/GitHub access and no personal token.

Outstanding

• Install the agent, config and systemd units on the staging host and observe a real timer run. The host is not accessed in this delivery.
• Phase 3 owns the schema gate, verified backup, migration job, image rollout, landing switch, smoke checks, rollback and current.json updates.
• Production remains manual behind G09; no production or release action is included.