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

> Easily integrate Archify into your CI/CD pipeline using four core CLI commands. Automate your builds with non-interactive, deterministic JSON outputs and failure alerts.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-11

---

**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:

```bash
npx skills add tt-a1i/archify -g

```

Alternatively, use npm directly:

```bash
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):

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

```

Example for a web application:

```bash
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:

```bash
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`:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/.github/workflows/archify.yml) with this complete configuration:

```yaml
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:

```bash
#!/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`](https://github.com/tt-a1i/archify/blob/main/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.