A scheduled build is a Jenkins build that starts because the clock says so, not because a person clicked a button or a developer saved new code.

Start with the basics. Jenkins is an automation server, a program that stays switched on and does tasks for you. A job is the saved description of a task, and a build is one single run of that job. Every build begins because of a trigger, an event that says “start now.” Common triggers are a person clicking a button, a code change arriving, or another job finishing.

A scheduled build uses the clock as its trigger. You give the job a schedule, and Jenkins starts a build whenever the time matches. In the Jenkins screens, the option is often named Build periodically. The schedule itself is written in a small text format borrowed from a very old Unix tool called cron, which is why people say “a cron build” or “a Jenkins cron job.” The word cron comes from the Greek word for time.

It is important to see what a scheduled build is not. It does not watch your code. It does not care whether anything has changed. When the time comes, the build starts, even if nothing is new since yesterday. That is exactly what you want for some tasks, such as a nightly backup, and exactly wrong for others, such as “check whether the developers pushed anything.” We will compare the two ideas carefully later in this guide.

What teams commonly schedule

The schedule format in Jenkins is decades older than Jenkins itself. Knowing where it came from explains its odd look.

Long before web pages and cloud servers, computers running Unix needed a way to do chores at fixed times, such as rotating log files or sending nightly mail. The answer was a small background program called cron. It read a table, checked the clock every minute, and ran whatever was due. The table was called a crontab, short for “cron table.” Each line held a time pattern and a command, and the time pattern used five fields separated by spaces.

That five-field pattern was so simple and so flexible that it became a standard. Nearly every scheduling tool since has either copied it or offered it as an option. When Jenkins, then called Hudson, needed a way to start builds at chosen times, it made sense to reuse this well-known pattern. Anyone who had set up a cron table on a server could set up a scheduled build with no new learning.

A few small ideas explain almost everything about scheduled builds. Learn them once and the rest of the guide becomes easy.

Job, build and agent, quickly

A job is the recipe, and each run of it is a build. The main Jenkins server, called the controller, keeps the schedule and starts the request. The build itself runs on an agent, a separate machine or container, in a slot called an executor. When the clock matches your schedule, the controller places a build request in the queue, and from that point the build behaves like any other build.

Somewhere inside the controller is a small clock watcher. Seeing its place in the system explains many surprises.

flowchart LR
    Admin["Job owner"] -->|"saves schedule"| Cfg["Job Configuration"]
    Cfg --> Home["Stored in JENKINS_HOME"]
    Clock["Controller Clock Ticker"] -->|"every minute"| Sched["Schedule Checker"]
    Home --> Sched
    Sched -->|"time matches"| Queue["Build Queue"]
    Queue -->|"free executor"| Agent["Agent"]
    Agent -->|"log and result"| Ctrl["Jenkins Controller"]
    Ctrl --> Notify["Email and Chat"]

Reading the diagram

Begin at the left. The job owner types a schedule into the job’s settings, and Jenkins saves it in the job configuration inside its home folder. On the controller, a clock ticker wakes up once every minute. Each time it wakes, a schedule checker looks through the saved schedules and asks, “Does the current minute match this one?” For every match, the controller places a build request in the build queue. When an agent has a free executor, the build moves there, runs, and reports its log and result back to the controller, which can then send a message to email or chat.

Three facts that follow from this design

• The controller must be running. The clock ticker lives inside the controller. If Jenkins is switched off at the scheduled minute, nothing starts.
• Precision is one minute. The checker wakes once a minute, so you cannot schedule seconds, and a build may begin a little after the minute rather than on the dot.
• The controller’s clock decides. Unless you say otherwise, “2 a.m.” means 2 a.m. on the controller’s own clock and time zone, not yours.

A schedule is one line of text with five pieces. Once you know what each piece means, reading any schedule becomes easy.

A Jenkins schedule has five fields, separated by spaces, always in the same order. Each field answers one small question about time.

The special characters

Reading some real schedules

The table below shows common schedules and how to read them aloud. Practice saying each one in words. It is the best way to make the format feel natural.

