Quality Gate

You might say

Why is my Pull Request blocked with an error saying 'Quality gate failed'?

A mandatory automated verification checkpoint before merging or deploying code that blocks the pipeline if any rule failsFor example, opening a Pull Request triggers automated tests, lint checks, and coverage verification where any failure blocks merging. A quality gate serves as an impartial checkpoint enforcing team standards; it does not author tests for you, and failures require fixing the underlying bugs rather than blindly bypassing the check.
Know first
Unit TestCI
Quality Gates
PR #42 Quality GateBLOCKED
✓ Unit tests (45/45) ✓ Linter & formatting ✕ Core coverage 68% (< 80%)
Quality Gate≠Feature Flag

Feature Flag dynamically enables or disables features at runtime based on user or tenant identity; Quality Gate uses automated tests during development to stop broken builds before production.

Quality Gate≠CI

CI is the automated pipeline workflow that clones repositories and runs test scripts; Quality Gate is the rule set deciding whether results qualify for approval or immediate blocking.

When to use it

  • Enable branch protection so pull requests cannot merge until all quality gates pass
    See field rules at a glance
    emailRequired · email formatpriceNumber · greater than 0roleuser / admin
  • Require passing unit tests, clean lint reports, and type checks to stop regressions early
    Keep rules together in one schema
    email: string().email()price: number().positive()role: enum(["user", "admin"])
  • Define unambiguous thresholds such as zero fatal errors and 100% passing test suites
    Write to the database only after validation passes
    Receive input→Rule check→Write to database
  • Inspect CI failure logs to guide AI assistants on exact failing files and errors
    Errors should point to the specific field.
    Product price-3Below the inputPrice must be greater than 0

When NOT to use it

  • Abuse administrator privileges to bypass failing gates and push broken code to main
    Page-side checks can be bypassed
    Skip form→Request API directly→Backend still needs validation
  • Set flaky or intermittent tests as blocking gates, paralyzing regular development merges
    Do not silently change critical data.
    User inputPrice -99 → System silently changes it toPrice 99
    Reject it clearly and ask the user to confirm.
  • Set unrealistic thresholds like demanding 100% coverage on day-one prototype code
    Do not show internal errors to users.
    PrismaClientKnownRequestErrorat node_modules/runtime/library.js:129:42
    The page should say: Unable to save right now. Please try again later.
  • Rely only on verbal self-testing promises without automated gate enforcement in CI
    Status code and result contradict each other
    HTTP200 OKResponse bodyerror: invalid email
    The frontend can easily mistake failure for success.
Anatomy
Metrics (Tests/Lint/Sec)evaluated byThresholdyieldsPass or Block
Concrete metrics collected by CI, such as unit test pass rate, lint errors, and test coverage
Pre-agreed criteria for admission, such as 0 fatal errors and 100% passing tests
Final decision: pass allows merge or deployment, whereas failure blocks the pipeline
Variants
Merge Gate
CI: 45 passed, 0 failed → MERGEABLE
Guard branch merges into trunk by verifying correctness and linting.
Deployment Gate
healthCheck == OK && errorRate < 0.1%
Ensure stable staging verification and low error rates before production rollout.
Security Gate
SAST scan: 0 critical vulnerabilities
Block hardcoded secrets, known vulnerable dependencies, and security leaks.
Typical use cases
Automated checkpoint on Pull Request submission
PR GateFailing tests block merging
Checks1 failing unit test → Merge buttonLocked by GitHub
Prevents unverified code from corrupting the trunk
Deployment gating before production release
Release GateAnomaly halts production release
Canary 5%→Error spike→Gate halts rollout
Halts full deployment when metrics exceed acceptable thresholds
Security scanning for secrets and dependencies
Security GateDetecting leaked credentials
Secret scanHardcoded API Key foundGate actionCommit blockedAfter fixEnvironment variable used
Prevents critical credentials from being published to remotes
Enforcing test coverage minimum baselines
Coverage GateUntested code blocked
Required>= 80%Current PR84.2%StatusQuality gate passed
Maintains long-term code health and halts test debt accumulation
Further reading
SonarQube Quality Gate GuideSonarQube ↗GitHub Protected Branches and Status ChecksGitHub ↗