Platform schedule guide
GitHub Actions Cron Schedule Guide
Write reliable GitHub Actions cron schedules with current POSIX syntax, timezone support, the five-minute minimum, workflow YAML examples, concurrency controls, and scheduling gotchas.
Platform behavior reviewed against the official documentation on August 5, 2026.
- Format
- 5-field POSIX cron
- Smallest interval
- Every 5 minutes
- Default timezone
- UTC
- Execution branch
- Default branch
Overview
GitHub Actions can run a workflow on a recurring schedule through the schedule event. It uses a five-field POSIX cron expression in the workflow file, evaluates the schedule in UTC by default, and now also accepts an IANA timezone for a wall-clock schedule.
Scheduled runs are designed for repository automation such as dependency checks, nightly tests, reports, and maintenance. They are not a real-time scheduler: a run can start later during periods of high load, so time-critical production work should use a scheduler with an explicit delivery contract.
The workflow file must be present on the default branch. A scheduled run uses the latest commit on that branch, which is different from push and pull-request events that are tied to a particular commit.
GitHub Actions cron format
Place one or more entries under on.schedule. Each cron value has minute, hour, day-of-month, month, and day-of-week fields. GitHub accepts numbers, month and weekday names, lists, ranges, and step values.
There is no seconds field. A six-field Quartz or Spring expression will be rejected. GitHub also enforces a five-minute minimum even though the POSIX grammar itself can describe every-minute schedules.
┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12 or JAN-DEC)
│ │ │ │ ┌───────────── day of week (0-6 or SUN-SAT)
│ │ │ │ │
* * * * *| Field | Position | Values | Platform note |
|---|---|---|---|
| Minute | 1 | 0-59 | Use */5 or a larger step; once per minute is not allowed. |
| Hour | 2 | 0-23 | Interpreted in UTC unless schedule.timezone is set. |
| Day of month | 3 | 1-31 | A star means every valid calendar day. |
| Month | 4 | 1-12, JAN-DEC | Names are case-insensitive in normal POSIX usage. |
| Day of week | 5 | 0-6, SUN-SAT | Sunday is 0; names make reviews easier. |
Copyable schedule examples
Every 15 minutes
*/15 * * * *
on:
schedule:
- cron: '*/15 * * * *'Useful for polling, but design the job so overlapping or delayed runs are safe.
Weekdays at 5:30 AM in an explicit timezone
30 5 * * 1-5
on:
schedule:
- cron: '30 5 * * 1-5'
timezone: 'America/New_York'Use an IANA name instead of a fixed UTC offset when the schedule should follow daylight saving time.
Every Monday at 02:17 UTC
17 2 * * 1
Choosing a non-zero minute can reduce contention around the top of the hour.
At 03:00 on the first day of every month
0 3 1 * *
Complete scheduled workflow example
Save the workflow under .github/workflows. Keep workflow_dispatch so maintainers can test the same job manually, and use concurrency when two runs must not overlap.
name: Nightly maintenance
on:
schedule:
- cron: '17 2 * * *'
timezone: 'UTC'
workflow_dispatch:
concurrency:
group: nightly-maintenance
cancel-in-progress: false
jobs:
maintenance:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v7
- name: Run maintenance
run: ./scripts/maintenance.shDeployment checklist
- Commit the YAML file to the repository default branch.
- Run it once with workflow_dispatch and verify permissions, secrets, and runtime assumptions.
- Check the Actions tab after the first scheduled window; do not infer success from the schedule configuration alone.
- Add a timeout, idempotency key, and an external missed-run alert for important automation.
Timezone and daylight-saving behavior
Without a timezone property, GitHub evaluates scheduled workflows in UTC. To keep a job at the same local wall-clock time, set schedule.timezone to an IANA identifier such as Europe/Istanbul or America/New_York.
A named timezone follows its daylight-saving rules. GitHub documents that a time inside a skipped spring-forward hour advances to the next valid local time. If exact behavior around clock changes matters, avoid the transition window and inspect the next runs before deployment.
UTC remains the simplest choice for infrastructure work because it has no daylight-saving jumps. State the timezone in the workflow name or comments so future reviewers do not silently reinterpret the expression.
on:
schedule:
- cron: '0 9 * * 1-5'
timezone: 'Europe/Istanbul'Limits and platform behavior
- Five-minute floor
- The shortest supported interval is once every five minutes. Use a queue, service loop, or platform scheduler for shorter cadences.
- Best-effort start time
- Scheduled events can be delayed during high load. Avoid building correctness around an exact start second or minute.
- Default-branch execution
- The workflow runs from the latest commit on the default branch and the workflow file must exist there.
- Repository activity
- GitHub may disable scheduled workflows in public repositories after long periods without repository activity; monitor the workflow rather than assuming it remains enabled.
Production gotchas
Top-of-hour congestion
Many schedules use minute 0. A minute such as 7, 17, or 43 is easier on shared infrastructure and often starts more predictably.
Duplicate or overlapping work
A slow run can overlap the next scheduled run. Use a concurrency group, application-level lock, and idempotent operations.
Untrusted schedule input
The cron string is workflow configuration, not user input. Keep secrets in Actions secrets and grant the GITHUB_TOKEN only the permissions the job needs.
Silent failure
A green schedule definition does not prove that the job completed. Alert on a missing success signal, not only on a failed workflow run.
Frequently asked questions
What cron format does GitHub Actions use?
GitHub Actions uses a five-field POSIX cron expression: minute, hour, day of month, month, and day of week. It does not accept a seconds field.
Can GitHub Actions cron use a timezone?
Yes. Scheduled workflows default to UTC, and a schedule entry can specify an IANA timezone with the timezone property.
How often can a scheduled GitHub Action run?
The shortest supported interval is once every five minutes. Actual starts can be delayed during periods of high load.
Which branch does a scheduled workflow run from?
Scheduled workflows run the latest commit from the repository default branch, and the workflow file must exist on that branch.