Shortcut names

Jenkins also understands a few friendly words that stand for common schedules. These start with the at sign. They are handy for simple cases and they also use the hash idea behind the scenes, so the exact minute or hour is chosen for you.

• @hourly means once every hour.
• @daily and @midnight mean once a day, around midnight.
• @weekly means once a week.
• @monthly means once a month.
• @annually and @yearly mean once a year.

The hash symbol looks like a tiny detail, but it is the difference between a calm Jenkins and one that struggles every midnight.

Picture a large company with two hundred jobs. Nearly every team wants a nightly build, and nearly everyone thinks “midnight” is the natural choice. If all two hundred jobs are set to start at exactly midnight, then at one minute past eleven fifty-nine there is silence, and at midnight two hundred build requests arrive at the same instant. Agents run out of free executors, the queue grows long, the controller strains, and every job slows down. Then, minutes later, the system goes quiet again.

What H really does

When you write H in a field, Jenkins picks a value for that field by using the name of the job as a seed. It does the same calculation every time, so the chosen value is stable: the same job always gets the same minute. But different jobs get different values, so they spread across the available range. That gives you the best of both worlds. Each job runs at a predictable time, but the whole set of jobs is scattered.

flowchart LR
    subgraph Before["Everyone chooses midnight"]
        J1["Job A"] --> M["00:00 crowd"]
        J2["Job B"] --> M
        J3["Job C"] --> M
        J4["Job D"] --> M
    end
    subgraph After["Everyone uses H"]
        K1["Job A at 00:07"]
        K2["Job B at 00:23"]
        K3["Job C at 00:41"]
        K4["Job D at 00:52"]
    end

Reading the diagram

The left side shows four jobs that all name the same moment. They pile up together at midnight and compete for the same executors. The right side shows the same four jobs using H. Each job lands on its own minute within the hour, so the controller and agents see a steady trickle instead of a wave.

Using H with ranges and steps

You can limit the range that H chooses from. Writing H followed by a range in brackets tells Jenkins to pick within that range only. For example, an hour field with H and the range zero to five means “choose an hour between midnight and five in the morning.” A minute field with H and a step of fifteen means “every fifteen minutes, but shifted by a job-specific offset,” so different jobs do not all fire on the quarter hour. This is the healthy replacement for the old habit of writing a star with a slash.

“Two in the morning” is not one moment for the whole planet. Jenkins needs to know whose two in the morning you mean.

By default, Jenkins reads a schedule using the time zone of the controller, the clock of the machine where Jenkins runs. If your controller is set to universal time and your team lives in another region, then “2 a.m.” might arrive in the middle of your workday. Many cloud servers default to universal time, so this surprise is very common.

Three ways to be clear

• Check the preview message. The “would next run at” line shows a real date and time, and a time zone label, so you can compare it with your own clock.
• Set the time zone inside the schedule. Jenkins lets you put a time zone line at the very top of the schedule box, naming a region such as a continent and city. All lines below it are then read in that region’s local time.
• Set the controller’s own time zone. This changes the meaning of every schedule on the server, so it is a bigger decision and should be made deliberately.

Daylight saving time

Some regions move their clocks forward in spring and back in autumn. That creates two awkward nights each year. When clocks jump forward, one hour simply does not exist, so a job scheduled inside that hour may be skipped or run at a different moment than you expect. When clocks fall back, one hour happens twice, so a job scheduled in that hour might run twice. Jobs that must run exactly once per day should avoid the hour that changes, which is often around two or three in the morning in affected regions. Choosing a time such as five in the morning, or working in universal time, sidesteps the problem.

From the moment the clock matches to the moment a record is saved, every scheduled build follows the same road.

flowchart TD
    A["Clock ticks: a minute passes"] --> B["Schedule matches this minute"]
    B --> C["Build request added to queue"]
    C --> D["Executor becomes free"]
    D --> E["Agent prepares workspace"]
    E --> F["Code is checked out"]
    F --> G["Stages and steps run"]
    G --> H["Result decided"]
    H --> I["Reports and notifications"]
    I --> J["Record kept: Started by timer"]

