GitHub Actions Workflow Won't Trigger — The 6 Silent Reasons

A workflow that never starts is almost always a trigger-definition detail: branch filters, path filters, file naming, or events that don't fire from bots. Six checks, in order of frequency.

What you'll see

Root causes

Filename or location wrong

Must be .github/workflows/<name>.yml — .yml/.yaml both fine, but the directory path is exact. A typo'd folder is invisible to GitHub entirely.

on: filters exclude your branch/paths

on: push: branches: [main] means pushes to other branches do nothing. Same for paths: filters — a docs-only commit skips a workflow filtered to 'src/**'.

Bot-authored events don't trigger more events

Commits pushed by GITHUB_TOKEN (actions, Dependabot in some modes) deliberately don't fire push events — preventing recursive runs. Your workflow watching another workflow's output stays silent.

Workflow disabled or failing YAML syntax

Disabled workflows show an enable banner on the Actions tab; a YAML typo shows a red '!'. Both are silent from the commit's perspective.

Fix it

  1. Check the file location and workflow state
    ls .github/workflows/ && gh workflow list --all   # shows state: active/disabled, and any invalid-marker
  2. Read your trigger filters literally
    grep -A8 '^on:' .github/workflows/<wf>.yml   # branches/paths/tags filters exclude more than people expect
  3. For bot pushes: use a PAT or workflow_run/workflow_call chains
    # events from GITHUB_TOKEN don't re-trigger; either use a PAT for the pushing action, or chain via 'on: workflow_run' on the second workflow
  4. Test the YAML parses and triggers match reality
    gh workflow view <wf> && git branch --show-current   # confirm current branch is actually in the filter list

Field note

on: push with no filters fires on all branches — most 'silent' workflows turn out to have a branches: [main] the author forgot. workflow_run triggers on the default branch config only — a classic gotcha for chained pipelines.

Common questions

Why won't my Dependabot/GitHub-action commits trigger the deploy workflow?

Events created with GITHUB_TOKEN intentionally don't trigger new workflow runs (recursion protection). Use a PAT for the bot's push, or trigger the second stage via workflow_run which sees the completed run.

Do I need the workflow on the branch I'm pushing?

For push events: the workflow file ON THAT BRANCH is what runs (not main's copy). If you added the file on a feature branch, that branch triggers its own version — a common surprise.

Related fixes

Ship it right the first time

Our most-documented failures, packaged as ready-to-ship starter kits: Docker, Kubernetes, and Terraform.

Browse the template store →

One-time. Yours to modify. Instant download from the NinjaOps template store.