Archify
Archify Deployment: Operate Deterministic Diagram Builds in CI
A production-minded Archify deployment guide covering pinned skills, evidence inputs, last-good previews, export checks, and rollback.
What you will learn
- Version Archify inputs and compiler
- Design CI validation and last-good gates
- Operate safe export and rollback paths
Before you start
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Key takeaways
- Pin compiler and authored facts together.
- Make validation and last-good previews release gates.
- Treat exports, permissions, and visual diffs as operational surfaces.
Pin the compiler and the facts
A reproducible Archify build has two versioned inputs: the Archify skill/compiler and the authored JSON or repository revision that supplies the facts. Pin both, record the agent host, and publish the validation receipt with the generated artifact. A mutable skill or moving branch can change layout and diagnostics without a source change.
Keep secrets and private source out of the rendered artifact unless the repository policy explicitly permits them. Prefer a sanitized architecture fixture for public CI and link back to the private evidence system when necessary.
Use last-good as an explicit release boundary
The README describes validation and last-good preview behavior. In CI, render the candidate beside the last accepted artifact, fail the job on schema or layout errors, and keep the last-good output available for reviewers. Do not replace a trustworthy diagram with a partially rendered candidate just because the export step produced a file.
Compare normalized JSON and visual diffs for a fixed input. A changed edge, missing source trace, or unexpected animation should be reviewed as a semantic change, not dismissed as cosmetic noise.
Harden exports and permissions
Run diagram generation with least-privilege access to the repository and an isolated output directory. Check that HTML is self-contained, external requests are expected, and generated media cannot escape the artifact root. Treat agent-produced JSON and source descriptions as untrusted input to the renderer.
Collect duration, node/edge counts, validation status, export format, artifact checksum, and input revision. These fields help distinguish a real architecture change from a toolchain or environment drift.
Upgrade and rollback
Canary a new Archify release on representative diagrams, including sequence and lifecycle cases, and compare validation, render, export, and source-trace results. Keep the previous skill revision and last-good artifacts available so rollback is a versioned change rather than a manual redraw.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Pin the Archify skill and input revision.
- 2
Run validation and candidate/last-good comparisons in an isolated job.
- 3
Verify self-contained exports, permissions, checksums, and source traces.
- 4
Canary upgrades and retain a rollback revision and artifact.
Copy-ready example
archify:
skill_revision: <commit>
input_revision: <commit>
validation: required
last_good: artifacts/architecture-last-good.html
output_sha256: <recorded-hash>Frequently asked questions
Should CI publish every render even when validation fails?
Keep failed output as a review artifact, but publish it as failed and preserve the last-good diagram as the trusted release surface.
What belongs in the build record?
Record skill/compiler revision, input revision, host, validation status, node/edge counts, export format, duration, and checksum.
Sources
- Archify README (captured 2026-08-31)Source checked 2026-08-31
- Archify repositorySource checked 2026-08-31