A trigger is the event or condition that starts a GitHub Actions workflow. It is declared with the root-level `on:` key in a YAML workflow stored under `.github/workflows`; once it fires, the workflow can run its defined jobs and steps. Triggers make automations responsive to repository activity, scheduled work, manual operations, and release handoffs. section 1.2 section 3.3
Choose a trigger type based on how the automation should begin:
- Webhook triggers respond to GitHub events, including `push`, `pull_request`, issues activity, repository stars, branch-protection changes, and visibility changes. section 3.3.1
- Scheduled triggers run work on a defined schedule, while manual triggers let an operator start a workflow on demand. section 3.3
- `workflow_dispatch` enables manual runs from the Actions interface after the workflow containing that trigger is available on the main branch, unless the API is used. section 2.4 section 3.9
Webhook triggers can be broad or narrowly scoped. A plain `on: push` runs for pushes, while configuration beneath `push:` can limit runs to branches and changed paths. Quote wildcard patterns because `*` has special meaning in YAML. Narrowing event conditions avoids running workflows when a change is irrelevant to their purpose. section 3.3.1 section 2.2
on:
push:
branches:
- 'main'
- 'release/**'
paths:
- 'doc/**'
This configuration combines branch and path filters: documentation changes must be pushed to `main` or a `release/` branch before the workflow starts. section 3.3.1
Manual and push-started workflow
A first workflow can start automatically on any push, then add `workflow_dispatch` so it can also be run from the Actions tab. Committing that workflow to the main branch produces a push-triggered run; the run view identifies its trigger, branch, status, duration, jobs, and logs. This provides a quick way to verify both the event-driven and operator-driven paths. section 2.2 section 2.3 section 2.4
Triggers also define automation boundaries beyond CI. An issue workflow can start when an issue is opened or edited and then label it from its body. For continuous delivery, a `release` trigger filtered to `published` starts deployment when a release is created, using the release as the handoff after CI has produced the artifacts. section 1.3 section 9.1.2
Test trigger behavior without disrupting active development. Create webhook-triggered workflows in a fork when practical, then merge the finished workflow back to the original repository. For workflows developed on branches, account for manual-trigger availability and use the API where needed. Workflow-editor autocomplete, validation, and error highlighting help ensure that `on:` configuration is correctly formed before committing. section 3.9 section 2.2
