GitHub Actions scheduled workflows fail silently. Here is how to notice
2026-11-16
on: schedule is probably the most widely used hosted cron there is. It is
free, it lives next to the code, and nobody has to look after a server for it.
It also has failure modes that never show up as a failed run. The Actions tab
can only show you runs that happened. It has no row for a run that never
started.
What GitHub documents
The note at the top of the
schedule event reference
says, word for word:
The
scheduleevent can be delayed during periods of high loads of GitHub Actions workflow runs. High load times include the start of every hour. If the load is sufficiently high enough, some queued jobs may be dropped.
and
In a public repository, scheduled workflows are automatically disabled when no repository activity has occurred in 60 days.
The disabling and enabling a workflow page adds that "when a public repository is forked, scheduled workflows are disabled by default".
That gives three ways a scheduled job can stop working without a failed run anywhere:
- Disabled. A public repository that only runs a nightly job, such as a data scraper, a dependency bump or a backup of something else, gets no new commits. After 60 days the schedule stops. No run fails, because no run starts.
- Dropped. Under enough load, a queued scheduled run may never execute.
- Delayed. The run happens, but late. Usually that does no harm. It does harm when something downstream expects the job's output by a set time.
There is a fourth, which is just ordinary failure: the job runs and exits non-zero. GitHub shows that one, but only to people who look at the Actions tab or read the notification email.
None of the first three can be reported from inside the workflow. A step that never runs cannot send an alert. Something outside GitHub has to expect the run and notice when it does not arrive.
The pattern: a heartbeat with a deadline
A heartbeat monitor (sometimes called a dead man's switch) gives you a URL. Your job calls it when it finishes. The monitor knows the schedule and allows a grace period. If no success ping arrives by the scheduled time plus the grace period, it alerts you. A disabled workflow, a dropped run, a run delayed past the grace period and a job that crashes all end the same way: no success ping by the deadline. One rule covers all four.
Two optional signals make it faster and more informative:
/startat the beginning of the job, which lets the monitor record how long the run took./failwhen the job knows it failed, so you get the alert now rather than at the deadline.
Leave out /fail and failures still get caught. You just hear about them when
the grace period runs out, not the moment the job fails.
The workflow
name: nightly-backup
on:
schedule:
- cron: "17 3 * * *" # off the hour: GitHub names the top of the hour as peak load
workflow_dispatch: # lets you run it by hand to test the pings
jobs:
backup:
runs-on: ubuntu-latest
timeout-minutes: 30
env:
PING_URL: ${{ secrets.PING_URL }} # e.g. https://app.okokumo.com/ping/<token>
steps:
- name: Signal start
run: curl -fsS -m 10 --retry 3 "$PING_URL/start" || true
- uses: actions/checkout@v4
- name: The actual job
run: ./scripts/backup.sh
- name: Signal result
if: always()
run: |
if [ "${{ job.status }}" = "success" ]; then
curl -fsS -m 10 --retry 3 "$PING_URL" || true
else
curl -fsS -m 10 --retry 3 "$PING_URL/fail" || true
fi
Why each piece is there:
if: always()makes the last step run even after an earlier step failed or the job was cancelled. The step then checksjob.statusto decide which ping to send. A plain final step would be skipped as soon as the backup failed, so the monitor would only hear about it at the deadline.|| truestops a failed ping from changing the job's result. A DNS blip on the way to the monitor should not turn a good backup into a red X. If the success ping is lost, the worst case is a false alert at the deadline. You never miss a real failure this way.-m 10puts a time limit on each curl call, so a slow monitor cannot hold up your job.timeout-minutesturns a hung job into a cancelled one, and thealways()step still reports it.- The URL is a secret, because anyone who has it can send pings for that check.
What we actually ran
We pushed this workflow, with a stand-in job, to a scratch private repository
and triggered it with workflow_dispatch on GitHub-hosted runners. The ping
URL pointed at a request-echo endpoint, so the logs show which path each run
called. The three outcomes:
| Job outcome | job.status in the final step |
Ping sent |
|---|---|---|
| Exits 0 | success |
/start, then the bare URL |
exit 1 |
failure |
/start, then /fail |
Sleeps past timeout-minutes |
cancelled |
/start, then /fail |
The timeout row is the one worth knowing. GitHub cancelled the step ("The
operation was canceled."), and the always() step still ran and reported
cancelled. We did not reproduce a 60-day disable or a dropped run. Those are
the cases where no step runs at all, so the deadline is the only thing that can
catch them.
Configuring the check
The check needs to know the same schedule as the workflow. Otherwise the deadline is a guess.
- Schedule: use the cron expression from the workflow. GitHub reads it as
UTC unless you set
timezone:, so give the check UTC as well, or the same zone you set in the workflow. - Grace: the job's normal run time, plus room for GitHub's queue delay.
GitHub does not publish a delay figure, so measure your own:
gh run list --workflow nightly-backup.yml --event schedule --json createdAtshows when each run was created. Compare that with the cron time. For a daily job, 30–60 minutes is a reasonable place to start. Tighten it once you have a few weeks of history.
In okokumo that is a cron check:
{
"type": "cron",
"name": "nightly-backup",
"cron_expression": "17 3 * * *",
"cron_timezone": "UTC",
"grace_seconds": 3600
}
The deadline is the scheduled fire time plus grace_seconds. A success ping
moves it on to the next fire time. /start only records when the run began, so
the completion ping can store its duration. A run that starts and never
finishes is caught at the same deadline as one that never started. /fail
marks the check down straight away, and stores up to 10 KB of the request body
to include in the alert. To see the next few fire times of an expression
before you rely on it, use the
cron expression tester.
You don't need okokumo for this
The pattern is not ours, and the workflow above works with other heartbeat services after you change the URLs:
- Healthchecks.io uses the same suffixes:
/startand/failon its ping URL. Its GitHub Actions page uses separateneeds:jobs instead of onealways()step. It also offers aworkflow_runvariant that keeps the pinging in its own workflow. One difference: a Healthchecks.io/startstarts a timer, and the check goes down if no success ping follows within the grace time. - Cronitor's API-key telemetry URL takes a query parameter instead of a path suffix:
?state=run,?state=completeand?state=failon its telemetry URL.
Whichever service you use, do these:
- Put the success ping in a step that runs only after the real work.
- Send
/failfrom analways()step. - Set a schedule and a grace period that match the workflow.
- Test it once with
workflow_dispatch, and once with a job that fails on purpose.
Want the deadline without running anything yourself? Create a free okokumo account. The free plan includes 5 checks.
Try the free tool: Cron expression tester