A plain-language first look before any details.

Jenkins is a free, open-source automation server that builds, tests and delivers software. Its work is written as a pipeline, a recipe stored in a text file called the Jenkinsfile. A pipeline is split into stages, such as Build, Test and Deploy, and each stage contains steps, the single actions Jenkins performs.

A quality gate is a set of pass-or-fail rules checked at a chosen point in the pipeline. The rules are about the health of the code and the build: do the tests pass, is enough of the new code covered by tests, are there serious security problems, is the code becoming messier? The gate collects the answers and gives one verdict: open or closed.

What a gate is not

A gate is not a single tool. Jenkins does not have one button called “quality gate.” It is an idea that you build from several pieces: test reports, coverage numbers, code analysis results, security scans and sometimes a human sign-off. Some tools, such as SonarQube, offer their own gate feature that Jenkins can wait for. Others, such as the Jenkins plugins for warnings and coverage, let you set thresholds directly inside the pipeline.

Teams in banking, retail, healthcare and open-source projects all use gates. The exact checks differ, but the shape is always the same: measure, compare with an agreed standard, decide, and tell people clearly why.

The problem they solve and how the idea grew.

The problem: quality decays quietly

Without gates, quality depends on memory and goodwill. Reviewers are busy. Deadlines press. A reviewer may not notice that a change removed a test or added a risky dependency. Each small compromise is reasonable in the moment, yet the total effect is a slow decline that nobody chose and nobody can point to.

There is also a cost of timing. A defect found while writing the code costs minutes to fix. The same defect found in testing costs hours. Found by customers, it can cost days of work, lost trust and sometimes real money. Gates move the discovery earlier, to the moment when fixing is cheapest.

A handful of small ideas that make everything else easy.

Metric

A metric is a number that describes something about the code or the build, such as the percentage of lines covered by tests or the count of serious security issues.

Threshold

A threshold is the line a metric must not cross, such as “coverage must be at least 80 percent.” A gate is a group of thresholds.

Condition

A condition is one rule inside a gate, pairing a metric with a threshold. A gate usually contains several conditions and closes if any important one fails.

Build result

Every run finishes with a result: success, unstable, failure or aborted. Gates use these results to signal their verdict. Failure is a hard stop. Unstable is a yellow warning that lets the build continue but draws attention.

Static analysis and coverage

Static analysis examines code without running it, looking for bugs, risky patterns and messy structure. Code coverage measures how much of the code is executed by the tests. Both produce metrics that gates like to use.

New code and overall code

New code means the lines changed recently, such as in the current pull request. Overall code means everything. This difference is the secret to gates that people accept, and Chapter 13 gives it a whole section.

Which parts of a Jenkins setup work together to make a gate.

A quality gate is not one component. It is a small system. Jenkins runs the checks and collects the numbers. Tools produce the measurements. A decision point compares them with the rules. The result flows back to the people and to the code host.

flowchart LR
    DEV["Developer pushes code"] --> SCM["Source Control Server"]
    SCM -->|"webhook"| CTRL["Jenkins Controller"]
    CTRL --> AGT["Build Agent"]
    AGT --> T["Test runner"]
    AGT --> COV["Coverage tool"]
    AGT --> SA["Static analysis and security scanners"]
    T --> RES["Reports"]
    COV --> RES
    SA --> SQ["Analysis server such as SonarQube"]
    RES --> GATE{"Quality gate"}
    SQ --> GATE
    GATE -->|"Pass"| NEXT["Next stage or deploy"]
    GATE -->|"Fail"| STOP["Stop and report"]
    GATE -->|"Warn"| YEL["Continue as unstable"]
    GATE --> STAT["Status back to pull request"]

Read the diagram from left to right. A push starts a build on an agent. The agent runs tests, measures coverage and runs scanners. Some results stay in Jenkins as reports. Others go to an analysis server, which stores history and computes its own verdict. The gate collects everything, and the verdict controls the pipeline and is reported back to the pull request, so reviewers see a green tick or a red cross without opening Jenkins.

A gate can check many different things. Here are the common families.

Automatic and human gates

Most gates are automatic, because machines are consistent and fast. Some decisions need human judgment, such as approving a release to customers. Good pipelines use both: machines check everything that has a rule, and humans decide the few things that need judgment.

