Triggers (on:)

Every way to start a workflow: push with branch, tag and path filters, pull requests, manual runs with inputs, cron schedules, releases and calls from other workflows.

#github-actions #triggers #events

Common triggers

on: examples

YAML

1on:

2 push:

3 branches: [main, 'release/**'] # glob patterns allowed

4 tags: ['v*.*.*'] # fires when you push a tag like v1.4.0

5 paths: ['src/**', 'pom.xml'] # only if these files changed

6 paths-ignore: ['**.md', 'docs/**']

8 pull_request:

9 branches: [main]

10 types: [opened, synchronize, reopened] # default set

12 workflow_dispatch: # manual button + inputs

13 inputs:

14 environment:

15 type: choice

16 options: [staging, production]

17 default: staging

18 dry_run:

19 type: boolean

20 default: false

22 schedule:

23 - cron: '0 3 * * 1-5' # 03:00 UTC Mon-Fri (UTC only!)

25 release:

26 types: [published] # when a GitHub Release is published

28 workflow_call: # makes this a reusable workflow

29 inputs:

30 image: { type: string, required: true }

Which one when

Goal	Trigger
Test every change	`pull_request` + `push: branches: [main]`
Release a version	`push: tags: ['v..*']`
Deploy on demand	`workflow_dispatch` with an environment input
Nightly jobs, cleanup	`schedule` (cron, UTC)
Share one pipeline across repos	`workflow_call`
Monorepo: build only what changed	`paths:` filters

Read manual inputs with ${{ inputs.environment }}. Trigger from CLI: gh workflow run deploy.yml -f environment=production.

Gotchas

branches and tags under the same push are OR-ed: a tag push is not filtered by branches.
schedule runs only on the default branch and can be delayed at busy times.
Workflows triggered by the default GITHUB_TOKEN do not start other workflows (prevents loops); use a GitHub App token or PAT if you need chaining.

Avoid pull_request_target unless you understand it: it runs with write access and secrets in the context of the base repo, which is dangerous with code from forks.