schedule-watch: know when a scheduled GitHub Actions workflow stops doing its job

schedule-watch watches every workflow with an on: schedule trigger in the repositories you choose. When one needs attention, it opens an issue in that repository. When the problem clears, it closes the issue. There is nothing to add to your workflows.

Install schedule-watch

What it reports

• Failing: a scheduled run finished with failure, timed out, or failed to start.
• Not running on schedule: expected runs did not happen.
• Disabled: the workflow was disabled, including GitHub's automatic disabling of scheduled workflows in inactive public repositories.

How it decides a run is missing

GitHub starts scheduled runs late under load and skips some entirely. To avoid false alarms:

• A run counts as missing when it has not started 240 minutes after its scheduled time. This is the grace period.
• Schedules that run at least as often as the grace period are reported only after 24 hours with no run at all, because GitHub routinely skips individual runs of frequent schedules. This goes by the shortest gap between two of a schedule's times, so 0 9,10 * * * counts as frequent even though it runs twice a day.

Limits

Up to 50 scheduled workflows per repository and 100 scheduled workflows per installation are watched.

Past a limit, workflows already being watched keep their place, so the same ones stay watched from one check to the next. Which of the rest is picked up follows the order GitHub lists them in. To choose for yourself, add the workflows you do not need to ignore in the settings file; that frees room for the others.

A workflow is also left unwatched when:

• it has more than 10 on: schedule entries,
• its file is larger than 256 KB,
• the repository has more than 300 workflow files, or more than 1024 KB of them in total,
• its schedule uses cron syntax GitHub does not document, or a time that exists on no day of the year.

There is no page listing which workflows are watched, so if one is missing from your alerts, check it against the limits above yourself.

Permissions it asks for

• Actions: read — to list workflows, their state, and their scheduled runs.
• Contents: read — to read workflow files and the optional .github/schedule-watch.yml on the default branch.
• Issues: write — to open, comment on, and close its own alert issues.
• Metadata: read — to list the repositories you selected.

Issues must be turned on in each repository you want alerts for. Repositories with Issues turned off are skipped.

Optional settings

Add .github/schedule-watch.yml to a repository's default branch to change how it is watched. It is read again after a push that changes it.

enabled: true
ignore:
  - .github/workflows/nightly.yml
grace_minutes: 120

• enabled: true or false. false stops watching the repository.
• ignore: a list of workflow files to skip. Write each path in full from the repository root, such as .github/workflows/nightly.yml. A path that matches no workflow does nothing. An issue already open on a workflow you ignore stays open — see Stopping alerts.
• grace_minutes: a whole number from 15 to 1440. How many minutes late a run may start before it counts as missing. Setting it below the shortest gap between two of a schedule's times takes that schedule out of the 24-hour rule, so a single skipped run raises an alert. For 0 9,10 * * * above, that gap is 60 minutes, not 23 hours.

The file may contain only enabled, ignore, and grace_minutes. If it has any other key, a value that breaks these rules (such as enabled: no), or invalid YAML, the whole file is ignored, even a correct enabled: false, and the repository is watched with the defaults. Nothing warns you when this happens. If a setting seems to have no effect, check the file against these rules first.

Stopping alerts

• For one workflow: add it to ignore in the settings file.
• For one repository: set enabled: false as above, or remove the repository from the app's repository selection on GitHub.
• For every repository: uninstall the app from the organization's or account's GitHub settings.

Whichever you choose, and however a workflow stops being watched, issues already open stay open and are not updated again. Close them yourself when you are done with them. Nothing is watching them any more, so nothing will.

Alert issues carry the label schedule-watch, so you can filter them or route them to the right people.