GitHub Actions Workflow Not Triggering — Every Cause and Fix (2026)

You pushed code. Nothing happened. The workflow exists but GitHub Actions shows no runs. Here's every reason a workflow doesn't trigger and how to fix it.

Quick Diagnosis

First, check the Actions tab in your repo:

• If you see the run but it's failing → skip to that error
• If the Actions tab shows nothing at all → the trigger never fired
• If the workflow doesn't appear in the list → YAML parsing error

Cause 1: Wrong Branch in the Trigger

Symptom: Push to main but workflow only runs on master (or vice versa).

# Your workflow
on:
  push:
    branches:
      - master    # ← but your default branch is "main"

Fix:

on:
  push:
    branches:
      - main      # match your actual branch name
      - master    # or include both

Check your default branch: Repo → Settings → Branches → Default branch.

Cause 2: Workflow File Not in the Right Path

GitHub Actions only reads workflow files from .github/workflows/.

✅ .github/workflows/ci.yml
❌ .github/workflow/ci.yml      (missing 's')
❌ github/workflows/ci.yml      (missing '.')
❌ .github/workflows/ci.yaml    # this works too, just be consistent

Fix: Verify exact path:

ls -la .github/workflows/

Cause 3: YAML Syntax Error

A syntax error silently breaks the workflow — GitHub won't run it and won't always alert you clearly.

Common mistakes:

# Wrong indentation
on:
push:          # ← should be indented under 'on'
  branches:
    - main
 
# Wrong
on: push       # string, not mapping
 
# Right
on:
  push:
    branches:
      - main

Fix — validate YAML locally:

# Install actionlint
brew install actionlint
# or
go install github.com/rhysd/actionlint/cmd/actionlint@latest
 
actionlint .github/workflows/ci.yml

Or paste your YAML at yamllint.com.

Cause 4: paths Filter Excluding Your Files

on:
  push:
    branches:
      - main
    paths:
      - 'src/**'      # workflow only runs if src/ files change

If you pushed changes outside src/ (e.g., README, .github/workflows/), the workflow won't trigger.

Fix — add paths to include or remove the filter:

on:
  push:
    branches:
      - main
    paths:
      - 'src/**'
      - '.github/workflows/**'    # also trigger on workflow changes

Or remove paths entirely if you don't need file filtering.

Cause 5: GitHub Actions Disabled for the Repo

Check: Repo → Settings → Actions → General → Actions permissions.

Common scenario: new repo, Actions is set to "Disable Actions".

Fix: Set to "Allow all actions and reusable workflows" (or your preferred policy).

Cause 6: workflow_dispatch Trigger Needs Manual Start

on:
  workflow_dispatch:    # only triggers via manual button or API

workflow_dispatch never fires automatically. You have to click Run workflow in the Actions tab, or call the API.

Fix — add automatic trigger too:

on:
  push:
    branches:
      - main
  workflow_dispatch:    # keep for manual runs too

Cause 7: pull_request Trigger From a Fork

Workflows don't auto-run for PRs from forks by default (security protection).

Check: Actions tab → look for "Waiting for approval" status.

Fix: A maintainer must click "Approve and run" for first-time contributors. For trusted contributors, you can auto-approve:

Repo → Settings → Actions → General → "Fork pull request workflows" → "Require approval for first-time contributors only".

Cause 8: Job if Condition Evaluating False

jobs:
  deploy:
    if: github.ref == 'refs/heads/production'   # only runs on 'production' branch

If you pushed to main, the if condition is false → job is skipped → no run appears.

Debug:

jobs:
  debug:
    runs-on: ubuntu-latest
    steps:
    - run: echo "Branch is ${{ github.ref }}"

Check what github.ref actually contains.

Cause 9: Scheduled Trigger (cron) Not Running

on:
  schedule:
    - cron: '0 9 * * 1'    # Monday 9am UTC

Known GitHub issues with scheduled workflows:

1. GitHub throttles or disables scheduled workflows on inactive repos (no pushes in 60 days)
2. Busy periods — GitHub may delay scheduled runs by up to 30 minutes
3. Timezone: cron is always UTC, not your local timezone

Fix:

# Re-activate the repo with a small commit
git commit --allow-empty -m "keep workflows active" && git push
 
# Add workflow_dispatch as fallback
on:
  schedule:
    - cron: '0 9 * * 1'
  workflow_dispatch:    # manual trigger to test the schedule logic

Cause 10: Branch Protection Rules Blocking

Branch protection with "Require status checks" can prevent workflows from even starting in some configurations.

Check: Repo → Settings → Branches → Branch protection rules → examine required status checks.

Cause 11: concurrency Group Cancelling Runs

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true    # cancels previous run when new push happens

If you push rapidly, earlier runs get cancelled. The latest run should still execute — but check the Actions tab for "Cancelled" status.

Cause 12: Organization-Level Policy Blocking

In GitHub Organizations, admins can restrict which workflows can run.

Check: Organization → Settings → Actions → Policies.

If you're in a company org, your workflow might be blocked by org policy. Contact your GitHub org admin.

Full Debug Workflow

# 1. Check workflow file path
ls -la .github/workflows/
 
# 2. Validate YAML syntax
actionlint .github/workflows/*.yml
 
# 3. Add a minimal test workflow
cat > .github/workflows/test-trigger.yml << 'EOF'
name: Test Trigger
on:
  push:
    branches: ['**']   # all branches
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Workflow triggered on ${{ github.ref }}"
EOF
 
git add .github/workflows/test-trigger.yml
git commit -m "test: check workflow trigger"
git push
 
# 4. Check Actions tab immediately after push

Quick Reference

Resources

• Udemy: GitHub Actions Masterclass — Complete course on workflows, triggers, and advanced patterns
• KodeKloud CI/CD Path — Hands-on GitHub Actions labs