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 divided into stages, such as Build, Test and Deploy, and each stage contains steps, the single actions Jenkins performs.

Performance tuning means changing how a pipeline is written and how Jenkins is set up so that the same work finishes sooner, uses fewer resources, or both. It is not about clever tricks. It is about finding where time goes, removing waste, and doing independent things at the same time.

The same ideas apply whether you run a small team on two machines or a large organization on hundreds. The numbers differ, but the method is identical: measure, find the biggest cost, fix it, and measure again.

The hidden costs of slow pipelines.

Feedback delayed is feedback lessened

The value of a build is the information it gives a developer: “your change is fine” or “your change broke something.” That information is most useful while the developer still remembers the change. After ten minutes the memory is fresh. After an hour, the developer has moved on, and coming back costs time to reload the context.

Slow pipelines change behavior

When feedback is slow, people push large batches of changes to avoid waiting several times. Large changes are harder to review and more likely to hide bugs. When the pipeline is fast, people push small changes, and small changes are safer.

Money and machines

Every minute a build runs holds a work slot, an executor, on a machine. On cloud machines billed by time, slower builds cost more. In a busy installation, slow builds also lengthen the queue for everyone else.

A handful of small ideas that make everything else easy.

Wall-clock time

Wall-clock time is the time on the clock from the moment a build is requested to the moment it finishes. It is what the developer experiences, and it includes waiting.

Queue time and run time

Queue time is how long a build waits for a free machine. Run time is how long it takes once it starts. Tuning run time does nothing for a build that spends most of its life waiting in the queue, so always look at both.

Critical path

The critical path is the longest chain of steps that must happen one after another. Steps that run in parallel do not add up; the longest of them decides the total. Only shortening the critical path shortens the pipeline. Speeding up something that is not on it changes nothing.

Latency and throughput

Latency is how long one build takes. Throughput is how many builds the system can complete per hour. Some changes improve one but hurt the other, for example running many builds at once on one machine raises throughput but slows each build.

Cache

A cache is a saved copy of something expensive to produce, kept so it does not have to be produced again. Downloaded libraries and compiled code are the usual candidates.

Controller and agent

Jenkins has a main server, the controller, and worker machines called agents. Heavy work belongs on agents. The pipeline’s own decision-making runs on the controller and should stay light.

The parts of a Jenkins setup that each add a little delay.

A pipeline run is the journey of a change through several components. Each hop can add delay, and knowing the route tells you where to look.

flowchart LR
    DEV["Developer pushes code"] --> SCM["Source Control Server"]
    SCM -->|"webhook"| CTRL["Jenkins Controller"]
    CTRL --> Q["Build Queue"]
    Q --> AGT["Agent with free executor"]
    AGT --> CO["Checkout"]
    CO --> DEP["Download dependencies"]
    DEP --> BLD["Compile and package"]
    BLD --> TST["Run tests"]
    TST --> PUB["Publish artifacts and reports"]
    PUB --> NOTI["Notify and update status"]
    CTRL -.->|"runs pipeline logic"| AGT
    AGT -.->|"streams logs"| CTRL

Read the diagram from left to right. The push reaches the controller through a webhook, a message sent automatically when something happens. The build waits in the queue for an agent. On the agent, it checks out code, downloads libraries, compiles, tests and publishes. Meanwhile the controller runs the pipeline’s own logic and receives the log lines the agent sends. Time is spent in each box, and the biggest box is usually not the one people suspect.

You cannot fix what you cannot see.

Jenkins gives you several ways to see where time goes, and most cost nothing to switch on.

Switch on timestamps

The timestamps option prefixes each log line with the time. It costs almost nothing and turns a wall of text into a timeline. With it, a gap of four minutes between two lines is immediately visible, and you can ask what happened there.

Separate queue time from run time

The duration shown for a build usually counts only the time after it started running. A build that shows twelve minutes may have waited fifteen minutes before that. Always check the queue separately, or you may spend a week tuning code when the real problem is a shortage of machines.

A repeatable method that keeps you honest.

