DEV Community

delay.run
delay.run

Posted on

GitHub Actions scheduled workflow not running (or running late)? 8 causes and how to fix each

Reliable HTTP cron and delayed-job scheduling with automatic retries and full run logs — delay.run

You add a schedule to a GitHub Actions workflow:

on:
  schedule:
    - cron: "0 9 * * 1-5"
Enter fullscreen mode Exit fullscreen mode

You expect it to run at 9 every weekday. Then either nothing happens, or it runs at 9:37, or it ran fine for two months and then quietly stopped.

GitHub's scheduled workflows use cron syntax, but they're not cron. They're events that GitHub's own scheduler queues on shared infrastructure, with rules that are easy to miss. Here are the causes I see most, roughly in order of how often they bite.

1. The workflow file isn't on the default branch

Scheduled workflows only run from the workflow file on the repository's default branch. If you added the schedule on a feature branch, or your default branch is main but you pushed the change to develop, the schedule doesn't exist as far as GitHub is concerned.

Fix: merge the workflow to the default branch. Check under Settings → General which branch that is; it isn't always the one you think.

2. The time is UTC

The cron expression is evaluated in UTC by default. 0 9 * * 1-5 is 09:00 UTC, which is 10:00 or 11:00 in Central Europe depending on the season and 04:00 or 05:00 in New York.

Fix: convert your intended local time to UTC and write that, and remember it shifts by an hour when DST changes, because UTC doesn't. Put the intended local time in a comment next to the expression so the next person knows what you meant. If the docs for your plan describe a time zone option for schedules, use it instead.

3. It ran, just late

Scheduled runs are queued, and at busy times they can start many minutes late. The top of the hour is the busiest moment of all, because so many people write 0 * * * *. GitHub's documentation warns that scheduled events can be delayed during periods of high load, and that some queued runs may be dropped.

Fix: if a few minutes don't matter, pick an off-peak minute, like 17 9 * * 1-5 instead of 0 9 * * 1-5. If the exact time does matter, a GitHub Actions schedule isn't the right tool; trigger the workflow from something that does fire on time (see the end of this post).

4. The schedule was disabled for inactivity

In public repositories, scheduled workflows are automatically disabled when there has been no repository activity for 60 days. GitHub sends an email to the person who last changed the workflow, which is easy to miss. The workflow then shows a banner in the Actions tab saying it has been disabled.

Fix: re-enable it in the Actions tab (select the workflow, then Enable workflow). To keep it from happening again, you need real repository activity; some people commit a timestamp file from the workflow itself, which works but adds noise to the history.

5. The cron expression is invalid or isn't what you think

GitHub supports standard five-field POSIX cron syntax. It doesn't support seconds, L, W, # or ?. Some invalid expressions are rejected with an error in the Actions tab; others are valid and just mean something different, like 0 9 1 * 1, which runs every Monday and on the 1st, because cron ORs day-of-month and day-of-week.

The minimum interval is every 5 minutes. * * * * * won't run every minute.

Fix: check the expression with a cron explainer, and look at the workflow's page in the Actions tab for a warning.

6. It's a fork, or Actions are disabled

Scheduled workflows don't run in forks by default. Also check Settings → Actions → General: if Actions are disabled for the repository, or limited to certain actions, the workflow can't run. Organisation policies can override repository settings.

7. The workflow was disabled by hand

Somebody may have disabled it in the Actions tab while debugging and never turned it back on. The Actions tab shows disabled workflows with a label.

Fix: gh workflow list --all shows every workflow with its state, and gh workflow enable <name> turns it back on.

8. It ran and failed silently

Sometimes the schedule worked and the job failed, and nobody saw it because failure notifications for scheduled workflows go only to the user who last modified the cron line. If that person has left the team or filtered GitHub email, nobody hears about it.

Fix: check gh run list --workflow <file>.yml --event schedule. Add an explicit failure notification step (if: failure()) that posts to a team channel, rather than relying on email to one person.

If the job needs to run at 09:00 and not at 09:37, the trigger shouldn't depend on a shared queue. delay.run fires an HTTP call on your schedule, retries if it fails, and keeps a log of every run, so you can see exactly when it started.

When the timing actually matters

A GitHub Actions schedule is great for "roughly once a day" chores: dependency checks, stale-issue bots, nightly builds. It's a poor fit for anything with a real deadline: billing runs, reports someone reads at 9 a.m., reminder emails, anything a customer notices when it's late.

For those, keep the workflow and change the trigger. Add workflow_dispatch (or repository_dispatch) to the workflow, and have an external scheduler call the GitHub API at the exact time:

curl -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/report.yml/dispatches \
  -d '{"ref":"main"}'
Enter fullscreen mode Exit fullscreen mode

The token needs permission to run workflows on that repository; a fine-grained token scoped to the one repo with Actions write access is the safest choice. The workflow then starts within seconds, and the scheduler's log tells you when it was triggered, independently of GitHub's queue.

A quick diagnostic list

  1. Is the workflow on the default branch?
  2. Did you convert the time to UTC?
  3. Does gh run list --event schedule show runs, even late ones?
  4. Is there a "disabled" banner in the Actions tab?
  5. Is it a fork, or are Actions restricted in settings?
  6. Who gets the failure emails?

Related reading

Has a GitHub Actions schedule ever silently stopped on you? I'd like to know how long it took before someone noticed.

Top comments (0)