A reliable cron schedule is more than a five-field expression. This guide explains cron syntax, compares scheduling formats across CI/CD and cloud platforms, and provides a practical checklist for time zones, overlaps, retries, and missed runs.
Overview
Cron schedules are compact instructions for recurring automation, but the same-looking expression can behave differently depending on the platform. A schedule that works in a Linux host may need adjustment in GitHub Actions, GitLab CI, Quartz, or a Kubernetes CronJob. Before deploying a recurring job, confirm both the expression and the scheduler’s operating rules.
In the traditional five-field format, the fields are:
| Field | Allowed values | Meaning |
|---|---|---|
| Minute | 0–59 | Minute within the hour |
| Hour | 0–23 | Hour of the day |
| Day of month | 1–31 | Calendar day |
| Month | 1–12 or names in some implementations | Month of the year |
| Day of week | 0–7 in many implementations | Day of the week; 0 and 7 commonly represent Sunday |
Common operators include * for every permitted value, a comma for a list, a hyphen for a range, and a slash for a step. For example, 15 2 * * * runs at 02:15 every day in the scheduler’s time zone. */10 * * * * runs every ten minutes, while 0 9 * * 1-5 represents 09:00 on weekdays.
Do not treat an expression as a complete schedule definition. The scheduler also determines the time zone, minimum interval, concurrency behavior, retry model, and response to a missed or delayed run.
Checklist by scenario
Standard Unix-style cron
- Confirm whether the daemon uses the host’s local time or an explicit time-zone setting.
- Write five fields in this order: minute, hour, day of month, month, day of week.
- Test lists, ranges, and steps independently before combining them.
- Define where output, errors, and exit status are recorded.
- Make the command safe to run more than once if a previous invocation is still active.
GitHub Actions and GitLab CI schedules
- Use the platform’s documented five-field cron syntax rather than assuming support for Quartz features such as seconds or
?. - Check the configured time zone. A workflow written for a local business hour may be stored or evaluated in UTC, depending on the platform and configuration.
- Confirm the platform’s minimum scheduling interval and whether scheduled jobs can be delayed during service load.
- Protect scheduled deployments with environment approvals, branch controls, and least-privilege credentials.
- Set an explicit concurrency policy where available. Decide whether a new run should cancel, queue behind, or coexist with an earlier run.
For a GitHub Actions workflow, the schedule normally appears under on.schedule:
on:
schedule:
- cron: '15 2 * * *'
For GitLab CI, the cron expression is commonly configured as part of a pipeline schedule rather than only in the repository YAML file. Review the schedule’s branch, variables, owner, permissions, and time-zone settings alongside the expression.
Quartz and application schedulers
- Check whether the implementation expects six or seven fields, usually including seconds and sometimes a year.
- Use Quartz-specific syntax carefully:
?can mean “no specific value” in the day-of-month or day-of-week position. - Specify the intended time zone in the trigger configuration instead of relying on the application host.
- Document misfire behavior, such as firing once after recovery, skipping the missed occurrence, or firing according to a configured policy.
Kubernetes CronJob
- Place the expression in
.spec.scheduleand verify the cluster version and controller behavior before using optional features. - Set a deliberate
concurrencyPolicy:Allow,Forbid, orReplace, according to the job’s safety requirements. - Use
startingDeadlineSecondswhen a late start should be bounded rather than attempted indefinitely. - Configure
successfulJobsHistoryLimitandfailedJobsHistoryLimitso completed Jobs do not accumulate without a reason. - Make the container idempotent and define resource requests, limits, timeouts, and observability.
apiVersion: batch/v1
kind: CronJob
metadata:
name: nightly-report
spec:
schedule: "15 2 * * *"
concurrencyPolicy: Forbid
jobTemplate:
spec:
template:
spec:
restartPolicy: Never
containers:
- name: report
image: example/report:stable
args: ["--mode", "nightly"]
What to double-check
Time zones and daylight saving time
Write the business requirement first: “run at 09:00 Europe/London” is clearer than “run at 09:00.” Convert that requirement to UTC only when the platform requires it, and record the original business time in the job documentation. Around daylight-saving transitions, a local time may occur twice or not occur at all. Decide whether the job should skip, run once, or follow a UTC schedule.
Overlaps, retries, and idempotency
A schedule starts an attempt; it does not guarantee completion before the next attempt. Estimate the maximum runtime, then choose a concurrency policy. Use a durable lock, unique run identifier, or transactional design where duplicate work could cause damage. Retries should have a bounded count and backoff, and they should not turn a temporary failure into an unobserved backlog.
Missed runs and monitoring
Ask what happens if the runner is offline, the controller restarts, or the queue is unavailable. Some systems skip missed occurrences, while others start a late execution or apply a misfire policy. Add an alert for both failed runs and missing runs. A successful scheduler invocation is not proof that the job produced the expected result.
For production automation, record the schedule, time zone, expected duration, owner, dependency assumptions, last successful run, and recovery procedure. Connect failures to your existing incident response process and review the resulting signals with your SLOs where appropriate. See the SLO burn-rate alert checklist for a related approach to operational alert review.
Common mistakes
- Confusing fields:
0 9 * * 1-5means 09:00 on weekdays, not every nine minutes. - Assuming local time: CI/CD runners and managed controllers may use UTC or a configured zone.
- Copying Quartz syntax into five-field cron: Seconds and
?are not portable. - Ignoring day semantics: Different cron implementations can interpret simultaneous day-of-month and day-of-week restrictions differently. Test the target scheduler.
- Running destructive work without a guard: A delayed or duplicated run can delete, publish, or migrate data twice.
- Using a schedule as a health check: Add completion metrics, logs, alerts, and a way to inspect the last successful business result.
- Testing only the expression: Validate permissions, secrets, network access, image versions, resource capacity, and downstream dependencies too.
When to revisit
Return to this cron expression guide before seasonal planning cycles, time-zone changes, major platform upgrades, or migrations between CI/CD and cloud systems. Recheck it whenever a workflow changes ownership, runtime, branch, container image, dependency, or data-impact level.
Before approving a new schedule, complete this short review:
- State the intended business time and time zone.
- Validate the expression with the target scheduler, not only a generic cron expression builder.
- Confirm the minimum interval, missed-run behavior, retry policy, and concurrency setting.
- Run a safe test in a non-production environment and inspect logs, metrics, and notifications.
- Document the owner, rollback or stop procedure, and expected completion signal.
- Schedule a review after the next daylight-saving transition or operational change.
Keeping these details together turns a fragile recurring command into maintainable engineering workflow automation. The expression is the starting point; predictable behavior comes from testing the scheduler and the job as one system.