flowchart LR
    M["Measure: collect durations of many runs"] --> F["Find the biggest cost on the critical path"]
    F --> H["Form a simple hypothesis"]
    H --> C["Change one thing"]
    C --> V["Verify with new measurements"]
    V --> Q{"Improved?"}
    Q -->|"Yes"| K["Keep it and note the gain"]
    Q -->|"No"| R["Revert and try another idea"]
    K --> M
    R --> F

Amdahl’s insight

A simple idea from computer science says that the benefit of speeding up one part is limited by how much of the total that part represents. If tests are ten percent of the pipeline, making them twice as fast saves five percent. If dependency downloads are forty percent, halving them saves twenty. This is why the first step is always to find the biggest piece.

Where the minutes usually hide.

flowchart TD
    T["Total wall-clock time"] --> W["Waiting: queue and agent start-up"]
    T --> S["Setup: checkout and dependencies"]
    T --> B["Build: compile and package"]
    T --> X["Test: unit, integration, end to end"]
    T --> P["Publish: artifacts, reports, notifications"]
    T --> O["Overhead: step start-up, logging, pipeline logic"]

These shares are only typical ranges, not rules. Your own pipeline will differ, which is exactly why measuring matters. But the table shows a useful pattern: setup and waiting together often outweigh the actual building and testing. Many teams focus on the compiler and the test framework when the bigger wins are in the boring parts around them.

The delay before your code is even looked at.

When all the executors on suitable agents are busy, new builds wait in the build queue. Queue time is often the most annoying delay because it is pure idleness: nothing is happening for your change. It is also the delay that no amount of code tuning can fix.

Causes of long queues

• Too little capacity for the number of builds at busy times.
• Labels that split the fleet into small pools, so one pool is full while another sits idle.
• Builds that hold executors while waiting, for example an approval prompt inside an agent block.
• Redundant builds for commits that have already been superseded by newer ones.
• Slow builds that hold slots longer, which lengthens the queue for everyone.

The pipeline script runs on the controller, not on the agent.

This surprises many beginners. When a pipeline runs, the steps that execute commands run on the agent. But the pipeline script itself, the small program that decides what to do next, runs on the controller. Jenkins runs it with a special engine that can pause and resume, so that a pipeline can survive a restart. This engine is slower than ordinary code, and it uses controller memory and processor time.

flowchart LR
    subgraph CT["Controller"]
        SC["Pipeline script logic"]
        LG["Log receiving and storage"]
        ST["State saving to disk"]
    end
    subgraph AG["Agent"]
        CM["Commands: compile, test, package"]
    end
    SC -->|"sends step"| CM
    CM -->|"output lines"| LG
    SC --> ST

The rule

Let agents do the heavy work through ordinary commands and small programs, and keep the pipeline script thin: a coordinator, not a calculator. If a script needs to process a large list or file, write that processing as a normal tool that runs in a command on the agent, and let the pipeline read the short result.

How often a pipeline saves its progress to disk.

To survive a controller restart, a pipeline saves its progress to disk as it goes. Frequent saving is safe but costs disk activity, and on a busy controller with many pipelines the disk can become the bottleneck. Jenkins offers a durability setting that lets you choose how careful to be.

Who should use which

• Performance-optimized suits most ordinary build and test pipelines, which can simply be rerun if the controller crashes. Many teams see a noticeable reduction in disk load and faster pipelines.
• Maximum survivability suits long-running pipelines that would be expensive to restart, such as those with long approvals or lengthy deployments.

The setting can be chosen per pipeline in its options, or as a default for the whole installation. A good approach is a fast default, with the safe setting for the few pipelines that need it.

Every step has a fixed cost, however small its work.

Each pipeline step involves some bookkeeping: the controller records it, sends it to the agent, waits for it, saves state and records the result. For a big step, this cost is invisible. For a thousand tiny steps, it adds up to minutes. A pipeline that runs many small commands one by one is slower than one that runs the same commands as a single script.

The balance