Failure stops the run. Unstable warns but continues. Choosing between them is a policy decision.

When a condition is not met, Jenkins can react in two ways. It can mark the build as failed, which stops later stages, or as unstable, shown in yellow, which lets the pipeline continue but signals a problem. The choice expresses how serious you consider the condition.

flowchart TD
    M["Metric measured"] --> C{"Threshold met?"}
    C -->|"Yes"| P["Pass: continue"]
    C -->|"No"| S{"How serious?"}
    S -->|"Critical"| H["Hard gate: mark failure and stop"]
    S -->|"Moderate"| W["Soft gate: mark unstable and continue"]
    S -->|"Experimental"| A["Advisory: record and continue"]
    H --> N["Notify team with reason"]
    W --> N

A common growth path

When you introduce a new check, begin as advisory, so people see the numbers without being blocked. After a few weeks, make it soft, so breaches are visible in yellow. When the team has cleared the backlog and trusts the rule, make it hard. This gentle path avoids the anger that comes when a brand-new gate suddenly blocks everyone.

The earlier a problem is caught, the cheaper it is to fix.

The phrase shift left means moving checks earlier in the pipeline, toward the developer’s first push. Imagine the pipeline as a line from left to right, ending at production. Cheap, fast checks belong on the left. Slow, expensive checks belong on the right, where fewer changes reach them.

flowchart LR
    G1["Gate 1: build, lint, unit tests"] --> G2["Gate 2: coverage and static analysis"]
    G2 --> G3["Gate 3: dependency and security scan"]
    G3 --> G4["Gate 4: integration and performance tests"]
    G4 --> G5["Gate 5: manual approval"]
    G5 --> G6["Gate 6: post-deploy health checks"]
    G1 -. "seconds" .-> T1["Fast feedback"]
    G4 -. "minutes" .-> T2["Slower feedback"]
    G6 -. "after release" .-> T3["Slowest, safest"]

Placing a check too far right wastes effort: a slow test that fails after twenty minutes could have been replaced by a quick check that fails after two. Placing a slow check too far left wastes everyone’s time: a fifteen-minute scan on every push makes developers wait. Balance speed against value.

The foundation: do the tests pass?

The simplest gate is that every test must pass. Jenkins helps through the junit step, which reads standard test result files and publishes pass and fail counts, trends and details. When tests fail, the step marks the run unstable by default, which is the yellow state, and the test command itself may mark it failed if it returns an error.

Making the gate strict

• Treat failed tests as a hard stop for anything beyond experimental branches. Yellow builds can slip into releases unless you check the result.
• Watch skipped tests. A gate that counts only failures can be satisfied by skipping everything. Report the number skipped and set a limit on it.
• Watch missing results. If the test step produced no result files at all, that is a failure, not a pass. Many pipelines silently pass because “no failures” was recorded when nothing ran.
• Watch test count. A sudden drop in the number of tests is a warning sign even if all pass.

How much of the code do the tests actually exercise?

Code coverage measures the share of code that runs while tests execute. The common flavors are line coverage, the percentage of lines executed, and branch coverage, the percentage of decision paths, such as both sides of an if, taken. Coverage tools produce a report, and Jenkins coverage plugins read it and can enforce thresholds directly in the pipeline.

What coverage tells you, and what it does not

Setting a useful coverage gate

• Gate the coverage of new code, not the whole project, so legacy code does not block every change.
• Use a level people can reach, commonly somewhere between 70 and 85 percent for new code, and adjust for the kind of software.
• Consider both line and branch coverage. Branch coverage is harder to fake.
• Add a “no drop” rule, so overall coverage cannot fall below the current level, which protects against slow decay.

Letting tools read the code and report problems.

Static analysis tools examine code without running it. They find likely bugs, unsafe patterns, style violations and needless complexity. The Jenkins Warnings plugin family collects reports from many such tools and shows them together, with trends and details. Its recording step can also apply quality gates: you say, for example, “fail the build if there are any new high-severity issues,” or “mark it unstable if the total exceeds fifty.”

Two ways to count

Severity and reaction

Not all issues are equal. Most gates weigh them by severity. A common arrangement is to fail on any new high-severity issue, mark unstable on many new medium ones, and merely record low-severity findings. This keeps the gate focused on what matters.

