Reference

CI integration.

ngcompass is designed to run in CI pipelines. It exits with code 0 on success and a non-zero code when violations at or above the failOnSeverity threshold are found.

GitHub Actions SARIF with Code Scanning

The recommended setup for GitHub. SARIF output is uploaded to GitHub Code Scanning, which surfaces violations as inline annotations on pull requests. Install ngcompass locally with ng add ngcompass before committing this workflow so CI uses the locked project dependency.

.github/workflows/ngcompass.yml

01name: ngcompass
02
03on:
04  push:
05  pull_request:
06  workflow_dispatch:
07
08permissions:
09  contents: read
10  security-events: write
11  actions: read
12
13jobs:
14  analyze:
15    runs-on: ubuntu-latest
16
17    steps:
18      - uses: actions/checkout@v4
19
20      - uses: actions/setup-node@v4
21        with:
22          node-version: '20'
23
24      - name: Install dependencies
25        run: npm ci
26
27      - name: Run ngcompass
28        run: npx ngcompass analyze --format sarif > results.sarif
29        continue-on-error: true
30
31      - name: Upload to Code Scanning
32        uses: github/codeql-action/upload-sarif@v4
33        with:
34          sarif_file: results.sarif

GitHub Actions hard gate (no SARIF)

Simpler setup that fails the job directly when violations are found. Good for projects that don't use Code Scanning.

.github/workflows/ngcompass.yml

01name: ngcompass
02
03on: [push, pull_request]
04
05jobs:
06  analyze:
07    runs-on: ubuntu-latest
08    steps:
09      - uses: actions/checkout@v4
10
11      - uses: actions/setup-node@v4
12        with:
13          node-version: '20'
14
15      - name: Install dependencies
16        run: npm ci
17
18      # Exits non-zero if any error-severity violations are found.
19      # Use --profile ci to activate stricter CI-specific rules.
20      - name: Run ngcompass
21        run: npx ngcompass analyze --profile ci

CI profile

Define a ci profile in your config to use stricter rules in CI than you do locally:

ngcompass.config.ts

01profiles: {
02  ci: {
03    failOnSeverity: 'warn',
04    maxWarnings: 0,
05    rules: {
06      'spec-no-focused-test': 'error',
07    },
08  },
09},

Activate it with:

bash

01npx ngcompass analyze --profile ci

Exit codes

0
Analysis passed. No violations at or above failOnSeverity.
1
Violations found, maxWarnings exceeded, or a configuration / runtime error occurred.

Caching in CI

ngcompass caches analysis results between runs. In CI, the cache lives in node_modules/.cache/ngcompass by default. Cache this directory between runs to speed up analysis on large codebases.

yaml

01- uses: actions/cache@v4
02  with:
03    path: node_modules/.cache/ngcompass
04    key: ngcompass-${{ hashFiles('src/**/*.ts') }}

Skip the cache for a specific run with npx ngcompass analyze --force.