CI/CD Integration

Diff Guardian integrates with GitHub Actions to automatically analyze every pull request and post a structured comment with the results.

GitHub Actions

The recommended approach is the workflow generated by npx dg init. It runs on every PR targeting main or master.

.github/workflows/diff-guardian.yml
name: "Diff-Guardian"

on:
  pull_request:
    branches: [ "main", "master" ]

permissions:
  contents: read
  pull-requests: write

jobs:
  analyze:
    name: API Contract Audit
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install Dependencies
        run: npm ci

      - name: Build WASM Grammars
        run: npm run build:grammars

      - name: Build
        run: npm run build

      - name: Run Diff-Guardian
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: npx dg

Key details

fetch-depth: 0

The fetch-depth: 0 option ensures the full git history is available. Diff Guardian needs to access both the base branch and the PR head to extract source files from both refs.

Smart default mode

When npx dg runs without arguments inside GitHub Actions, it automatically detects the CI environment and:

  1. Reads GITHUB_BASE_REF as the base ref (e.g., origin/main)
  2. Reads GITHUB_HEAD_SHA as the head ref (the actual PR commit, not the merge commit)
  3. Uses the GitHub Reporter to post a PR comment
  4. Always exits 0 — the PR comment is advisory, not blocking

GITHUB_HEAD_SHA

This is critical. GitHub's default GITHUB_SHA in PR context is a merge commit — not the actual head of the PR branch. By passing GITHUB_HEAD_SHA explicitly from the event payload, Diff Guardian analyzes the correct code.

Environment variables

VariableSourcePurpose
GITHUB_ACTIONSAuto-set by GitHubTriggers CI mode detection in smart default
GITHUB_TOKENSecretsUsed to post PR comments via GitHub API
GITHUB_HEAD_SHAWorkflow envThe actual PR head commit SHA
GITHUB_BASE_REFAuto-set by GitHubBase branch name (e.g., "main")
GITHUB_REPOSITORYAuto-set by GitHubRepo slug (e.g., "owner/repo") for API calls
GITHUB_REFAuto-set by GitHubUsed to extract the PR number

Exit codes in CI

CodeBehavior
0Always. CI mode is advisory — results are posted as a PR comment, never blocking.
2Infrastructure failure (missing grammars, OOM). The CI check turns red to alert the team.

PR comment format

The GitHub Reporter posts a single comment per PR, updating it on each push. The comment includes:

  • A summary table: total changes, breaking count, warning count, safe count
  • Detailed per-change breakdown with file paths, line numbers, and rule IDs
  • Call-site tracing results for breaking changes

WASM grammar caching

The cache: 'npm' setting in the Node.js setup step cachesnode_modules across runs. Since WASM grammars are installed as npm packages, they are cached automatically — subsequent CI runs skip the grammar download.