The most widely used gate service and how Jenkins works with it.

SonarQube is a code quality server. It stores the results of code analysis over time and lets administrators define a quality gate: a set of conditions on metrics such as coverage, duplication, bugs, vulnerabilities and code smells. Each time code is analyzed, SonarQube compares the results with the gate and produces a status, typically passed or failed.

A typical default gate

The default gate that many installations start with checks the new code only. Commonly it requires that coverage on new code is at least 80 percent, duplicated lines on new code are 3 percent or fewer, the reliability, security and maintainability ratings for new code are the best grade, and security hotspots on new code have all been reviewed. Exact defaults vary by version and edition, so check your own server.

How Jenkins and SonarQube cooperate

flowchart TD
    A["Pipeline stage: analysis step runs scanner"] --> B["Scanner sends results to SonarQube server"]
    B --> C["SonarQube processes results in the background"]
    C --> D["SonarQube evaluates quality gate"]
    D --> E["SonarQube sends webhook to Jenkins"]
    E --> F["Pipeline wait step receives status"]
    F --> G{"Status"}
    G -->|"Passed"| H["Pipeline continues"]
    G -->|"Failed"| I["Pipeline stops"]

The wait step is simple, but three details make the difference between a smooth gate and a stuck pipeline.

Detail one: the webhook must exist

The waitForQualityGate step normally depends on the webhook from SonarQube. If the webhook is missing or points to the wrong address, Jenkins never hears the answer and waits, and waits. This is the most common gate problem of all. When a gate stage seems stuck, check the webhook delivery history on the SonarQube side first.

Detail two: always set a timeout

Wrap the wait in a timeout so a lost message cannot hold a build forever. A few minutes is usually enough for normal projects, longer for very large ones. When the timeout expires, the build ends as aborted, and your post section can report clearly what happened.

Detail three: do not hold an agent

Just as with the input step, waiting inside a machine block ties up an executor, a work slot on an agent, while doing nothing. Since the scanner has already sent its results, the wait can happen outside any agent, on the controller, which is nearly free. In practice this means placing the wait in its own stage with no agent, or after the agent block has ended.

flowchart LR
    subgraph BAD["Wasteful"]
        B1["Agent allocated"] --> B2["Scan"]
        B2 --> B3["Wait for gate while agent held"]
        B3 --> B4["Next steps"]
    end
    subgraph GOOD["Efficient"]
        G1["Agent allocated"] --> G2["Scan"]
        G2 --> G3["Agent released"]
        G3 --> G4["Wait for gate with timeout, no agent"]
        G4 --> G5["Agent allocated again for next steps"]
    end

The idea that makes gates fair, and therefore accepted.

Imagine joining a project with thousands of existing problems. If a gate demanded that all of them be fixed before anything can ship, the gate would be closed forever, and everyone would soon find a way to switch it off. A better approach is to apply strict rules only to the code that people are changing now. This is often called Clean as You Code.

What counts as new

A reference point decides what is “new”: for a pull request, the target branch; for a main branch, the previous release or a period such as the last thirty days. Every tool lets you choose the definition. Pick one that matches your release rhythm, and explain it to the team.

Stopping known dangers before they ship.

Security gates check for problems that would be costly if released. They come in several flavors, each scanning a different part of what you ship.

Choosing thresholds for security

A sensible pattern is to block on critical and high-severity findings that have a known fix, warn on medium ones, and record the rest. Blocking on everything, including findings without any available fix, teaches people to ignore the gate. Blocking on nothing wastes the scan.

Checking that the software is not just correct, but fast and steady enough.

Some quality problems show up only under load: pages that become slow, memory that grows, requests that fail one time in a hundred. Performance gates run load tests against a test environment and compare results with limits, such as “ninety-fifth percentile response time under 400 milliseconds” or “error rate below 0.5 percent.” A Jenkins plugin for performance testing can read the results and mark the build accordingly.

Making performance gates trustworthy

• Compare with a baseline, the last good run, rather than a fixed number, so normal variation does not cause alarms.
• Allow a tolerance. A five percent slowdown may be noise; a thirty percent slowdown is not.
• Use a stable test environment. Results from shared, noisy machines vary wildly and destroy trust.
• Keep the test short enough to be practical, and run heavier tests on a schedule instead of on every change.