What if the last build is still running?

Sometimes a scheduled build takes longer than the gap between schedules. Suppose a job runs every hour, but one run takes ninety minutes. When the next hour arrives, the previous build is still working. What happens depends on whether the job allows concurrent builds. If concurrency is off, the new request waits in the queue until the earlier build finishes. If it is on, a second build may start alongside the first. Neither is automatically right. A job that writes to one shared place should usually forbid concurrency, or two runs may trample each other. But a job that only reads and reports may run side by side without trouble.

Two Jenkins options both use cron-style text. They sound similar, but they do very different things.

Beginners often mix these two options, so this chapter is worth reading slowly. Both use the same five-field schedule text. The difference is what happens when the time arrives.

Why webhooks usually beat polling

A webhook is a message that your code host sends to Jenkins the instant something changes. It is fast, it wastes nothing, and it scales well. Polling makes Jenkins ask again and again, “Anything new?” With a hundred jobs each polling every minute, that is a hundred questions a minute, mostly answered “no.” Use polling only when the network makes webhooks impossible, and if you must, poll less often and use H to spread the questions out.

Combining the ideas

Many teams use several triggers on one project. A webhook builds each change within seconds for quick feedback. A nightly schedule then runs a longer, deeper set of tests on the latest code. A weekly schedule scans for newly announced weaknesses in libraries. Each trigger has a clear purpose, and none of them fights the others.

You can set a schedule through a web form or inside the pipeline recipe. Both create the same kind of trigger.

In a classic job

In a freestyle job, open the job’s configuration page and find the section for build triggers. Tick the box called Build periodically, and a text box appears. Type the schedule there. Under the box, Jenkins shows the “would last have run” and “would next run” lines. Save the job and the schedule is active.

In a pipeline job

In a pipeline, the schedule can live inside the pipeline recipe itself, in the section that lists triggers. This is the better place for serious projects, because the schedule is then stored beside the code, reviewed by teammates, and versioned in history. If the server is lost and rebuilt, the schedule comes back automatically when the pipeline runs again. One thing to remember is that a trigger defined inside a pipeline file is registered when the pipeline runs. So after adding or changing it, the job may need to run once before the new schedule takes effect.

In multibranch pipelines

Each branch has its own pipeline, and a schedule inside the file applies to each branch that has it. This can surprise teams, because a nightly trigger might then run for every active branch, multiplying the load. Many teams limit scheduled work to the main branch by adding a condition, so feature branches are only built when their code changes.

Passing options to scheduled builds

A scheduled build normally runs with the default values of any parameters, since no person is there to choose. If you need different options at different times, such as a fast test set every hour and a deep test set every night, there is a plugin that lets you attach parameter values to each schedule line. Another approach is to create two jobs that share the same pipeline recipe but have different defaults.

Picking a schedule is a design decision. A few questions make the answer clear.

Common schedule choices and their reasons

A worked example: planning schedules for one small team

Imagine a team of eight people building a web shop. They want quick feedback while they work, a deep check every night, and a few housekeeping chores. Here is how they might plan it, in words. Every code change triggers a quick build through a webhook, so a developer knows within minutes whether a change is safe. Once a night, during a hash-chosen time between one and four in the morning, the full test suite runs against the latest main branch, and the result is waiting in the team chat by nine. Once a week, early on Monday, a scan checks libraries and container images for newly announced weaknesses. Every Sunday, a cleanup job removes old packages and stops unused test servers. Finally, a small monitoring check confirms each morning that the nightly build really happened.

Notice what this plan does well. Each schedule has a purpose. None of them fights another, because they use different windows. Every one of them uses the hash symbol, because none of them needs an exact minute. And the plan includes a watcher for the watchers, so silence is noticed. A team can write a plan like this on a single page and revisit it every quarter.

Thinking about cost

