Setting Up Quality Gates in CI/CD with the Vipr CLI

Code reviews catch a lot, but they cannot catch everything, especially the slow, incremental growth of complexity that happens one pull request at a time. A function gains a few branches here, a component picks up a few more props there, and before anyone notices the maintainability index has dropped below the threshold where changes start getting risky. Quality gates solve this by making complexity a build-time constraint, not a best-effort suggestion.

The Vipr CLI ships with built-in support for quality gates. You define thresholds in a .vipr.config.json file at the root of your repository, and the CLI exits with a non-zero status code when any threshold is exceeded. This means your CI pipeline fails the same way it would for a broken test or a lint error. The feedback loop is immediate and automatic.

Setting Up GitHub Actions

Here is a minimal GitHub Actions workflow that runs Vipr on every pull request and blocks the merge if any file exceeds the configured thresholds:

name: Vipr Quality Gate
on: [pull_request]

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx vipr analyze --format json --output vipr-report.json
      - run: npx vipr gate --config .vipr.config.json --report vipr-report.json

The analyze command produces a full JSON report. The gate command reads that report and checks it against your thresholds. If any file has a cyclomatic complexity above 15, a maintainability index below 40, or whatever limits you have configured, the step fails and the PR is blocked.

Configuring Thresholds

The .vipr.config.json file supports per-metric thresholds with optional glob-based overrides. You might enforce strict limits on core business logic while allowing higher complexity in generated code or test utilities:

{
  "qualityGate": {
    "defaults": {
      "maxCyclomaticComplexity": 15,
      "minMaintainabilityIndex": 40,
      "maxHalsteadDifficulty": 30
    },
    "overrides": [
      {
        "glob": "src/generated/**",
        "maxCyclomaticComplexity": 50,
        "minMaintainabilityIndex": 20
      }
    ]
  }
}

This keeps the gate practical. You do not want false failures from auto-generated code blocking real work.

Beyond GitHub Actions

The CLI works in any CI environment that can run Node.js. For GitLab CI, add a script step with the same two commands. For Jenkins, use a shell step. For Buildkite, add a command step. The interface is the same everywhere: run vipr analyze, then run vipr gate, and let the exit code do the rest. The JSON report can also be uploaded as a build artifact so developers can inspect the full results without re-running the analysis locally.

Quality gates are one of those practices that feel unnecessary until you have been burned by a codebase that slowly became unmaintainable. Adding a five-minute CI step now saves hours of cleanup later. The Vipr CLI is free. There is no reason not to try it on your next pull request.