Events and Triggers

The on: key decides what wakes a workflow up. A push, a pull_request, a manual workflow_dispatch, a cron schedule, or any of dozens of other repo webhooks can be a trigger, and most workflows subscribe to two or three of them. Choosing the right events — and scoping them with filters — is most of what separates a pipeline that runs when it should from one that burns minutes on every irrelevant change.

One trigger deserves its own warning label before anything else: pull_request_target. It runs with the base repository's secrets and a write token, against a context derived from a fork's pull request. Used correctly it automates labels and comments; used carelessly it hands a stranger your credentials. The rest of this page builds up to why.

Push and Pull Request

The two everyday triggers are push and pull_request. Both take branch, tag, and path filters so you can fire only on the branches and files that matter. pull_request also has activity types — opened, synchronize (a new commit pushed to the PR), and reopened are the ones that mean "there is new code to test." Listing them explicitly skips redundant runs on label or assignee changes.

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

Manual and Scheduled

workflow_dispatch adds a "Run workflow" button in the Actions UI and accepts typed inputs so a manual run can be parameterized and validated. Note that the button only appears once the workflow file exists on the default branch — a dispatch trigger on a feature branch alone is invisible. schedule runs on POSIX cron, always in UTC, with a minimum interval of five minutes, and only ever on the default branch.

on:
  schedule:
    - cron: '0 3 * * *'
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [staging, production]
        required: true

The pull_request_target Hazard

For a pull request from a fork, the safe default pull_request runs against the PR's merge commit with a read-only token and no access to your secrets — precisely because the code came from someone you do not control. pull_request_target inverts that: it runs in the context of the base branch, with full secrets and a write GITHUB_TOKEN. That is exactly what you want for labeling or commenting on a PR, and exactly what you must never combine with checking out and executing the fork's code.

Filtering

Filters narrow which activity actually triggers a run: branches/branches-ignore, paths/paths-ignore, and tags. You cannot use the include and ignore form of the same filter together under one event — branches alongside branches-ignore is a configuration error. A paths: filter is the standard way to skip CI when only documentation changed.

Other Triggers

Beyond push and PR there is a long tail: release for publishing flows, issues for triage automation, workflow_run to chain one workflow off another's completion, and repository_dispatch for kicking a workflow from an external system over the API. They all plug into the same on: key and the same event-driven model.