GitHub Actions: scheduled workflow not triggering [2026 fix]

CRON syntax errors or branch protection rules block scheduled jobs; fix: validate cron format and ensure default branch runs are permitted.

GitHub Actions: Scheduled Workflow Not Triggering at 2AM

TL;DR

---

Real Console Error Messages

Here are the exact errors you'll see:

``` 1. No scheduled runs appear in Actions tab └─ "This scheduled workflow hasn't run yet"

2. Workflow file validation fails silently: Error: You have an error in your git config file at line 3 Unexpected input 'schedule'

3. In workflow logs (if file is on branch): Error: The workflow is not enabled. Workflows must have at least one job, and 'schedule' alone is invalid without 'on:' prefix

4. Branch protection rejection: ✗ Workflow execution blocked by branch protection rule: "Require status checks to pass before merging"

5. Cron parsing failure (rare but seen in logs): Parse error in workflow: Invalid cron expression '0 2 * *' Expected 5 fields, found 4 ```

---

Broken Code vs. Exact Fix

Problem #1: Invalid CRON Syntax

❌ BROKEN: ```yaml name: Nightly Deploy on: schedule: - cron: '2 * * *' # Missing minute field!

jobs: deploy: runs-on: ubuntu-latest steps: - run: echo "Deploy" ```

✅ FIXED: ```yaml name: Nightly Deploy on: schedule: - cron: '0 2 * * *' # 2:00 AM UTC, every day

jobs: deploy: runs-on: ubuntu-latest steps: - run: echo "Deploy" ```

Format: minute hour day month day-of-week (all 5 fields required).

---

Problem #2: Workflow File Not on Default Branch

❌ BROKEN: ``` Your repo structure: main/ ├─ src/ └─ README.md ← .github/workflows/ missing!

feature-branch/ └─ .github/workflows/deploy.yml ← Won't trigger! ```

✅ FIXED: ``` main/ (default branch) ├─ .github/ │ └─ workflows/ │ └─ deploy.yml ← Commit here first ├─ src/ └─ README.md ```

Action: Push the .github/workflows/deploy.yml file to your default branch (main, master, etc.). Scheduled workflows *only* run from the default branch.

---

Problem #3: Branch Protection Blocking Execution

❌ BROKEN Settings: ``` Repository Settings → Branches → Branch protection rules ☑ Require pull request reviews before merging ☑ Dismiss stale pull request approvals ← This can block it ☑ Require status checks to pass └─ "Strict" mode enabled ← This too ```

✅ FIXED Settings: ``` 1. Go to Settings → Branches → Branch protection rules 2. Click "Edit" on main/master 3. Scroll to "Allow force pushes" 4. Ensure "Restrict who can push to matching branches" is OFF for GitHub Actions user (or whitelist it) 5. Under "Require status checks": └─ Uncheck "Require branches to be up to date" 6. Save ```

Why: Scheduled workflows run *as* the default branch, not *against* a PR, so strict protections can silently block them.

---

Validate Your CRON Expression

Before committing, test at [crontab.guru](https://crontab.guru):

Note on timezones: GitHub Actions runs all scheduled workflows in UTC. If you need 2 AM EST, use 7 * * * (5 hours ahead in winter).

---

Still Broken? Check These Too

1. Workflow is disabled in UI: Navigate to .github/workflows/ in your repo, click the workflow file, and check the "Actions" tab. Look for a three-dot menu → "Enable workflow." Manually disabling a workflow persists even if you push new code.

2. if: condition is too restrictive: If your job has if: github.event_name == 'pull_request', scheduled triggers won't match. Change to if: github.event_name == 'schedule' || github.event_name == 'pull_request' or remove the condition entirely.

3. Workflow syntax error elsewhere: GitHub won't show syntax errors for on: schedule: in the UI by default. Download the [GitHub CLI](/?guide=github-cli-setup) and run gh workflow view <filename> --yaml to validate locally before pushing.

---

Related Guides

---

Official Docs

---

Found a different variation? Drop it in the comments

Scheduled workflows have edge cases (especially around organizational runners, self-hosted agents, and private repos). If you hit a different error, comment below with the exact error message and your workflow structure—we'll add it to this guide.