GitHub Actions Workflow Not Triggering - Fix the on: Block

The workflow file is valid but nothing runs because the on: triggers, branch filters, or path filters do not match the event you produced - or the file is not yet on the branch the event targets.

What this error means

You push or open a pull request and no run appears in the Actions tab. There is no error because the event simply did not match any configured trigger.

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
# a change only under docs/ on a feature branch matches nothing here

Common causes

Branch or path filters exclude the change

branches and paths filters are allowlists. A push to a branch not listed, or a change touching only files outside paths, produces no run.

The workflow is not on the relevant branch

For push and pull_request, GitHub uses the workflow file as it exists on the branch receiving the event. A new workflow on a feature branch will not run for events on other branches.

Wrong event type

Using on: push when you expected a pull_request run, or omitting workflow_dispatch when you try to run it manually, means the event never matches.

How to fix it

Match the trigger to the event you produce

List every event and branch you intend to fire on, and add workflow_dispatch if you want a manual run button.

on:
  push:
    branches: [main, 'feature/**']
  pull_request:
  workflow_dispatch:

Check filters and branch placement

1. Confirm the changed files actually match any paths filter (paths-ignore is an inverse blocklist).
2. Ensure the workflow file exists on the branch the event targets.
3. Remember pull_request uses the workflow from the base branch, not the PR head.

How to prevent it

• Keep trigger and filter rules minimal and test them with a small change.
• Use workflow_dispatch during development so you can trigger runs on demand.
• Merge new workflows to the default branch early so scheduled and push events pick them up.

Related guides