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@v4
         - 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. Mind the lifetime: without your own setting the token expires after 30 days. Choose a longer lifetime and note the date.

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.

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. In the Advanced tab, set the request method to POST, the content type to application/json and put the branch into the request body. Under custom 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"}
   Custom 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), not UTC as on GitHub. 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 a response with status 204 (or 200, depending on GitHub’s API version) – 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?

Status 204 No Content with an empty response, or 200 with the details of the started run on the newer API version. 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, or the token may not see this repository. 422: the workflow has no workflow_dispatch trigger, or the branch given in ref does not exist.

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. Keep the Actions minutes of your GitHub account in mind: every run uses them.

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.