This is not a call for one giant, unreadable script. Steps also give you visibility: when a stage shows steps with names and durations, you can see where time goes. The balance is to group steps that belong together, and keep separate steps where separate timing or separate failure handling helps you.

Do not download the whole history to build one snapshot.

The first thing a build does is fetch the source code. By default, Git downloads the full history of the repository: every commit, every branch, every tag, going back years. For a large, old repository, this can be gigabytes, and on a fresh agent it happens on every build. Yet most builds need only the latest snapshot.

flowchart TD
    A["Build needs the source code"] --> B{"Which checkout style?"}
    B -->|"Full clone"| C["Download all history, branches and tags"]
    B -->|"Shallow clone"| D["Download only recent commits"]
    B -->|"Reference repository"| E["Reuse a local copy, fetch only new commits"]
    B -->|"Sparse checkout"| F["Download only needed folders"]
    C --> S1["Slowest, most complete"]
    D --> S2["Fast for most builds"]
    E --> S3["Very fast on warm agents"]
    F --> S4["Fast for monorepos"]

The same libraries, downloaded again and again.

Most projects depend on many outside libraries. On a fresh agent, the build tool downloads every one of them before compiling. A project with hundreds of libraries can spend more time downloading than building. Since the libraries rarely change between builds, this is wasted effort. Caching removes it.

flowchart LR
    B["Build needs a library"] --> L{"In local cache on the agent?"}
    L -->|"Yes"| U["Use it: instant"]
    L -->|"No"| P{"In package proxy near the agent?"}
    P -->|"Yes"| PD["Download from proxy: fast"]
    P -->|"No"| N["Download from the internet: slow"]
    N --> PS["Proxy stores a copy"]
    PS --> LS["Agent stores a copy"]
    PD --> LS

Keys and freshness

A cache is only safe if it is keyed by exactly what it contains. If dependencies are recorded in a file with exact versions, use a fingerprint of that file as the cache key. When the file changes, the key changes, and a fresh cache is built. Reusing a cache built for different versions causes confusing bugs.

Letting the compiler and packager do less, and do it in parallel.

The build tool, whether Maven, Gradle, npm, a C++ compiler or another, does the actual compilation and packaging. Each has its own options for speed, and many teams never turn them on. Jenkins cannot make a slow tool fast, but it can give the tool a fair chance.

Match the tool to the agent

A build tool that runs eight parallel workers on an agent with two cores will not go faster; it will fight itself. Set parallelism to the number of cores available to the build, which in a container may be limited by its resource settings. Check the resource limits, not just the machine size.

Tests are usually the biggest block of real work.

Once the setup is lean, tests are often the largest share of a pipeline’s time. Speeding them up is a mix of running them smarter, running them side by side and removing waste inside them.

flowchart TD
    S["Whole test suite: 40 minutes"] --> SP["Split by past duration into balanced groups"]
    SP --> G1["Group 1 on agent A: about 10 minutes"]
    SP --> G2["Group 2 on agent B: about 10 minutes"]
    SP --> G3["Group 3 on agent C: about 10 minutes"]
    SP --> G4["Group 4 on agent D: about 10 minutes"]
    G1 --> J["Join results into one report"]
    G2 --> J
    G3 --> J
    G4 --> J

The test pyramid

Many fast unit tests at the bottom, fewer integration tests in the middle and a handful of slow end-to-end tests at the top give the best speed for the confidence they provide. A pipeline with an inverted pyramid, mostly slow end-to-end tests, will always be slow and flaky.

If something is going to fail, let it fail early and cheaply.

The order of stages affects how long a failing build wastes. If a formatting mistake is caught after forty minutes of tests, forty minutes were spent for nothing. If the cheap check runs first, the mistake is reported in thirty seconds.

flowchart LR
    A["Format and lint: 30 seconds"] --> B["Compile: 2 minutes"]
    B --> C["Unit tests: 5 minutes"]
    C --> D["Integration tests: 12 minutes"]
    D --> E["Security scan: 6 minutes"]
    E --> F["Package and publish: 3 minutes"]
    A -.-> X1["Fails here: wasted 30 seconds"]
    C -.-> X2["Fails here: wasted 7.5 minutes"]
    D -.-> X3["Fails here: wasted 19.5 minutes"]