Reliability gates after release

The last gate does not sit before release, but after it. After a deployment, health checks, error rates and key business numbers are watched for a few minutes. If they cross limits, the pipeline rolls back automatically. This turns the real world into the final test.

flowchart TD
    D["Deploy new version to small share of users"] --> W["Watch error rate and response time"]
    W --> Q{"Within limits?"}
    Q -->|"Yes"| E["Expand to all users"]
    Q -->|"No"| R["Roll back automatically"]
    R --> N["Notify team and open incident"]
    E --> F["Mark release healthy"]

When a human decision belongs in the pipeline.

Some decisions cannot be reduced to a rule. Is this the right day to release? Has the product owner confirmed the new screen? Has the security team reviewed this unusual change? For these, Jenkins offers the input step, which pauses the pipeline and waits for an authorized person to click Proceed or Abort.

Rules for a good manual gate

• Automate first. Present the human with evidence: test results, scan summaries, the change list. Do not ask them to hunt for it.
• Restrict who may approve to a named group, and record who did.
• Set a timeout, so forgotten builds do not pile up.
• Wait outside any agent, so no work slot is held.
• Use it sparingly. Too many manual gates turn approvers into rubber stamps.

Different builds deserve different gates.

In a Multibranch Pipeline, Jenkins builds pull requests, main branches, release branches and tags from the same pipeline file. One gate for everything is either too weak for releases or too slow for pull requests. The better approach is to layer the gates, using the branch, change request and tag conditions to decide which stages run.

flowchart TD
    B["Build starts"] --> T{"Build type"}
    T -->|"Pull request"| PR["Fast gate: unit tests, new-code coverage, static analysis"]
    T -->|"Main branch"| MB["Full gate: everything above plus integration tests and security scans"]
    T -->|"Release branch"| RB["Release gate: full gate plus performance tests"]
    T -->|"Tag"| TG["Publish gate: approval and signing checks"]
    PR --> ST["Status on pull request"]
    MB --> DEP["Deploy to staging"]
    RB --> APP["Manual approval"]
    TG --> PUB["Publish release"]

The time budget matters. If a pull request gate takes forty minutes, developers will batch their changes into large, risky pull requests to avoid waiting, which defeats the purpose. Aim for feedback in the time it takes to get a coffee.

A gate that can be skipped is only a suggestion.

A gate inside Jenkins stops the pipeline, but it does not by itself stop someone from merging a pull request. To make the gate binding, connect it to the code host. Jenkins reports the verdict of each build as a status check on the pull request. The code host can then be told, through branch protection rules, that the pull request cannot be merged unless specific checks have passed.

Numbers that are too soft mean nothing. Numbers that are too hard get ignored.

A threshold is a promise the team makes to itself. To be believed, it must be achievable, meaningful and stable. Picking numbers out of the air, or copying another company’s numbers, usually goes badly.

flowchart LR
    A["Measure current level"] --> B["Set gate at current level"]
    B --> C["Team meets it comfortably"]
    C --> D["Raise threshold a little"]
    D --> E{"Team still meets it?"}
    E -->|"Yes"| C
    E -->|"No"| F["Hold the line and investigate"]
    F --> C

Signs that a threshold is wrong

• Always red: people stop believing it and look for overrides.
• Always green with a huge margin: it is not protecting anything.
• Frequently overridden: the rule may be unfair, or the exceptions may be the real rule.
• Debated in every review: the team does not agree on why it exists. Write down the reason.

Real life has exceptions. Plan for them, or people will invent their own.

Sooner or later a gate blocks something that should go out. A critical fix must be released tonight and one non-essential condition is failing. If no official exception route exists, people bypass the whole system: they disable the check, edit the pipeline, or ask an administrator to force the merge. A planned exception path is far safer than an improvised one.

flowchart TD
    F["Gate fails"] --> Q{"Genuine problem?"}
    Q -->|"Yes"| FIX["Fix the code and rerun"]
    Q -->|"No, false positive"| MARK["Mark finding as accepted in the tool with reason"]
    Q -->|"Real but urgent"| WAIV["Request waiver from named approvers"]
    WAIV --> REC["Record reason, owner and expiry date"]
    REC --> REL["Release with waiver"]
    REL --> FU["Follow-up task created and tracked"]

