Let’s build a precise, beginner-friendly definition before diving into mechanics.

The Simple Definition

Poll SCM, short for “Poll Source Control Management,” is a Jenkins trigger that tells Jenkins to periodically check a source code repository to see whether anything has changed since the last check. If Jenkins finds new commits, it automatically starts a build. If nothing has changed, Jenkins simply waits and checks again at the next scheduled interval, without doing any extra work.

The word “SCM” stands for Source Control Management, the general term for systems like Git that track changes to source code over time. “Polling” is a broader computing term describing the act of repeatedly checking something at intervals, rather than waiting to be told when something happens. Put together, “Poll SCM” simply means “repeatedly check the source control system for changes.”

It helps to compare this to how many everyday systems work. A doorbell is a notification: someone presses it, and you find out immediately. Checking your mailbox is polling: you go look, whether or not there’s actually anything there. Neither approach is wrong — a doorbell requires someone else to reliably press it, while checking the mailbox works regardless of whether anyone tells you anything, as long as you remember to check often enough.

Key Vocabulary You Need First

A handful of terms come up constantly when discussing Poll SCM. Knowing them now will make every later chapter easier to follow.

Understanding the problem Poll SCM was designed to solve makes its behavior far easier to reason about.

The Original Problem: Jenkins Doesn’t Know What It Isn’t Told

A Jenkins Controller, sitting inside a company’s own network, generally has no automatic way of knowing the instant a developer pushes new code to a repository somewhere else. Unless something actively tells Jenkins “a change just happened,” Jenkins would otherwise have no idea a build is needed at all. Poll SCM solves this by flipping the responsibility around: instead of waiting to be told, Jenkins goes and checks for itself, on a regular schedule.

Why Network Position Mattered

In many organizations, especially in Jenkins’s earlier years, the Jenkins Controller lived inside a private, firewalled network, while the source code repository lived on an external, publicly hosted service. An external service trying to directly notify an internal Jenkins Controller often simply couldn’t reach it, because the firewall blocked incoming connections from the outside. Polling neatly avoids this problem, since it’s Jenkins reaching outward to check the repository, not the repository trying to reach inward to Jenkins.

These three qualities — outbound, scheduled, independent — explain exactly why Poll SCM was so useful historically, and they still explain the specific situations where it remains a sensible choice today, even in a world where faster alternatives now exist.

A Short History

Poll SCM dates back to Jenkins’s earliest days, when it was still known by its original name, Hudson. At that time, webhook-based notifications from source control hosts were either unavailable or far less standardized than they are now, so polling was, for many teams, essentially the only practical option for automatic triggering. As webhook support matured and became far more widely standardized across hosting platforms, it gradually became the preferred default for teams whose network setup allowed it — but Poll SCM never stopped working, and it remains a fully supported option to this day.

Poll SCM is simpler than it might sound, built from just a few cooperating pieces.

flowchart LR
    A[Polling Schedule] -->|wakes up| B[Jenkins Controller]
    B -->|asks| C[Source Repository]
    C -->|responds with latest revision| B
    B -->|compares to| D[Last Known Revision]
    D -->|different?| E{Changed?}
    E -->|yes| F[Trigger Build]
    E -->|no| G[Wait for Next Cycle]
        

Notice how little state Poll SCM actually needs to keep. It doesn’t need a full history of every change ever made — it only needs to remember the one revision it last saw, compare that against whatever the repository currently reports as its latest revision, and decide whether those two values match. This simplicity is part of why Poll SCM has remained reliable and easy to reason about for so long.

It’s also worth noting that a polling schedule is configured per job, not globally across the entire Jenkins installation. Two different projects on the same Jenkins Controller can run on completely different schedules — one checking every few minutes because it’s under active, heavy development, and another checking just once a day because it rarely changes. This per-job flexibility lets teams tune polling behavior to match each individual project’s real pace of change, rather than forcing one single rhythm onto everything.

Let’s trace exactly what happens during a single polling cycle, from wake-up to decision.

