cxgrdcxgrd docs

Merge Policies

Merge policies let you block, warn, or require review on pull requests based on the actual blast radius of a change — not just file count or diff size.

What a merge policy checks

A merge policy evaluates a PR against your dependency graph and applies rules like:

  • Blast radius threshold — block merges where a change affects more than N downstream files or functions.
  • Critical path protection — require manual approval when a change touches files marked as critical (e.g. auth, billing, database migrations).
  • Risk levels - block merges whose risk level is flagged as critical or high.

These rules run automatically in CI via cxgrd check --ci, so a policy violation blocks the merge the same way a failing test would.

How it's different from a lint rule or test gate

A lint rule checks a file in isolation. A test gate checks whether existing tests pass. Neither one tells you what else in the codebase is affected by a change that touches a shared function, type, or module.

CXGRD builds a dependency graph of your codebase — real import and call relationships — and traces each PR's changes through that graph. If you change a function signature used in 12 other files, CXGRD's blast radius calculation surfaces all 12, even if none of them were touched in the diff and no test currently covers them.

Setting up a merge policy

  1. Install the CXGRD GitHub App on your repository.
  2. Define policy rules in your Team dashboard,
  3. Add cxgrd check --ci to your CI pipeline (GitHub Actions example):
name: cxgrd check

on:
  pull_request:
    branches: [main]

jobs:
  cxgrd:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm install

      - name: Install cxgrd
        run: npm install -g cxgrd

      - name: Scan project
        run: cxgrd scan
        env:
          CXGRD_AUTH_TOKEN: ${{ secrets.CXGRD_AUTH_TOKEN }}

      - name: Run cxgrd check
        run: cxgrd check --ci
        env:
          CXGRD_AUTH_TOKEN: ${{ secrets.CXGRD_AUTH_TOKEN }}

You can get the CXGRD_AUTH_TOKEN from the dashboard itself.

  1. Merges that violate policy are blocked at the PR check level, visible directly in the GitHub PR UI.

Audit logs

Every policy decision — pass, block, or override — is logged with the triggering PR, the blast radius computed, and which rule fired. Team tier includes a dashboard view of this history for compliance and post-incident review.

Related