Three forces that quietly destroy trust in a gate.

Flaky tests

A flaky test sometimes passes and sometimes fails on identical code. It might depend on timing, on shared data, or on an outside service. Flaky tests are poison for gates: a red build that means nothing teaches everyone to rerun until green. Track flaky tests, fix or quarantine them quickly, and keep the count visible. A retry step can hide the problem for a while, but retries should be reported, never silent.

False positives

Analysis tools sometimes report a problem that is not real. If there is no easy, recorded way to mark a finding as accepted, developers will grow resentful, and rightly so. Give them a route, keep it accountable, and periodically review accepted findings.

Gaming the numbers

When a number becomes a target, people learn to hit the number instead of the goal. Coverage is the classic case: tests that run code but assert nothing raise coverage without catching bugs. Code smells are “fixed” by moving them around. This is often called Goodhart’s law: a measure that becomes a target stops being a good measure.

A gate that anyone can quietly edit is not a gate.

Gate rules live in several places: the Jenkinsfile, the settings of the analysis server, plugin configuration and the code host’s branch protection. Each is a place where someone could weaken the standard, on purpose or by accident.

How to know that your gates are healthy, fair and fast.

Make every verdict explain itself

A gate that says only “failed” wastes everyone’s time. Each failure should say which condition broke, what the value was, what the limit was, and where to click to see details. Send this summary to the pull request and to chat, with a link to the report. A good message answers the developer’s first three questions before they ask.

Metrics worth watching

Keeping gates fast

• Run independent checks in parallel. Tests, static analysis and dependency scans rarely depend on each other.
• Cache dependencies between builds so scans do not download the world each time.
• Analyze incrementally where the tool supports it, looking only at changed files for pull requests.
• Fail fast. Put the cheapest, most likely-to-fail checks first, so a broken build stops in seconds.
• Move slow checks off the pull request, to main or to a schedule.

Those numbers are only an illustration, but the effect is real. With 30 pushes a day across a team, saving twenty-eight minutes each gives back well over thirteen hours of waiting every single day.

Proven ways of arranging quality gates.

Habits that look fine at first and hurt later.

A checklist to apply to any Jenkins setup today.

Mistakes people make when they are new

Forgetting to test the failure path. Many teams build a gate and never see it fail. Break something on purpose on a test branch and confirm the pipeline stops and the message is clear.

Trusting an empty result. “No issues found” can mean the scanner never ran. Require evidence that the tool actually analyzed something.

Mixing up new and overall. A gate on overall coverage feels strict but blocks the wrong people. Decide deliberately which you are measuring.

Ignoring the wait step’s abort setting. Without it, a failed SonarQube verdict may not stop the pipeline.

Never revisiting the rules. A gate written three years ago for a different code base may protect nothing today.

An honest look at what quality gates do well and where they strain.

Trade-offs to weigh

There is no universally right answer. The right settings depend on the risk of your software, the maturity of your team and the speed you need. Choose on purpose and write down why.

How the ideas look in the kinds of organizations that run Jenkins at scale.

Follow one imaginary team through a change.

A team owns a booking service. Their Multibranch Pipeline uses a shared library that provides the standard quality gate. The analysis server holds the gate definition, and the code host requires the Jenkins check before any merge to main.

At no point did anyone need to remember a rule. The gates carried the standard, gave clear feedback, and kept a record. The humans spent their attention on the parts that needed judgment.

Symptoms, likely causes and calm fixes.

A calm debugging routine

1. Read the verdict message for the failing condition, value and limit.
2. Open the report behind that number, not just the summary.
3. Check that the tool really ran, using the log of the stage.
4. Check the reference point used for new code.
5. Reproduce on a test branch and change one thing at a time.

Every important word in this guide in one place.

Short answers to the questions that come up most often.

The whole story in a few lines.

A quality gate turns good intentions into automatic decisions. It measures the health of a change, compares it with written rules, and lets the pipeline continue, warn or stop. In Jenkins you assemble gates from test reports, coverage and analysis plugins, an analysis server such as SonarQube, security scans and a manual approval step, then make them binding through required status checks. The gates that last are fair, because they focus on new code; fast, because feedback arrives within minutes; explained, because every failure says why; protected, because nobody can quietly weaken them; and humane, because real exceptions have a recorded path.