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: 22.22.0
      - run: npx --yes @vipr/cli analyze 'src/**/*.{ts,tsx}' --format json --output vipr-report.json --fail-threshold 70 --fail-on-critical

The analyze command produces a JSON report and applies the quality gate in the same run. If any file scores below the configured threshold, or if Vipr finds a critical insight and --fail-on-critical is enabled, the step exits non-zero and the PR is blocked.

Configuring Thresholds

The .vipr.config.json file can keep the same output and gate settings in one place, so local runs and CI runs use the same expectations:

{
  "output": {
    "format": "json",
    "failThreshold": 70,
    "failOnCritical": true
  }
}

This keeps the gate practical. You can tune the threshold as the codebase improves instead of blocking useful work on day one.

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 npx --yes @vipr/cli analyze command. For Jenkins, use a shell step. For Buildkite, add a command step. The interface is the same everywhere: run analysis with your gate flags, 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 tend to 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, and the Vipr CLI is free to try on your next pull request.