Events, Triggers, Filters, Schedules, Manual Runs, and Repository Dispatch: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first trigger diagnostic sequence

1. Preserve: event/commit/PR/API request evidence and any existing run ID/attempt.
2. Confirm event: did the repository activity or API request actually happen?
3. Confirm workflow eligibility: did the workflow exist at the required ref/default branch?
4. Evaluate filters: activity types, branches/tags, paths, commit-message skip rules.
5. Confirm ref/SHA: especially for PR merge context versus head context.
6. Only if a run exists: inspect job conditions, queue, runner, steps, permissions, external systems.
7. Repair minimally: change one causal input, repeat the smallest equivalent event, compare evidence.

2. Failure class A — expected a run, but no run exists

Start with a prediction table, not a YAML rewrite:

3. Intentionally broken example — assuming branch OR path

on:
  push:
    branches:
      - main
    paths:
      - 'app/**'

A learner pushes docs/notes.md to main and expects the branch match alone to create a run. It does not. When both filters are defined, both must be satisfied. Preserve the commit SHA and absence of a workflow run. Do not “fix” it by changing runs-on, permissions, or shell because no job was ever queued.

Two valid repairs answer different policy questions:

• remove the path filter if every main push should create a run;
• keep the filter if docs-only changes genuinely make the workflow irrelevant.

4. Failure class B — run exists, but the revision is not the one you assumed

The classic example is pull_request. A workflow compares GITHUB_SHA with the contributor's last commit and declares “wrong checkout.” But the event intentionally exposes the PR merge commit as GITHUB_SHA. Diagnose by recording both:

env:
  EVENT_SHA: ${{ github.sha }}
  PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
  REF: ${{ github.ref }}
  BASE_REF: ${{ github.base_ref }}
  HEAD_REF: ${{ github.head_ref }}
steps:
  - run: |
      printf 'event_sha=%s pr_head_sha=%s\n' "$EVENT_SHA" "$PR_HEAD_SHA"
      printf 'ref=%s base=%s head=%s\n' "$REF" "$BASE_REF" "$HEAD_REF"

Repair the expectation first. Only change checkout behavior if the workflow's actual requirement is to test the head commit rather than the merge result.

5. Failure class C — cron did not start at the expected second

Do not interpret schedule delay as a syntax or runner failure until you inspect current schedule rules. Scheduled workflows run from the default branch, have a minimum five-minute interval, and can be delayed during high Actions load. Current docs specifically note that the start of an hour is a high-load period and suggest choosing a different minute when possible.

6. Failure class D — “fixing” permissions by choosing a more privileged trigger

A fork PR cannot access the same secrets/write capabilities as trusted branch automation, and that is intentional. Switching from pull_request to pull_request_target and then checking out/executing untrusted PR code is not a routine permissions fix. It moves execution into a trusted base context and can create a severe privilege boundary violation.

In Chapter 03, the safe repair is to keep the untrusted validation job read-only. If privileged follow-up is required, separate it behind an explicit trusted control plane and defer the full design to Chapter 22.

7. Failure class E — expecting every GITHUB_TOKEN mutation to trigger another workflow

GitHub deliberately suppresses most workflow-triggering recursion for events caused by the repository's GITHUB_TOKEN. Current behavior makes exceptions for workflow_dispatch and repository_dispatch, and has special approval behavior for certain PR events. If a workflow writes to the repository or an issue and you expected another workflow to cascade automatically, inspect token/event recursion rules before adding retries.

8. Broken trigger mini-lab

Create this disposable workflow on main:

name: Broken trigger lab
on:
  push:
    branches: [main]
    paths: ['app/**']
permissions: {}
jobs:
  prove:
    runs-on: ubuntu-24.04
    steps:
      - run: echo "created for $GITHUB_REF at $GITHUB_SHA"

1. Commit a docs-only change on main. Predict no run; record commit SHA and absence.
2. Before editing YAML, explain AND semantics from the current workflow.
3. Commit an app/** change. Predict a run; record run ID/attempt/ref/SHA.
4. If your policy wanted docs-only visibility, repair by removing the path filter or moving selective logic to job conditions. Preserve the original evidence.

9. Diagnostic anti-patterns

• Editing runs-on when no run exists.
• Adding write-all permissions to “make triggers work.”
• Dumping the entire event context to logs instead of selecting necessary fields.
• Replacing pull_request with a privileged trigger to regain secrets.
• Assuming a schedule must fire exactly at the cron second and repeatedly editing cron without preserving actual timestamps.
• Deleting failed or surprising runs before recording run IDs, attempts, refs, and payload evidence.

Knowledge check

Official references and version notes

• Events that trigger workflows — authoritative event-specific ref/SHA, default-branch, activity-type, schedule, and dispatch semantics.
• Triggering a workflow — branch/path filters, manual inputs, event configuration, and trigger examples.
• Workflow syntax for GitHub Actions — current on syntax, filter combination rules, schedule syntax, and manual input types.
• Contexts reference — current github context fields and safe access patterns.
• Variables reference — current meanings of GITHUB_REF, GITHUB_SHA, event path, and run identity variables.
• Troubleshooting workflows — current guidance for trigger conditions, default-branch requirements, merge-conflict behavior, and schedule delays.
• GITHUB_TOKEN concepts — current recursion suppression and exceptions for dispatch events.
• Secure use reference — privileged trigger and untrusted-input security guidance.