CI/CD Integration

CI/CD Integration

Arxo is designed for CI/CD integration with fast analysis, policy enforcement, and multiple output formats.

GitHub Actions

Basic Setup

Create .github/workflows/architecture.yml:

name: Architecture Analysis

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for git-based metrics

      - name: Install Arxo
        run: |
          # Download pre-built binary from GitHub Releases (see https://github.com/arxohq/arxo/releases)
          curl -sL "https://github.com/arxohq/arxo/releases/latest/download/arxo-linux-x86_64.tar.gz" | tar xz
          chmod +x arxo && sudo mv arxo /usr/local/bin/

      - name: Run Architecture Analysis
        run: |
          arxo analyze --preset ci --fail-fast

With Caching

Speed up runs with caching:

- name: Cache Arxo Analysis
  uses: actions/cache@v3
  with:
    path: |
      ~/.cache/arxo
    key: arxo-${{ hashFiles('**/*.ts', '**/*.tsx', '**/*.py') }}
    restore-keys: |
      arxo-

- name: Run Analysis
  run: arxo analyze --preset ci

Generate Reports

Upload analysis reports as artifacts:

- name: Generate Report
  run: |
    arxo analyze --format json --output architecture-report.json
    arxo analyze --format html --output architecture-report.html

- name: Upload Report
  uses: actions/upload-artifact@v3
  if: always()
  with:
    name: architecture-reports
    path: |
      architecture-report.json
      architecture-report.html

PR Comments

Post results as PR comments:

- name: Analyze Architecture
  id: analyze
  run: |
    arxo analyze --format json --output report.json
    echo "status=$?" >> $GITHUB_OUTPUT

- name: Comment PR
  uses: actions/github-script@v7
  if: github.event_name == 'pull_request'
  with:
    script: |
      const fs = require('fs');
      const report = JSON.parse(fs.readFileSync('report.json', 'utf8'));

      const violations = report.violations || [];
      const body = violations.length > 0
        ? `## ⚠️ Architecture Violations\n\n${violations.map(v => `- ${v.message}`).join('\n')}`
        : '## ✅ No Architecture Violations';

      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: body
      });

Changed Files Only

Analyze only changed files in PRs:

- name: Analyze Changed Files
  run: |
    arxo analyze --only-changed origin/${{ github.base_ref }}

Baseline Comparison

Compare against main branch:

- name: Compare with Baseline
  run: |
    arxo analyze --baseline origin/main --format json --output diff.json

---

GitLab CI

Create .gitlab-ci.yml:

architecture:
  stage: test
  image: ubuntu:22.04

  cache:
    paths:
      - .cache/arxo

  before_script:
    - apt-get update && apt-get install -y curl
    - curl -sL "https://github.com/arxohq/arxo/releases/latest/download/arxo-linux-x86_64.tar.gz" | tar xz
    - chmod +x arxo && mv arxo /usr/local/bin/

  script:
    - arxo analyze --preset ci --fail-fast

  artifacts:
    when: always
    paths:
      - architecture-report.json
    reports:
      junit: architecture-report.xml

---

Jenkins

Create Jenkinsfile:

pipeline {
    agent any

    stages {
        stage('Architecture Analysis') {
            steps {
                sh 'curl -sL "https://github.com/arxohq/arxo/releases/latest/download/arxo-linux-x86_64.tar.gz" | tar xz && chmod +x arxo && sudo mv arxo /usr/local/bin/'
                sh 'arxo analyze --preset ci --format json --output report.json'
            }
        }

        stage('Archive Reports') {
            steps {
                archiveArtifacts artifacts: 'report.json', allowEmptyArchive: false
                publishHTML([
                    reportDir: '.',
                    reportFiles: 'report.html',
                    reportName: 'Architecture Report'
                ])
            }
        }
    }

    post {
        failure {
            echo 'Architecture violations detected!'
        }
    }
}

---

CircleCI

Create .circleci/config.yml:

version: 2.1

jobs:
  analyze:
    docker:
      - image: ubuntu:22.04

    steps:
      - checkout

      - restore_cache:
          keys:
            - arxo-{{ checksum ".cache/arxo" }}

      - run:
          name: Install Arxo
          command: |
            apt-get update && apt-get install -y curl
            curl -sL "https://github.com/arxohq/arxo/releases/latest/download/arxo-linux-x86_64.tar.gz" | tar xz
            chmod +x arxo && sudo mv arxo /usr/local/bin/

      - run:
          name: Analyze Architecture
          command: arxo analyze --preset ci --fail-fast

      - save_cache:
          key: arxo-{{ checksum ".cache/arxo" }}
          paths:
            - ~/.cache/arxo

      - store_artifacts:
          path: architecture-report.json

workflows:
  version: 2
  build:
    jobs:
      - analyze

---

Pre-commit Hooks

Run quick analysis before commits:

Create .git/hooks/pre-commit:

#!/bin/bash

echo "Running architecture analysis..."

# Quick analysis (few seconds)
if ! arxo analyze --quick --quiet; then
    echo "❌ Architecture violations detected!"
    echo "Run: arxo analyze --quick"
    exit 1
fi

echo "✅ Architecture check passed"

Make executable:

chmod +x .git/hooks/pre-commit

Using pre-commit framework

