Events, Triggers, Filters, Schedules, Manual Runs, and Repository Dispatch: Configuration, Design Patterns, and Trade-Offs

1. Trigger configuration is an interface contract

Every on block defines who or what may request automation, what repository state is associated with the request, and which events are silently ignored. That means trigger changes deserve the same review discipline as API changes: identify callers, accepted input shape, trust assumptions, expected side effects, and how a breaking change will be detected.

2. Broad versus narrow triggers

There is no universal “optimize paths” rule. If branch protection requires a check that never appears because the workflow was filtered out, a compute optimization can become a merge-blocking reliability problem.

3. Branch filters and job conditions operate at different layers

# Trigger-level: may prevent run creation entirely
on:
  push:
    branches: [main]
    paths: ['app/**']

# Job-level: run exists, but job can be skipped
jobs:
  app-test:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-24.04
    steps:
      - run: echo 'test app'

Use trigger filters when the workflow itself is irrelevant. Use job conditions when the run is still valuable evidence but only some work should execute. Chapter 04 will go deeper into expression evaluation; this chapter stays focused on the selection boundary.

4. workflow_dispatch versus repository_dispatch

Do not use repository_dispatch merely because it sounds more “API-like.” If the intent is “run this workflow with these declared parameters,” workflow_dispatch provides a clearer typed workflow contract.

5. Schedule versus external orchestration

Native schedules are excellent for repository-local periodic work that can tolerate GitHub Actions scheduling semantics. They are less suitable for hard real-time requirements, complex calendars spanning many systems, or workflows that must coordinate with external business state.

Scheduled workflows currently run from the latest default-branch commit. If your business requirement is “run version 1.4 every night even after main changes,” schedule alone does not express that immutable version policy.

6. Push versus pull request is also a trust decision

push to a protected branch generally represents code that has already crossed repository review/merge policy. A pull_request run may execute code proposed by a contributor, including from a fork. Secrets and token behavior are intentionally restricted in low-trust contexts. The trigger is therefore not just “when”; it contributes to “who controls the code being executed.”

7. Design patterns that survive growth

• Stable event contract: name custom repository_dispatch event types as versioned interfaces when external clients depend on them.
• Visible required CI: prefer a broad PR trigger plus selective jobs when branch protection expects a consistent check.
• Manual safety valve: use typed workflow_dispatch inputs for operator-controlled retries or dry runs instead of editing workflow YAML for one-off behavior.
• Clock tolerance: document that schedule time is approximate and avoid top-of-hour bursts when exact timing is unnecessary.
• Ref intent: state whether PR work should validate merge result, head SHA, or base branch and record that choice.

8. Worked decision table

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.
• Secure use reference — current trust guidance for event-derived input and privileged workflow patterns.
• GITHUB_TOKEN concepts — current recursion behavior and low-trust workflow implications.