CI/CD Integration

CognitiveLint is designed to live in your CI pipeline, blocking merges that degrade UX quality just like a failing test.

GitHub Actions

Basic — fail on low score

.github/workflows/cognitivelint.yml

name: Cognitive UX Quality

on: [push, pull_request]

jobs:
  cognitive-ux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run CognitiveLint
        run: npx @cognitivelint/cli scan --min-score 80

With SARIF upload (inline PR annotations)

.github/workflows/cognitivelint.yml

name: Cognitive UX Quality

on: [push, pull_request]

permissions:
  security-events: write

jobs:
  cognitive-ux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run CognitiveLint
        run: |
          npx @cognitivelint/cli scan \
            --format sarif \
            --output cognitivelint.sarif \
            --min-score 80
        continue-on-error: true

      - name: Upload to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: cognitivelint.sarif
          category: cognitive-ux

This causes findings to appear as inline annotations on PR diffs in the GitHub Security tab.

With HTML report artifact

      - name: Run CognitiveLint
        run: |
          npx @cognitivelint/cli scan \
            --format html \
            --output cognitivelint-report.html

      - name: Upload report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: cognitivelint-report
          path: cognitivelint-report.html

GitLab CI

.gitlab-ci.yml

cognitive-ux:
  image: node:20
  stage: test
  script:
    - npx @cognitivelint/cli scan
        --format json
        --output cognitivelint-report.json
        --min-score 80
  artifacts:
    when: always
    reports:
      codequality: cognitivelint-report.json
    paths:
      - cognitivelint-report.json

Exit codes

Code	Meaning
0	Scan passed all thresholds
1	Score below --min-score or findings above --max-findings
2	Config error or scan failure

Use continue-on-error: true in GitHub Actions combined with the SARIF upload step to always upload results even when the job fails.

Recommended thresholds

Start lenient and tighten over time:

Maturity	--min-score	--max-findings
New project	60	unlimited
Growing team	70	50
Stable product	80	20
High quality bar	90	5

Incremental adoption

To avoid fixing all existing issues before you can enforce the threshold, add the exclude config to ignore legacy areas and only enforce on new code:

cognitivelint.config.js

export default {
  include: ['src/features/**/*.tsx'],   // only new features
  exclude: ['src/legacy/**'],            // skip old code
  minScore: 80,
};