This lightweight check-first, download-later approach is deliberate. If Jenkins downloaded the entire repository on every single polling cycle, even when nothing had changed, it would waste significant time and bandwidth on repositories checked frequently. By only asking a small, quick question — “what’s your latest revision?” — Jenkins keeps the overhead of polling itself very low, reserving the more expensive full checkout for the moments a build is actually needed.

It’s also worth understanding what happens when a polling check itself runs into a problem — say, the repository is briefly unreachable, or authentication fails. Jenkins records this as a failed polling attempt, rather than silently assuming nothing changed. The next scheduled check simply tries again, and because Jenkins is comparing against the last successfully recorded revision rather than the failed attempt, a temporary hiccup in one cycle doesn’t cause any changes to be permanently missed — they’ll still be detected as soon as a later polling check succeeds.

Zooming out, here’s how a full polling cycle looks as a single, repeating journey.

sequenceDiagram
    participant Sched as Jenkins Scheduler
    participant Ctrl as Jenkins Controller
    participant Repo as Source Repository
    Sched->>Ctrl: trigger scheduled poll
    Ctrl->>Repo: request latest revision
    Repo->>Ctrl: return current revision
    Ctrl->>Ctrl: compare to stored revision
    alt Revision changed
        Ctrl->>Ctrl: queue new build
        Ctrl->>Ctrl: update stored revision
    else No change
        Ctrl->>Ctrl: do nothing
    end
    Ctrl->>Sched: wait for next cycle
        

Notice this cycle repeats identically forever, regardless of outcome, for as long as the job remains configured with Poll SCM. Unlike a one-time trigger, polling has no natural end point — it simply keeps checking, quietly, in the background, on its configured rhythm, whether or not a human is watching or a change happens to be waiting.

Poll SCM is just one of several ways Jenkins can learn that a build is needed — seeing them side by side clarifies when each one fits best.

Webhooks flip the polling model around entirely: instead of Jenkins repeatedly asking “did anything change yet?”, the repository itself immediately tells Jenkins the moment something does change. This nearly eliminates the delay inherent in polling, since there’s no need to wait for the next scheduled check — the notification arrives right away. Because of this, most modern Jenkins setups prefer webhooks whenever the network allows the repository to reach the Jenkins Controller directly.

Manual triggers, the third option in the table above, remain useful even in projects that also rely on polling or webhooks. A deployment to a sensitive production environment, for instance, might deliberately require a person to click a button, even though the earlier build and test stages happen automatically. Poll SCM, webhooks, and manual triggers aren’t really competing alternatives so much as different tools suited to different moments in a single project’s overall workflow.

Poll SCM’s simplicity brings real benefits, alongside a real cost in responsiveness.

Neither of these trade-offs makes Poll SCM a bad choice outright — it simply makes it the right choice in some situations and a less optimal choice in others. The deciding factor is almost always about network reachability and how much delay a team is comfortable tolerating between a code change and the resulting build starting.

It’s worth thinking about this delay in concrete terms. A schedule that checks once every five minutes means, on average, a change is noticed roughly two and a half minutes after it’s made, with a worst case of nearly the full five minutes. For most everyday development work, this delay is barely noticeable. For teams practicing very rapid, tightly-coupled Continuous Integration with dozens of commits an hour, though, even a few minutes of added delay can feel meaningfully slower than the near-instant feedback a webhook would provide.

Poll SCM’s outbound-only nature is itself a meaningful security characteristic worth understanding.

Because Poll SCM only requires Jenkins to reach outward toward the repository, it avoids needing to open any inbound network path into the Jenkins Controller for this purpose. This is a genuine security advantage in tightly controlled environments, where accepting unsolicited inbound connections — as webhooks require — might not be acceptable under an organization’s network policy.

It’s also worth thinking about polling from the repository host’s perspective, not just Jenkins’s own. A single organization running many Jenkins jobs, each polling the same busy repository host frequently, can collectively generate a meaningful amount of repeated traffic. Some hosting providers apply rate limits to protect themselves from exactly this kind of pattern, and a Jenkins installation with dozens of aggressively polling jobs can occasionally bump into those limits, causing polling failures that have nothing to do with Jenkins itself.

