Events and Triggers

Events and Triggers

The on configuration determines when a workflow is eligible to run. Precise triggers reduce noise and cost while ensuring important changes are validated. Event payloads are available through the github context and the file path stored in github.event_path.

Core ideas

• push can filter branches, tags, and changed paths.
• pull_request runs in the base repository context; activity types can narrow actions such as opened or synchronize.
• workflow_dispatch provides a manual entry point with typed inputs.
• schedule uses POSIX cron in UTC and runs from the default branch; scheduled runs can be delayed during high load.

How it works

Filters at the same level are combined according to GitHub's event rules. When both branch and path filters are present, both must match. A skipped required workflow can leave a required check pending, so design required checks and filters together.

Configuration example

on:
  push:
    branches: [main, "release/**"]
    paths:
      - "src/**"
      - "package-lock.json"
  pull_request:
    types: [opened, synchronize, reopened]
  schedule:
    - cron: "23 2 * * 1-5"
  workflow_dispatch:
    inputs:
      deploy:
        type: boolean
        default: false

Read the example from top to bottom: the trigger creates a run, the job requests a runner, and each step receives only the context configured for it. Adapt names, versions, permissions, and commands to the repository rather than copying production credentials or policies blindly.

Production guidance

• Use a non-round cron minute to reduce contention at the top of the hour.
• Inspect the event name and ref in logs while developing trigger logic.
• Treat pull_request_target as privileged: never check out and execute untrusted pull-request code with its credentials.

The chapter quiz follows this lesson and checks both the vocabulary and the operational decisions behind the configuration.