GitHub Actions Triggers: Every on: Event and Its Traps

By Daniel Zoghalchali·Latchkey

Two rules cause most "my workflow did not run" reports: schedules and manual dispatch only work from the default branch, and path or branch filters are evaluated before anything else.

A workflow that does not run produces no log to read, which makes trigger problems disproportionately annoying to debug. Nearly all of them come down to a small set of scoping rules.

The most surprising: a schedule or workflow_dispatch workflow must exist on the default branch before GitHub will offer or fire it at all. Testing one on a feature branch does not work and gives no feedback.

The events

Filters and how they combine

on:
  push:
    branches: [main, 'release/**']
    paths: ['src/**', '!src/**/*.md']
  pull_request:
    branches: [main]
    paths-ignore: ['docs/**']

The traps worth memorising

• Schedules and dispatch require the default branch. The workflow file must be on it, or the schedule never fires and the Run workflow button never appears.
• pull_request_target runs with secrets in the base context. Checking out the PR head under it executes untrusted code with your secrets. This is the most dangerous misconfiguration in Actions.
• Path filters do not apply to workflow_dispatch. A manual run always executes regardless of what changed.
• Scheduled runs are best-effort and are commonly delayed during peak load. Do not rely on precise timing.
• A scheduled workflow is disabled after 60 days of repository inactivity.
• GITHUB_TOKEN events do not trigger other workflows, which prevents loops and surprises anyone building a chain.

Why did it not run?

# was the run even created?
gh run list --workflow=ci.yml --limit 5

# is the file on the default branch? (required for schedule/dispatch)
git ls-tree origin/main -- .github/workflows/ci.yml

# validate the trigger block parses
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color

Diagnose it: print the context before you change anything

Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.

- name: Dump contexts
  run: |
    echo '--- github ---'   ; echo '${{ toJSON(github) }}'
    echo '--- needs ---'    ; echo '${{ toJSON(needs) }}'
    echo '--- steps ---'    ; echo '${{ toJSON(steps) }}'
    echo '--- matrix ---'   ; echo '${{ toJSON(matrix) }}'
    echo '--- inputs ---'   ; echo '${{ toJSON(inputs) }}'

Check the context is allowed where you used it

Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.

Catch it before it reaches CI

Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.

# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color

# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
    bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
    ./actionlint -color

Frequently asked questions

Related guides

References

• GitHub: events that trigger workflows (verified 2026-08-20)
• GitHub Actions contexts reference (verified 2026-08-20)
• GitHub Actions documentation
• Workflow syntax for GitHub Actions