You schedule a GitHub Actions workflow with the schedule trigger and a standard five-field cron expression. It works, but it is not a precise scheduler, and several rules are easy to trip over.
name: Nightly job
on:
schedule:
- cron: "30 2 * * *" # 02:30 UTC every day
workflow_dispatch: # lets you run it manually too
jobs:
run:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: ./scripts/nightly.sh
Syntax
The expression is the usual five fields: minute, hour, day-of-month, month, day-of-week. Day-of-week is 0-6 (Sunday is 0) or SUN-SAT. Operators *, ,, - and / work as in any crontab. Non-standard extras like L, ? or @daily are not supported. If you are new to the operators, this explainer covers them.
on:
schedule:
- cron: "*/15 * * * *" # every 15 minutes
- cron: "0 9 * * 1-5" # weekdays at 09:00 UTC
- cron: "0 0 1 * *" # midnight UTC on the 1st
You can list several entries under one workflow. When you do, github.event.schedule holds the expression that triggered the run, which lets you branch on it:
steps:
- if: github.event.schedule == '0 9 * * 1-5'
run: echo "weekday run"
Quote the expression
Always wrap the cron string in quotes. A bare * at the start of a YAML value is parsed as an alias marker, so this fails with a YAML syntax error:
- cron: */15 * * * * # invalid YAML
- cron: "*/15 * * * *" # correct
Time zone: UTC only
Schedules are evaluated in UTC, whatever time zone your repository, runners or team are in. Work out the UTC time you want and write the expression for that.
To run at 08:00 in Paris you have to write the UTC hour yourself, and it moves by one hour between winter and summer:
schedule:
- cron: "0 7 * * *" # 08:00 CET (winter)
- cron: "0 6 * * *" # 08:00 CEST (summer)
With both entries the workflow runs twice a day, once at the right local time and once an hour off. A cheap fix is to have the job check the local hour at the start and exit early if it is not the one you want:
steps:
- name: Only continue at 08:00 Paris time
id: gate
run: |
if [ "$(TZ=Europe/Paris date +%H)" = "08" ]; then
echo "go=true" >> "$GITHUB_OUTPUT"
fi
- if: steps.gate.outputs.go == 'true'
run: ./scripts/report.sh
If the exact local time is not important, pick a UTC time and live with a one-hour shift twice a year. More on why this matters in cron and time zones.
Limitations that matter
The shortest interval is 5 minutes. * * * * * will not run every minute. Anything more frequent than every 5 minutes is not supported, so use a different mechanism if you need that.
Runs can be late. GitHub queues scheduled workflows, and during periods of high load they start later than the scheduled time. Delays are most common at the top of the hour, when everybody's 0 * * * * fires at once. A cheap mitigation is to avoid round times: use 17 3 * * * instead of 0 3 * * *.
Runs can be dropped. In heavy load, scheduled runs may be skipped altogether, not only delayed. Do not build anything on the assumption that every scheduled run happens. Make the job idempotent and design it so that a missed run is caught up by the next one.
Only the default branch is used. A schedule trigger only runs from the workflow file on the repository's default branch, at its latest commit. Adding a cron line to a feature branch does nothing until it is merged. If you are testing, add workflow_dispatch and start it by hand.
Public repos get disabled after 60 days of inactivity. In a public repository, GitHub automatically disables scheduled workflows when there has been no repository activity for 60 days. You get a warning, and have to re-enable the workflow from the Actions tab. Private repositories are not affected by this rule. A repo that exists only to run a cron job is the classic victim.
Forks do not run schedules by default. Scheduled workflows are disabled in forks until you enable them.
Failure notifications go to one person. If a scheduled workflow fails, the notification goes to the user who last edited the cron line in the workflow file, which might not be anyone who still cares. Consider an explicit alert step, as described in monitoring cron jobs.
Testing without waiting
Add workflow_dispatch so you can run the workflow from the Actions tab or the CLI, and test the job itself immediately:
gh workflow run nightly.yml
gh run list --workflow=nightly.yml --limit 5
Dispatch tests the steps, not the schedule. To check that the cron expression means what you think, paste it into the decoder and look at the next run times, remembering they are UTC.
Preventing overlapping runs
If a run can take longer than the interval, a second one will start in parallel. Use concurrency so GitHub queues or cancels it:
concurrency:
group: nightly-job
cancel-in-progress: false
With cancel-in-progress: false, a new run waits for the current one to finish. GitHub keeps at most one pending run per group, so extra queued runs are replaced by the newest one.
When Actions is the wrong tool
Scheduled workflows are good for periodic jobs that tolerate lateness: nightly builds, dependency checks, stale-issue cleanup, small data refreshes. They are a poor fit for anything that must run at an exact minute, run more often than every 5 minutes, or must never be skipped. For those, run cron or a systemd timer on a machine you control, or a managed scheduler. A comparison of the first two is in cron vs systemd timers.