GitHub Actions cron not running? Start workflows on time from outside

Setup

Step by step

1. Prepare the workflow for starting from outside

   In the workflow file, add the trigger workflow_dispatch under on:. You can remove the existing schedule or keep it as a fallback. Important: the file has to be on the default branch, otherwise the workflow cannot be started from outside.

   # .github/workflows/nightly.yml
   name: Nightly
   on:
     workflow_dispatch:
     # schedule:
     #   - cron: '0 3 * * *'
   jobs:
     work:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v7
         - run: ./scripts/nightly.sh

2. Create a token with the “Actions” permission

   On GitHub, go to Settings → Developer settings → Personal access tokens and create a fine-grained token. Select only this one repository and, under repository permissions, Actions: Read and write. That is all the start needs. Under Expiration you set when the token expires. Note the date, because after that GitHub answers with an error and the workflow no longer starts.

3. Create an account at Cronjob.de

   Registration takes a minute and is free. Five cronjobs stay free forever; the first 14 days run on the Unlimited plan, including the call log with GitHub’s response.

   Start for free 14 days of Unlimited included, no payment details

4. Create the cronjob with the API address

   As the address, enter the endpoint with your name, your repository and the file name of the workflow. Right in front of the address, set the request method to POST. Below it, content type (here application/json) and request body appear; the branch goes into the body. Under headers, add the token and the format header.

   Address:         https://api.github.com/repos/YOUR-NAME/YOUR-REPO/actions/workflows/nightly.yml/dispatches
   Request method:  POST
   Content type:    application/json
   Request body:    {"ref":"main"}
   Headers:         Authorization: Bearer github_pat_…
                    Accept: application/vnd.github+json

5. Pick the schedule

   Choose how often the workflow should run, for example daily at 3:00. Our schedules use German time (Europe/Berlin). GitHub uses UTC unless timezone is set. If you know crontab syntax, type it directly or let the AI assistant build the schedule from a single sentence.

   0 3 * * *

   You can enter this expression at Cronjob.de exactly as it is – the schedule field understands crontab notation. But you do not have to know it: simply click the schedule together instead.

6. Switch on notifications

   Enter an email address under Notifications. If GitHub does not answer with success, for example because the token has expired, you hear about it on the first failure. Failure notifications by email are included from the Plus plan, and free during the first 14 days.

7. Optional: monitor the run itself

   The start alone does not tell you whether the workflow runs through. Create a heartbeat for that and let the workflow report at the end: the address on success, the same address with /fail on failure. If the check-in is missing or reports a failure, we alert you. This also works if you stay with the GitHub schedule: set a generous grace period, such as one hour, so that delays do not raise an alarm, but a dropped or disabled schedule does.

         - name: Report success
           if: success()
           run: curl -fsS -m 10 --retry 3 https://runcheck.de/a8k3m2x9q1
         - name: Report failure
           if: failure()
           run: curl -fsS -m 10 --retry 3 https://runcheck.de/a8k3m2x9q1/fail

What the five fields of an expression like */5 * * * * mean is explained in the crontab reference – with examples and the most common pitfalls. You can build the expression in the crontab generator. Whether you need an outside service at all is shown in the comparison of the three ways.

Verification

Is it actually running?

Run the cronjob once by hand. The Cronjob.de call log then shows status 204 (empty response, API version 2022-11-28) or 200 with the run ID (API version 2026-03-10). Both mean: accepted. On GitHub, a new run with the trigger workflow_dispatch appears under Actions. If nothing shows up, the workflow file is usually not on the default branch or the file name in the address is wrong.

FAQ

Common questions about GitHub Actions

Why does my scheduled workflow not start on time?

According to GitHub, the schedule event is delayed under high load, especially at the start of every hour, and queued runs can be dropped entirely. There is no promise about the time. If you need to start on time, have the workflow started from outside via workflow_dispatch.

My schedule does not run at all any more.

Two common causes: in a public repository GitHub disables scheduled workflows after 60 days without activity. And scheduled workflows only run on the default branch. If the file only exists on another branch, nothing happens. A heartbeat at the end of the workflow catches both, because the check-in stops arriving.

Which response from GitHub is correct?

According to the GitHub docs, API version 2022-11-28 returns 204 with an empty response, or 200 with "return_run_details":true in the body. API version 2026-03-10 always answers 200 with the run ID. You choose the version with the X-GitHub-Api-Version header. We count both as success.

The call ends with 401 or 403.

401 means: the token is missing, mistyped or expired. 403 usually means: the token lacks the permission Actions: Read and write for this repository. Create a new token and replace the Authorization header in the cronjob.

The call ends with 404 or 422.

404: owner, repository or file name in the address are wrong, the token may not see this repository, or the method is not set to POST. For private repositories without valid authentication GitHub deliberately answers 404 instead of 403. 422: the request is invalid, usually ref is missing from the body, the branch does not exist or the workflow has no workflow_dispatch trigger.

Can I pass values to the workflow?

Yes, through inputs in the request body, for example {"ref":"main","inputs":{"environment":"production"}}. The inputs have to be defined in the workflow under workflow_dispatch:; GitHub allows up to 25.

How often can I start a workflow this way?

With us up to every minute (from Plus; in five-minute steps on the free plan); GitHub’s own schedule allows at most every five minutes. In private repositories every run counts against the Actions minutes of your GitHub account. In public repositories standard runners are free according to GitHub.

How safe is the token with you?

It is only stored in the settings of your cronjob. Still, restrict it as far as possible: a fine-grained token, only this one repository, only the Actions permission. With that, nothing can be done except starting this workflow. When you no longer need it, revoke it on GitHub.