How to Integrate Archify Into Your CI/CD Pipeline: A Complete Guide

Archify integrates into CI/CD pipelines through four core CLI commands—render, validate, compare, and deliver—which run non-interactively, output deterministic JSON receipts, and exit with non-zero status on failure, making them ideal for automated build stages.

Archify is a Node-based CLI skill that transforms typed JSON architecture definitions into self-contained HTML diagrams. If you're looking to integrate Archify into your CI/CD pipeline, this guide walks through the exact commands, configuration files, and exit-code semantics that enable automated diagram generation, validation, and PR review.

Why Archify Works Well in CI/CD

Archify's CLI design prioritizes automation. According to the tt-a1i/archify source code, all diagram generation is deterministic—the same JSON input always produces identical HTML output. Commands emit machine-readable JSON receipts and follow Unix exit-code conventions, allowing CI runners to treat failures as pipeline breaks without custom parsing logic.

The four commands you'll use in CI/CD are defined in archify/bin/archify.mjs:

Command	Purpose	CI/CD Stage
render	Generate HTML diagram from JSON IR	Build
validate	Run built-in validator plus artifact checks	Test/Lint
compare	Produce Architecture Delta between versions	PR Review
deliver	Final artifact validation and output	Deploy

Installing Archify in Your CI Environment

Install Archify globally before running any commands. The installation method is documented in the README and implemented via the skills CLI:

npx skills add tt-a1i/archify -g

Alternatively, use npm directly:

npm i -g tt-a1i/archify

Both approaches pull the latest skill package and make the archify binary available to subsequent steps.

Core CI/CD Workflow Steps

Step 1: Render Architecture Diagrams

The render command converts a typed JSON IR into a self-contained HTML file. The usage string and implementation reside in archify/bin/archify.mjs (lines 15-20):

archify render architecture <input.json> <output.html>

Example for a web application:

archify render architecture examples/web-app.architecture.json pr-diagram.html

Step 2: Validate Generated Diagrams

Validation runs the built-in validator and performs final artifact checks via scripts/check-render-output.mjs. The --json flag ensures machine-readable output:

archify validate architecture examples/web-app.architecture.json --json

As implemented in archify/bin/archify.mjs (lines 68-78), validation failures return non-zero exit codes and emit JSON diagnostics to stderr. This lets CI systems fail the build automatically.

Step 3: Compare Versions (PR-Only)

For pull request workflows, the compare command generates an Architecture Delta between base and head versions. The delta logic lives in delta/architecture-delta.mjs and archify/bin/archify.mjs:

archify compare architecture base.json head.json --json > delta-receipt.json

This produces:

• An HTML delta view highlighting added, removed, and changed architectural facts
• A JSON receipt summarizing the comparison

If the comparison detects composition failures, the command exits non-zero, blocking the PR merge.

Step 4: Publish or Fail

Upload artifacts using your CI platform's native mechanisms, or abort on any non-zero exit status. Archify's conventional exit codes require no special handling.

GitHub Actions Integration Example

Create .github/workflows/archify.yml with this complete configuration:

name: Archify CI

on:
  pull_request:
    branches: [ main ]

jobs:
  archify:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Node (>=18)
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install Archify skill
        run: |
          npm ci
          npx skills add tt-a1i/archify -g

      - name: Render current PR diagram
        run: |
          archify render architecture examples/web-app.architecture.json pr-diagram.html

      - name: Validate diagram
        run: |
          archify validate architecture examples/web-app.architecture.json --json

      - name: Compare with main branch (base vs head)
        env:
          BASE_JSON: ${{ github.workspace }}/base.architecture.json
          HEAD_JSON: ${{ github.workspace }}/examples/web-app.architecture.json
        run: |
          git fetch origin main:refs/remotes/origin/main
          git checkout origin/main
          archify render architecture examples/web-app.architecture.json base.architecture.html
          git checkout ${{ github.sha }}
          archify compare architecture $BASE_JSON $HEAD_JSON --json > delta-receipt.json

      - name: Upload diagrams
        uses: actions/upload-artifact@v3
        with:
          name: archify-architecture-diagrams
          path: |
            pr-diagram.html
            delta-receipt.json

This workflow runs on every PR to main, ensuring architectural changes are visually reviewed before merge.

Portable Shell Script for Any CI Runner

For GitLab CI, Azure Pipelines, Jenkins, or other runners, use this minimal shell script:

#!/usr/bin/env sh
set -e

# Install Archify globally

npx skills add tt-a1i/archify -g

# Render diagram from current source

archify render architecture examples/web-app.architecture.json diagram.html

# Validate – script aborts here if validation fails

archify validate architecture examples/web-app.architecture.json --json

# Compare with target branch in PR context

if [ -n "$CI_PULL_REQUEST" ]; then
  git fetch origin "$CI_TARGET_BRANCH"
  git checkout "$CI_TARGET_BRANCH"
  archify render architecture examples/web-app.architecture.json base.json
  git checkout "$CI_COMMIT_SHA"
  archify compare architecture base.json examples/web-app.architecture.json --json > delta.json
fi

The set -e directive ensures immediate failure on any Archify command returning non-zero.

Key Source Files in Archify

Understanding these files helps troubleshoot integration issues:

• archify/bin/archify.mjs — Main CLI entry point defining all commands and their usage strings
• scripts/check-render-output.mjs — Final artifact validation invoked by validate and deliver
• delta/architecture-delta.mjs — Delta algorithm implementation for compare command
• examples/web-app.architecture.json — Reference JSON structure for architecture definitions

Summary

• Install Archify via npx skills add or npm i -g in your CI environment
• Render diagrams deterministically with archify render
• Validate with --json for machine-readable diagnostics and non-zero exit on failure
• Compare PR versions using archify compare to generate Architecture Deltas
• Leverage exit codes — Archify follows Unix conventions for native CI integration
• Reference source files in archify/bin/archify.mjs and delta/architecture-delta.mjs for implementation details

Frequently Asked Questions

What Node version does Archify require?

Archify requires Node.js 18 or higher. Set this in your CI configuration using actions/setup-node@v3 for GitHub Actions or equivalent tools for other platforms.

How does Archify signal validation failures to CI systems?

Archify uses conventional Unix exit codes. Exit code 0 indicates success; any non-zero exit indicates failure. The validate command specifically returns non-zero when scripts/check-render-output.mjs detects issues, allowing CI runners to fail builds without custom parsing.

Can I use Archify in GitLab CI or Jenkins?

Yes. The portable shell script provided in this guide works in any CI system that supports Node.js execution. Replace GitHub Actions-specific syntax (actions/checkout, actions/upload-artifact) with your platform's equivalents for checkout and artifact storage.

What format does the compare command output?

The compare command outputs two artifacts: an HTML file containing the visual Architecture Delta, and a JSON receipt summarizing added, removed, and changed facts. Use --json to ensure the receipt is machine-readable for downstream automation like PR comment bots.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}