Scheduled builds feel free, because nobody clicks anything, but each run uses real machines. On your own servers, that means electricity and wear, and on rented cloud machines it means a monthly bill. A job that runs every ten minutes on a large machine can quietly cost more than an entire team’s coffee budget. To keep costs sensible, ask three questions for every schedule. How often does it truly need to run? How big a machine does it truly need? And can it stop early when nothing has changed? Teams that ask these questions regularly often cut their scheduled workload by a third without losing any real safety.

A scheduled build runs unattended, often at night, with real permissions. That makes it worth protecting well.

Permissions

Jenkins can limit who may create jobs, edit schedules, and start or stop builds. Follow least privilege, meaning each person gets only the access their work needs. Anyone who can edit a schedule can change when code runs, and anyone who can edit the job can change what runs. Treat those rights carefully.

The worst scheduled build is one that silently stops running. Good monitoring means you learn about problems from Jenkins, not from a customer.

Notifications that people will read

A message every night that says “all good” quickly becomes noise, and people learn to ignore it. A message only when something changes, such as the first failure or the first success after failures, gets attention. Send failures to the owner of the job and to the channel of the team that depends on the result. Keep messages short, with a link straight to the build.

Detecting a missing build

Because Jenkins does not replay missed runs, a controller outage or a broken schedule can pass unnoticed. A simple safeguard is a second, independent check that looks for the latest build time of important jobs and alerts if it is older than expected. Many monitoring systems, such as Prometheus with Grafana, can chart the time since the last successful build and raise an alarm. This is sometimes called a “dead man’s switch,” because it alerts you when the expected signal stops.

Scheduled builds are simple and powerful, and they also carry hidden costs that are worth knowing.

Trade-offs to think about

A pattern is a proven way to solve a common problem. An anti-pattern is a habit that looks helpful and causes pain later.

Patterns worth copying

Habits to avoid

These are lessons experienced teams usually learn the hard way. You can learn them the easy way, by reading them now.

Best practices

• Always use H unless an exact time is required. It costs nothing and protects the server.
• Check the preview lines every time. Read “would next run at” and confirm it matches your intention, including the time zone.
• State the time zone. Put it in the schedule or in the job description so nobody has to guess.
• Keep schedules in version control. Use pipeline files so changes are reviewed and recoverable.
• Add timeouts. A stuck scheduled build should stop itself, not block an executor all night.
• Decide about overlap. Choose deliberately whether concurrent runs are allowed.
• Limit scheduled work to trusted branches. Do not run nightly jobs for every experimental branch.
• Skip pointless runs. If nothing changed and nothing needs re-checking, exit early to save money.
• Set retention rules. Frequent builds create a lot of history, so decide how much to keep.
• Alert on missing builds. Detect silence, not only failure.
• Document ownership. Every scheduled job needs an owner and an alert channel.

Common mistakes

• Assuming the server clock is the team clock. Many servers run on universal time.
• Forgetting daylight saving. Jobs near the clock change may be skipped or doubled.
• Using a star with a slash for the minute field. Every job then fires on the same quarter hours. Use H with a step.
• Believing missed builds are replayed. They are not.
• Confusing Build periodically with Poll SCM. One always builds, the other builds only on changes.
• Scheduling the same heavy work in many branches. The load multiplies with each branch.
• Letting old scheduled builds fill the disk. A build every few minutes creates thousands of records in a month.
• Editing a pipeline schedule and expecting it to apply at once. The pipeline may need to run once to register the new trigger.

Sooner or later a scheduled build does not run when you expect. A calm routine finds the cause quickly.

A simple routine

Common situations and their usual causes

Scheduled builds appear in teams of every size and in nearly every industry. Here is how the ideas look in practice.

Lessons that repeat across teams

Look across these examples and a few lessons appear again and again. Successful teams keep quick, change-driven builds separate from slow, time-driven ones. They spread their schedules instead of stacking them. They watch for silence as carefully as for failure. They write schedules in files that people can review. And they keep the number of scheduled jobs small and useful, retiring the ones that no longer earn their cost. None of this requires a large budget. A small team can follow every one of these habits from the first week.

A scheduled build is Jenkins’ alarm clock. Used well, it turns quiet hours into useful work.