CI/CD, Artifacts, Migrations, and API Compatibility
Connect governed agent work to reproducible builds, immutable artifacts, compatibility controls, and delivery systems.
A rapid review of the chapter’s existing Quick Read, principles, definitions, lessons, and review material.
The chapter in one pass.
- Purpose: Connect governed agent work to reproducible builds, immutable artifacts, compatibility controls, and delivery systems.
- Best for: Platform, release, quality, security, and application architects.
- Prerequisites: Software Supply Chain Security and Testing Strategy.
- Reading time: 15 minutes.
- You will learn: How to separate source acceptance, build provenance, artifact promotion, schema change, and API compatibility.
- Keep three ideas: build once and promote by digest; database changes are distributed-system changes; and CI execution is not delivery authority.
Reconstruct and defend this chapter’s architecture.
Reconstruct the architecture, name each boundary, and defend the tradeoffs.
Open the source exercise
Design delivery for a service and three consumers during a schema migration. Add an outdated consumer, failed backfill, mutable dependency, and duplicate deployment webhook. Mark every authoritative record and recovery decision.
3. Enduring Principle
Separate governance from execution
The factory authorizes a build or release candidate, defines required evidence, and reconciles results. CI systems execute build and test jobs. Deployment systems apply an approved artifact. No external provider callback should advance authoritative state without identity, subject digest, policy, and reconciliation.
Build once, promote immutably
The artifact record binds source commit, dependency lock, builder identity, environment digest, commands, SBOM, provenance, signatures, test receipts, and output digest. The same digest moves through environments. Configuration changes remain separately versioned and attributable.
Treat migrations as compatibility windows
Safe database change commonly uses expand, migrate, validate, cut over, and contract phases. Plans identify writers, readers, backfill, dual operation, constraints, load, monitoring, stop conditions, restore, and owner. Destructive contraction waits until all consumers have moved and evidence proves the old shape is unused.
Verify API and event compatibility
Version schemas and identify producers, consumers, optionality, defaults, ordering, idempotency, and retention. Use contract and integration tests against representative consumer versions. A syntactically backward-compatible schema can still change semantics.
Protect the assurance system
Changes to tests, CI definitions, policy, provenance, signing, or deployment require independent review and higher assurance. The implementer cannot weaken the gate and use the weakened gate as proof.
8. Notes and lessons learned
The delivery subject should become more precise as it moves forward: source commit, build recipe, artifact digest, deployment, active configuration, and observed outcome. Reusing “version” for all of them hides failure boundaries.
9. Interview and discussion questions
- Why should the same artifact digest move through environments?
- When is forward correction safer than rollback?
- How do you prevent an agent from weakening its own CI gate?
- What makes an API change semantically incompatible?
- Which provider events require reconciliation?
Review this chapter.
Challenge a claim, boundary, missing failure mode, unclear term, or unsupported evidence statement.
- Claim
- Boundary
- Failure
- Evidence