GitHub Actions Workflow Not Triggering: 7 Causes and Fixes

When a workflow does not trigger, GitHub silently does nothing. Here are the seven most common causes.

Cause 1: Branch Name Mismatch

Your workflow targets main but your repo uses master, or vice versa.

on:
  push:
    branches: [main, master]

Cause 2: Path Filter Too Restrictive

on:
  push:
    paths:
      - src/**    # Only triggers if src/ files changed

If you pushed outside src/, no trigger. Remove paths or add more patterns.

Cause 3: YAML Syntax Error

GitHub silently ignores invalid YAML workflows.

brew install actionlint
actionlint .github/workflows/ci.yml

Common error: mixing tabs and spaces (YAML requires spaces only).

Cause 4: Workflow File Not on Default Branch

GitHub only reads workflow files from the default branch. Merge your workflow file to main first.

Cause 5: Actions Disabled

Settings -> Actions -> General -> "Allow all actions and reusable workflows"

Cause 6: Schedule Paused

GitHub pauses cron workflows after 60 days of repo inactivity.

gh workflow enable "My Scheduled Workflow"

Cause 7: workflow_dispatch Not Showing

The "Run workflow" button only appears after the file is on the default branch with no YAML errors.

Debug Commands

# List all workflows
gh workflow list
 
# Check if enabled
gh workflow view "CI"
 
# Manually trigger to test
gh workflow run ci.yml --ref main

More GitHub Actions? Read our CI/CD pipeline tutorial and GitHub Actions vs GitLab CI comparison.