Events, Triggers, Filters, Schedules, Manual Runs, and Repository Dispatch: Core Concepts and Mental Model

1. A workflow trigger is a selection problem, not a timer attached to YAML

A workflow file can be perfectly valid and still produce no run. GitHub first receives or generates an event. That event has an identity, payload, repository, and—depending on the event—a ref and commit SHA. GitHub then evaluates workflow trigger configuration against that event. Only after those conditions match does a run exist. Job conditions, runner queueing, and step execution happen later.

This ordering gives you a powerful debugging rule: if no run exists, do not start by debugging the runner. Ask whether the event occurred, whether the relevant workflow revision was eligible, and whether trigger filters matched.

2. Mental model: event → filters → revision → run

flowchart TD
  A[GitHub event / schedule / API request] --> B[Event name + activity + payload]
  B --> C[on configuration]
  C --> D{branch / tag / path / type filters match?}
  D -- no --> E[No workflow run created]
  D -- yes --> F[Resolve event ref + SHA]
  F --> G[Select eligible workflow revision]
  G --> H[Create run ID / attempt]
  H --> I[Evaluate jobs and if conditions]
  I --> J[Queue jobs for runners]

Notice where “no run” appears. A trigger filter is upstream of run creation. By contrast, jobs.<id>.if is downstream: the run can exist while one or more jobs are skipped. Those states look different in history and should not be described with the same word.

3. Event identity has several fields that answer different questions

4. Push and pull-request refs answer different CI questions

A push run naturally describes the branch or tag that was pushed. For an open pull_request run, GitHub normally sets GITHUB_REF to the PR merge branch and GITHUB_SHA to the merge commit for that merge branch. That lets CI test the result of merging the PR head into the base branch rather than only the head commit in isolation.

5. The workflow file itself has a revision

GitHub searches .github/workflows at the commit/ref associated with the event, subject to event-specific rules. A run therefore has both a source/event revision and a workflow definition that GitHub selected. For several trigger families, the workflow must exist on the default branch before GitHub will accept the event as a workflow trigger. This matters when someone tests a new workflow_dispatch or scheduled workflow only on an unmerged feature branch and wonders why no button or run appears.

6. Read-only event probe: inspect selected fields, not the whole context

The following workflow intentionally does not check out code or call the GitHub API. It records only the fields needed to understand trigger identity. Passing values through environment variables also avoids directly interpolating event-derived text into a shell command.

name: Chapter 03 event probe

on:
  workflow_dispatch:

permissions: {}

defaults:
  run:
    shell: bash

jobs:
  inspect:
    runs-on: ubuntu-24.04
    env:
      EVENT_NAME: ${{ github.event_name }}
      EVENT_ACTION: ${{ github.event.action }}
      ACTOR: ${{ github.actor }}
      REF: ${{ github.ref }}
      SHA: ${{ github.sha }}
      BASE_REF: ${{ github.base_ref }}
      HEAD_REF: ${{ github.head_ref }}
      WORKFLOW_REF: ${{ github.workflow_ref }}
    steps:
      - name: Print bounded event identity
        run: |
          printf 'event=%s action=%s actor=%s\n' "$EVENT_NAME" "$EVENT_ACTION" "$ACTOR"
          printf 'ref=%s sha=%s\n' "$REF" "$SHA"
          printf 'base=%s head=%s\n' "$BASE_REF" "$HEAD_REF"
          printf 'workflow_ref=%s\n' "$WORKFLOW_REF"
          printf 'run=%s attempt=%s\n' "$GITHUB_RUN_ID" "$GITHUB_RUN_ATTEMPT"

Do not print the entire github context as a beginner shortcut. It is much easier to reason about a small allow-list of fields, and later security chapters will explain why broad context dumping is unsafe.

7. Trigger skip versus job skip

One subtle governance consequence: when a workflow is skipped by branch/path filtering, checks associated with that workflow can remain pending if branch protection requires them. Trigger design and required-check design must therefore be reviewed together.

8. DevOps operating principle: prove why the run exists

For every production run, you should be able to reconstruct: event name/action, actor, ref/SHA, workflow path/revision, trigger filters, run ID/attempt, and the resulting job graph. That record lets incident responders answer whether the wrong event fired, whether the right event selected the wrong revision, or whether the trigger layer worked and the failure belongs later.

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.