How to order

• Put cheap checks first: formatting, linting, compilation and quick unit tests.
• Put likely-to-fail checks early if they are cheap, since they save the most time when they trigger.
• Put expensive checks late, once the cheap ones have passed.
• Run independent checks in parallel, for example static analysis and unit tests, so neither waits for the other.

Stopping parallel work early

When several branches run in parallel, the fail-fast option stops the remaining ones as soon as one fails, freeing their agents. Without it, the other branches run to the end, and the developer waits for results that no longer change the verdict.

The fastest step is the one that does not run.

Many builds do work that cannot affect the result. A change to a documentation file does not need the full test suite. A change in one service of a large repository does not need every other service rebuilt. Declarative pipelines have conditions, written in a when directive, that decide whether a stage runs, and one of them looks at which files changed.

flowchart TD
    C["Change arrives"] --> Q{"Which files changed?"}
    Q -->|"Only documentation"| D["Skip build and tests; run link check"]
    Q -->|"Only service A"| A["Build and test service A only"]
    Q -->|"Shared library"| ALL["Build and test everything that depends on it"]
    Q -->|"Pipeline definition"| FULL["Run the full pipeline"]

Doing things side by side helps, until it does not.

The parallel step runs several branches at the same time. Used well, it shortens the critical path. Used carelessly, it wastes resources, overloads the controller and even slows the pipeline down.

Every time a stage asks for a new agent, something is set up again.

A pipeline can request an agent at the top, for the whole run, or separately for each stage. Each choice has costs and benefits. Requesting a new agent for every stage frees machines between stages, but every request may wait in the queue, and every new workspace needs a fresh checkout and dependencies.

Container agents and the reuse option

When each stage runs in its own container image, such as one image for building and another for testing, a naive setup asks for a new machine for each stage. Declarative pipelines offer a reuse option for container agents inside a stage: it runs the container on the same machine and in the same workspace that the pipeline already holds, avoiding a new allocation and a new checkout.

Image size and pulling

Starting a container requires its image to be present on the machine. A large image takes time to download the first time. Keep images small, share common base layers, keep popular images on each machine or in a nearby mirror, and avoid pulling fresh copies on every run unless you need to.

Files that travel through the controller slow everyone down.

When a pipeline moves from one agent to another, files must follow. Jenkins offers stash and unstash for short hops within one build, and archiving for keeping files with the build record. Both normally send data through the controller, which is fine for small files and painful for large ones.

Practical rules

• Stash only what the next stage needs, using precise include patterns, not the entire workspace.
• Send big files to a repository, and pass only a version or address between stages.
• Archive reports, not everything. Do not archive dependency folders or intermediate files.
• Publish test results selectively. Extremely large result files slow down the reporting step and the page that shows them.

Every line of output travels to the controller and is stored there.

Commands running on an agent send their output to the controller as they run, and the controller stores it. A build that prints hundreds of thousands of lines creates real load: network traffic, disk writes and slow-loading log pages that few people can read anyway.

Reporting costs

Publishing test results, coverage and analysis reports is useful, but each report costs time to process, especially when files are large or numerous. Publish what people actually read, publish once at the end of a parallel group rather than per branch when possible, and watch the duration of the reporting steps themselves.

Reusable pipeline code has a cost at the start of every build.

A shared library is a reusable module of pipeline code that many Jenkinsfiles can call. It keeps pipelines short and consistent, which is excellent. But loading a library takes time. At the start of each build, Jenkins fetches the library from its source repository and prepares it, and a large library can add several seconds or more to every run. On a busy system with many pipelines, this also burdens the controller and the source server.

Pipeline start-up in general

Before the first stage begins, Jenkins parses the pipeline definition, loads libraries, fetches the Jenkinsfile and prepares the run. For very large Jenkinsfiles with many stages and thousands of lines, this can take noticeable time. Keep the Jenkinsfile lean by moving repeated logic into libraries or scripts, and split enormous pipelines into smaller ones that call each other.