Jenkins keeps a dedicated record of polling activity, separate from ordinary build logs.

Jenkins provides a dedicated polling log for each configured job, showing exactly what happened during each check — whether it succeeded, what revision it found, and whether that revision triggered a new build. Reviewing this log is usually the very first step when a team suspects a build isn’t starting when it should.

Beyond individual job logs, teams managing many polling-based jobs sometimes track polling activity in aggregate, looking for patterns across the whole Jenkins installation rather than one job at a time. A sudden spike in polling failures across many unrelated jobs, for instance, often points to a shared cause — a repository host outage, a network change, or an expired shared credential — rather than dozens of unrelated coincidences happening at once.

Years of real-world use have surfaced clear patterns worth following and traps worth avoiding.

These habits keep Poll SCM working smoothly, without becoming an unnecessary drag on infrastructure.

Choose a Schedule That Matches Real Needs

A project where developers push code constantly benefits from a tighter polling interval than a rarely touched project. Matching the schedule to actual activity avoids both wasted checks and needlessly slow detection.

Prefer Webhooks When the Network Allows It

If the repository can reach the Jenkins Controller directly, a webhook will almost always outperform polling in speed and efficiency, making it the better default choice for any newly configured job in that situation.

Watch the Polling Log, Not Just the Build History

Build history only shows builds that actually started. The polling log shows every check, including the ones that found nothing, which is often exactly where the real story of “why didn’t my build start” is hiding.

Keep Repository Credentials Current

Expired or revoked credentials are one of the most common, quietly damaging causes of polling failures, since a failing poll doesn’t always produce an obvious, loud error that a team notices right away.

Review Polling Configuration When Projects Change

A schedule set up years ago for a slow-moving project can quietly become outdated once that project’s pace of development picks up, or once its network environment changes enough that a webhook finally becomes possible. Periodically revisiting old polling configuration, rather than treating it as a one-time setup, keeps triggers matched to how a project actually behaves today.

Poll SCM still shows up across a range of real environments, even in an era where webhooks are common.

What ties all of these examples together is a shared recognition that no single trigger mechanism fits every situation equally well. The right choice depends heavily on factors specific to each project — its network position, how often it actually changes, and how tolerant the team is of a small delay — rather than on any universal rule that one approach is always superior to the other.

No. It remains a fully supported, reliable trigger mechanism. It’s simply no longer the fastest or most efficient default choice in situations where webhooks are possible, though it still fits certain network and infrastructure constraints very well.

Jenkins doesn’t need to know every individual change that happened between checks — it only needs to know that the latest revision differs from the one it saw last time. Once a build starts, the full checkout naturally brings in everything that changed since the previous build.

Yes. Many teams do exactly this, using the webhook as the fast, primary trigger and a much less frequent Poll SCM schedule as a backup safety net in case a webhook notification is ever missed.

No. A polling check only asks for the latest revision identifier, a small, lightweight request. The full repository is only downloaded once a build actually starts, keeping most polling cycles quick and inexpensive.

Jenkins simply notices that the latest revision differs from the last one it recorded and triggers a single build covering all the changes made in between, rather than triggering a separate build for each individual change it missed.

Mainly due to network constraints — if the source control system cannot directly reach the Jenkins Controller, perhaps because of a firewall or strict security policy, Poll SCM remains a dependable way to detect changes without needing any inbound connection at all.

Poll SCM is Jenkins’s original way of detecting new code changes: rather than waiting to be told, Jenkins reaches out on a fixed schedule and asks the repository whether anything is new. It remains reliable, simple to configure, and especially valuable when network constraints prevent the faster, webhook-based alternative from working. Understanding both its mechanics and its trade-offs makes it much easier to decide when Poll SCM is genuinely the right tool, and when a webhook would serve a project better instead.

Whichever trigger a project ultimately settles on, the underlying goal never changes: notice a real change and start a build promptly, without wasting resources or missing anything along the way. Poll SCM has reliably served that goal since Jenkins’s earliest days, and understanding exactly how it works leaves you well equipped to configure it thoughtfully, or to recognize confidently when a different trigger would serve a particular project better.