The NFRGate user guide.

What you get

Twelve features spanning the full loop: catch NFR gaps before merge, route them to the right reviewer, and keep the whole platform observable.

Installation

Every install path ships the same static analyzers and LLM assessment core; extras add the optional API/dashboard, IDE, and telemetry surfaces.

pip install nfrgate                # static analysis + LLM assessment
pip install "nfrgate[api]"         # + the overrides API and findings dashboard (FastAPI/uvicorn)
pip install "nfrgate[lsp]"         # + the nfrgate-lsp language server for IDE integration
pip install "nfrgate[otel]"        # + OpenTelemetry trace/metric export
pip install "nfrgate[dev,api,lsp]" # local development (test suite + all extras)

Or run the packaged API + dashboard via Docker (multi-arch: linux/amd64, linux/arm64):

docker pull ghcr.io/parab-rohit/rubric:latest
docker run --rm -p 8000:8000 -e NFR_GATE_API_KEY=<a-real-secret> ghcr.io/parab-rohit/rubric:latest

Pin a specific released version instead of latest by tag, e.g. ghcr.io/parab-rohit/rubric:0.2.0 — see GitHub Releases for what's available.

Configuration

Every piece of deployment-specific config is an environment variable — no source edits needed to point at different infrastructure.

Using the CI gate

Analyzes the diff on a PR/MR, posts one continuously-updated comment, and fails the job on high-confidence blocking violations. Both examples below are complete, runnable job definitions — not just the invocation line.

GitHub Actions

name: NFRGate

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write   # needed to post/update the PR comment

jobs:
  nfrgate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # full history -- pr_gate.py diffs base...head, a shallow clone can't resolve an arbitrary base SHA

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - run: pip install nfrgate

      - name: Run NFRGate
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: python -m nfr_gate.ci.pr_gate

Reads GITHUB_TOKEN, GITHUB_REPOSITORY, and GITHUB_EVENT_PATH from the standard Actions environment — the three env vars above and GitHub's own automatic ones are everything it needs, no further wiring. This exact shape (installing from a repo checkout instead of PyPI) is what .github/workflows/nfrgate-ci.yml in this repo runs for real, dogfooding it on this project's own PRs.

GitLab CI

nfrgate:
  stage: test
  image: python:3.12-slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    GIT_DEPTH: 0   # full history, same reason as the GitHub Actions example
  script:
    - pip install nfrgate
    - python -m nfr_gate.ci.mr_gate

Reads GitLab's built-in CI_* predefined variables (CI_PROJECT_DIR, CI_MERGE_REQUEST_IID, CI_MERGE_REQUEST_DIFF_BASE_SHA, CI_PROJECT_PATH, CI_API_V4_URL, CI_PROJECT_ID, etc.) automatically — nothing to map by hand. It still needs a token with permission to post MR notes: add a GITLAB_TOKEN CI/CD variable (Settings → CI/CD → Variables, masked + protected — a project or group access token with api scope works) if the job's own CI_JOB_TOKEN isn't allowed to post notes on your instance; GitLab injects CI/CD variables into the job automatically, so nothing in the YAML above needs to reference it explicitly.

Both examples only need the static-analysis path to work out of the box. The LLM-assessment half defaults to a local Ollama model (NFR_GATE_OLLAMA_BASE_URL, http://localhost:11434 by default) — unreachable from a hosted runner unless you also set NFR_GATE_LLM_BACKEND=anthropic and ANTHROPIC_API_KEY, or run on a self-hosted runner with Ollama on it. Static analysis, routing, and blocking all work correctly either way; only the LLM-only/LLM-supplement findings are skipped without one of those two.

Overrides API & CLI

Every routed decision a human overrides is recorded in an auditable log.

nfrgate-api                                        # or: uvicorn nfr_gate.api.app:app
nfrgate-override list --source-ref <ref>
nfrgate-override apply --source-ref <ref> --rule-code T1 --reviewer-id you@example.com --reason "..."

Requires NFR_GATE_API_KEY to be set on the server; the CLI sends it via NFR_GATE_API_URL. GET /healthz is an unauthenticated liveness probe independent of database reachability — point a load balancer's health check there. The API serves plain HTTP; put a TLS-terminating reverse proxy in front of it for any non-localhost deployment.

Findings dashboard

Coverage trend, most-flagged criteria, and AI-vs-human agreement rate — on the same running API, once it's deployed:

GET /dashboard

Open it in a browser, paste in your NFR_GATE_API_KEY, and click Connect — the key is kept in that browser's local storage only, never sent anywhere but your own API.

Notifications

Best-effort Slack and/or Jira notifications fire on blocking failures and on tier0 (always-human-review) failing results — never on a routine pass. Configure one, both, or neither; an unconfigured backend is silently skipped rather than an error. See the NFR_GATE_SLACK_WEBHOOK_URL / NFR_GATE_JIRA_* rows above.

IDE integration

The exact same rule engine that gates PRs in CI, surfaced as inline diagnostics before a PR ever opens.

pip install "nfrgate[lsp]"
nfrgate-lsp   # stdio transport — point any generic LSP client at it (Neovim, Emacs' eglot, ...)

A minimal VS Code extension lives in editors/vscode/ in the repo — see its README for setup (npm install, then F5 to launch an Extension Development Host).

Links