Three quiet ways to waste capacity.

Concurrent builds of the same branch

When commits arrive faster than builds finish, several builds of the same branch run or queue at once. Only the newest matters. Options exist to disable concurrent builds, or to abort the previous build when a new one starts, and a milestone step can make older builds stop when a newer one passes a checkpoint. These settings free capacity for useful work and give developers the freshest answer.

flowchart TD
    C1["Commit 1 starts build"] --> R1["Running"]
    C2["Commit 2 arrives"] --> Q{"Rule for older build?"}
    Q -->|"Let it run"| W["Both run: old result is stale"]
    Q -->|"Abort previous"| A["Old build stops; new build runs"]
    A --> F["Fresh result sooner, capacity saved"]

Waiting on agents

A build waiting for an outside event, such as an approval or an external system, should not hold an executor. Place long waits outside any agent block, so the slot returns to the pool. Files needed afterwards should be stashed or stored elsewhere.

Polling efficiently

Steps that poll, checking again and again until something is ready, should back off. The waitUntil step increases the pause between checks, which reduces load. Wrap polling in a timeout, avoid very short fixed sleeps in loops and print only occasional progress lines.

Keeping the gains you worked for.

Performance work fades unless someone watches it. A pipeline that took eight minutes after tuning drifts back to twenty over a year as tests are added and caches go stale. Track the numbers, and raise an alarm when they drift.

Regression alerts

Set an alert when a stage’s typical duration rises more than, say, twenty percent above its recent average, or when the 95th percentile crosses a chosen line. Catching a slowdown within a day means it can be traced to a single recent change. Catching it after six months means an archaeological dig.

A performance budget

Many teams agree a budget for each stage: ten minutes for pull requests, thirty for the main branch. When a change would break the budget, the team pays for it by speeding something else up, moving the check elsewhere or explicitly raising the budget with a reason. The budget turns performance from wishful thinking into a shared rule.

Proven ways of arranging fast pipelines.

Habits that look fine at first and hurt later.

A checklist to apply to any Jenkinsfile today.

Mistakes people make when they are new

Blaming the code when the queue is the problem. Check whether builds wait before they run.

Judging by one run. Builds vary. Use at least twenty runs and look at the middle and the slow tail.

Forgetting that shallow means less history. Steps that read history may fail after the change.

Trusting stale caches. Key caches by exact dependency versions and run a clean build on a schedule.

Over-parallelizing. More branches do not always mean faster, especially with repeated setup and a busy fleet.

Ignoring the controller. A slow controller slows every pipeline, no matter how well each one is written.

An honest look at tuning, its rewards and its costs.

Trade-offs to weigh

There is no universally right answer. The right settings depend on how often builds run, how expensive your machines are, how much risk you accept and how much your developers value quick answers. Choose on purpose, measure the result and write down why.

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

Follow one imaginary team through a tuning project.

A team’s pull request pipeline takes about forty-five minutes. Developers complain, and the queue grows at busy hours. Instead of guessing, they start by measuring.

The team never rewrote a test or bought a faster machine. They measured, found the boring causes, fixed them one at a time and kept watching. The result was four times faster feedback and lower cloud costs.

Symptoms, likely causes and calm fixes.

A calm debugging routine

1. Separate queue time from run time for the last twenty or more builds.
2. Read the timestamps of a typical slow run and mark the biggest gaps.
3. Check the critical path, and ignore anything not on it.
4. Check the agent’s graphs to see whether the step is limited by processor, memory, disk or network.
5. Change one thing at a time, measure again and record the result.

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.

Pipeline performance tuning is the disciplined removal of waste. Start by measuring: timestamps, many runs, and queue time separated from run time. Find the critical path and attack its biggest piece. The usual culprits are ordinary ones: queue waits, full clones, repeated downloads, tests run in a poor order or one after another, oversized file transfers, chatty logs and heavy scripting on the controller. Fix them one at a time, verify each change, and keep watching with budgets and drift alerts so the gains last.