A reliable cron schedule is more than a line of punctuation. This guide explains how to read and write five-field and six-field expressions, compare Linux crontab with Kubernetes CronJob and GitHub Actions syntax, and troubleshoot missed, duplicate, or incorrectly timed runs.
Overview
Cron expressions describe recurring times using compact fields. The basic five-field format is:
minute hour day-of-month month day-of-week
| Field | Typical values | Meaning |
|---|---|---|
| Minute | 0–59 | Minute within the hour |
| Hour | 0–23 | Hour of the day in the scheduler's time zone |
| Day of month | 1–31 | Calendar day |
| Month | 1–12 or names | Month of the year |
| Day of week | 0–7 or names | Weekday; 0 and 7 often represent Sunday |
Common operators include * for every permitted value, a comma for a list, a hyphen for a range, and a slash for an interval. For example, */15 means every 15 units in that field, while 1-5 means values one through five.
Useful cron schedule examples include:
0 2 * * *— every day at 02:00.30 9 * * 1-5— weekdays at 09:30.0 */6 * * *— every six hours, at minute zero.0 0 1 * *— on the first day of each month at midnight.15 8 * * 1,3,5— Monday, Wednesday, and Friday at 08:15.
These examples assume a conventional five-field implementation. A six-field format usually adds seconds at the beginning: second minute hour day-of-month month day-of-week. Do not insert a seconds field unless the specific tool documents that format.
Checklist by scenario
Linux crontab
- Confirm whether the schedule is installed for the intended user with
crontab -l, or in a system crontab that includes a user field. - Write the schedule in five fields unless the local daemon supports another format.
- Use an absolute path for the executable and redirect output to a known log during testing.
- Set required environment variables explicitly. Cron usually provides a smaller environment than an interactive shell.
- Check the host time zone and the daemon's behavior around daylight-saving transitions.
A safer entry looks like 0 2 * * * /usr/local/bin/backup --config /etc/backup/config.yml >> /var/log/backup.log 2>&1. Test the command manually as the same user before relying on the schedule.
Kubernetes CronJob
- Put the five-field schedule in
spec.schedule, for example0 2 * * *. - Choose the time zone deliberately. Kubernetes versions that support
spec.timeZonecan express the intended zone in the resource; otherwise, verify the controller's documented interpretation rather than assuming local time. - Set
concurrencyPolicyaccording to the workload:Allowpermits overlap,Forbidskips a new run while the prior job is active, andReplacereplaces the running job. - Review
startingDeadlineSecondswhen a delayed or missed start should be handled within a defined window. - Set job history limits, retries, resource requests, and a timeout appropriate to the task. A schedule only creates jobs; it does not guarantee that the workload completes successfully.
Use kubectl get cronjob, kubectl describe cronjob, and the related Job and Pod events to distinguish a parsing problem from a scheduling, image, permission, or application failure.
GitHub Actions
- Place the expression under
on.scheduleand use the documented five-field POSIX-style syntax. - Design the workflow around the platform's documented scheduling time zone rather than the time zone of the person who authored it.
- Remember that a scheduled workflow is associated with the repository's default branch and can be delayed during periods of platform load.
- Use a separate concurrency policy when overlapping workflow runs would be unsafe. A cron expression alone does not serialize runs.
- Make the workflow idempotent and record the intended schedule in a comment or operational documentation.
For example:
on:
schedule:
- cron: '30 9 * * 1-5'
Cloud schedulers and other automation tools
Cloud scheduler products do not all use the same grammar. Before migrating an expression, check whether the service expects five fields, six fields with seconds, a special wrapper such as rate(), or a separate time-zone setting. Also verify retry behavior, delivery semantics, overlap controls, and whether the scheduler invokes a job directly or sends an event to another service.
What to double-check
Time zones and daylight saving
“02:00” is incomplete without a time zone. Write the intended zone in the runbook, configuration, or resource definition. For jobs tied to business hours, a named zone is usually clearer than an assumed machine-local setting. For infrastructure maintenance, UTC may simplify coordination, but the correct choice depends on the operation.
Daylight-saving changes can create a missing local time or a repeated local time. Decide whether the job should run according to elapsed time, UTC, or local calendar time. Test the scheduler's documented behavior instead of inferring it from a different cron implementation.
Missed runs and overlaps
A scheduler may be paused, unavailable, overloaded, or unable to create a workload because of permissions or quotas. Check both the scheduler's execution history and the target system's logs. Then decide what should happen after a missed run: skip it, run it once on recovery, or replay it only when a business date is still valid.
Measure the normal runtime of the task. If it can exceed the interval, overlapping executions may corrupt output, duplicate notifications, or compete for resources. Use a concurrency control, distributed lock, unique run key, or idempotent design where appropriate.
Command environment and observability
Scheduled commands often fail because the working directory, executable path, credentials, network access, or environment variables differ from an interactive session. Use absolute paths, define configuration explicitly, and send standard output and errors to a retained destination. Emit a start time, schedule identity, run identifier, completion status, and duration so an incident responder can verify what happened.
Common mistakes
- Reading fields from left to right incorrectly: The first field in a conventional five-field expression is minutes, not seconds or hours.
- Assuming every system uses the same grammar: A valid Linux expression may need adjustment for a six-field scheduler or a platform-specific format.
- Confusing “every” with “at”:
0 2 * * *runs at 02:00; it does not run every two hours.0 */2 * * *expresses every two hours. - Ignoring day-of-month and day-of-week interactions: Traditional cron implementations can treat both restricted fields differently from tools that require both conditions. Confirm the target implementation before using a combined calendar rule.
- Using local time without documenting it: This creates surprises during travel, host migration, daylight-saving changes, and incident review.
- Testing only the expression: A schedule can parse correctly while the command fails due to a missing binary, permission, secret, image, or network route.
- Allowing duplicate work: Retries and overlapping runs need a deliberate design, especially for billing, cleanup, backups, and notifications.
When in doubt, test the expression with a cron expression generator or schedule calculator, then validate it in the actual target environment. Treat an online developer utility as a way to inspect expected fire times, not as a substitute for platform documentation and an end-to-end dry run.
When to revisit
Review a cron schedule before seasonal planning cycles, daylight-saving changes, a host or cluster migration, and any change to the job's runtime, dependencies, credentials, or destination. Recheck it when moving from Linux to Kubernetes, GitHub Actions, or a cloud scheduler because field rules, time-zone handling, retries, and concurrency behavior may differ.
Keep a short schedule record with the expression, intended time zone, owner, expected duration, overlap policy, retry policy, and verification method. During review, run this checklist:
- Translate the expression into plain language and confirm the next several expected run times.
- Verify the target platform's field count, special operators, and time-zone support.
- Confirm the command or workflow works with its production identity and environment.
- Check logs, alerts, retries, missed-run handling, and concurrency controls.
- Document the result and update the schedule when the workflow or platform changes.
A correct cron expression is only the first part of dependable automation. The durable solution combines an unambiguous schedule with explicit time-zone assumptions, safe execution behavior, visible outcomes, and a review habit.