Create .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: arxo
        name: Architecture Analysis
        entry: arxo analyze --quick
        language: system
        pass_filenames: false
        always_run: true

Install:

pip install pre-commit
pre-commit install

---

Docker Integration

Dockerfile

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

# Install Arxo (pre-built binary)
RUN curl -sL "https://github.com/arxohq/arxo/releases/latest/download/arxo-linux-x86_64.tar.gz" | tar xz \
    && chmod +x arxo && mv arxo /usr/local/bin/

COPY . /app
WORKDIR /app

RUN arxo analyze --preset ci --format json --output /report.json

Docker Compose

services:
  arxo:
    image: ubuntu:22.04
    volumes:
      - .:/workspace
    working_dir: /workspace
    command: |
      sh -c "
        apt-get update && apt-get install -y curl &&
        curl -sL https://github.com/arxohq/arxo/releases/latest/download/arxo-linux-x86_64.tar.gz | tar xz &&
        chmod +x arxo && ./arxo analyze --preset ci
      "

---

Configuration Strategies

Preset-Based (Recommended)

Use presets for consistent CI runs:

# Fast CI checks (30 seconds)
arxo analyze --preset ci --fail-fast

# Full analysis (2-5 minutes)
arxo analyze --preset full

Custom Config

Create .arxo.ci.yaml:

data:
  import_graph:
    group_by: folder
    group_depth: 2
    exclude:
      - "**/test/**"
      - "**/node_modules/**"

metrics:
  - id: scc
  - id: propagation_cost
  - id: smells

policy:
  invariants:
    - metric: scc.max_cycle_size
      op: "=="
      value: 0
      message: "No circular dependencies"

    - metric: propagation_cost.system.ratio
      op: "<="
      value: 0.15
      message: "System coupling too high"

run_options:
  fail_fast: true
  quiet: true

Use in CI:

arxo analyze --config .arxo.ci.yaml

---

Performance Tips

1. Use Quick Mode

For PRs, use quick mode:

arxo analyze --quick  # Skips expensive metrics

2. Analyze Changed Files Only

arxo analyze --only-changed HEAD~1

3. Cache Analysis Results

# GitHub Actions
- uses: actions/cache@v3
  with:
    path: ~/.cache/arxo
    key: arxo-${{ hashFiles('**/*.ts') }}

4. Parallel Metrics

Metrics run in parallel by default. Ensure adequate CPU:

# GitHub Actions
runs-on: ubuntu-latest-4-cores

5. Exclude Unnecessary Files

import_graph:
  exclude:
    - "**/node_modules/**"
    - "**/dist/**"
    - "**/test/**"
    - "**/*.test.ts"

---

Exit Codes

Arxo uses standard exit codes for CI integration:

Exit Code	Meaning
0	Success - No violations
1	Policy violations detected
2	Configuration error
3	Analysis error
4	Invalid arguments

Handling Exit Codes

# Fail on violations
arxo analyze --preset ci || exit 1

# Continue on violations (report only)
arxo analyze --preset ci || true

# Fail fast (stop at first violation)
arxo analyze --preset ci --fail-fast

---

Notifications

Slack Integration

#!/bin/bash

STATUS=$(arxo analyze --preset ci --format json --output report.json && echo "success" || echo "failure")

if [ "$STATUS" = "failure" ]; then
  VIOLATIONS=$(jq '.violations | length' report.json)

  curl -X POST -H 'Content-type: application/json' \
    --data "{\"text\":\"❌ Architecture violations: $VIOLATIONS\"}" \
    $SLACK_WEBHOOK_URL
fi

Microsoft Teams

if ! arxo analyze --preset ci; then
  curl -H 'Content-Type: application/json' \
    -d '{
      "@type": "MessageCard",
      "title": "Architecture Violations",
      "text": "CI build failed due to architecture violations"
    }' \
    $TEAMS_WEBHOOK_URL
fi

---

Best Practices

1. Start with Loose Policies - Tighten gradually
2. Use Presets - Consistent across team
3. Cache Analysis Results - Faster CI runs
4. Analyze Changed Files in PRs - Quick feedback
5. Generate HTML Reports - Visual debugging
6. Set Clear Exit Codes - Predictable CI behavior
7. Track Metrics Over Time - Spot trends
8. Document Policies - Why rules exist

---

Troubleshooting

Analysis Too Slow

• Use --quick mode
• Analyze --only-changed files
• Exclude test/build directories
• Cache analysis results

False Positives

• Adjust policy thresholds
• Exclude specific patterns
• Use custom metrics
• Review grouping strategy

Memory Issues

• Reduce max_nodes in config
• Exclude large dependencies
• Use file-level grouping
• Increase CI machine size

---

IDE-Driven CI Workflows

For AI-assisted development workflows, use the MCP server to integrate architecture analysis directly into your IDE:

Quick health check before commit:

Ask your AI assistant:
"Check for circular dependencies in my project"

The AI uses check_cycles via MCP to run instant analysis.

Policy gate in development:

"Verify this change meets our architecture policies"

The AI uses evaluate_policy and analyze_file_impact to validate changes before pushing.

See MCP Workflows for complete IDE-driven development patterns.

---

Next Steps

• MCP Workflows - AI-assisted architecture analysis
• Configuration Guide - Configure policies
• CLI Reference - Command options
• Policy Examples - Real-world policies
• Troubleshooting - Common issues