Events and Triggers
The on key decides when a workflow runs, from pushes to schedules to manual clicks.
The on key lists the events that start a workflow. Common triggers:
push— code is pushed to the repo.pull_request— a PR is opened or updated.schedule— run on a cron timetable.workflow_dispatch— a manual Run workflow button.release— a release is published.
Filtering
Narrow triggers by branch, tag, or changed path so workflows only run when relevant.
Example
on:
push:
branches: [main]
paths:
- "src/**"
pull_request:
branches: [main]
schedule:
- cron: "0 6 * * 1" # every Monday at 06:00 UTC
workflow_dispatch: # adds a manual run buttonWhen to use it
- A workflow triggers only on push to main and pull_request so it does not waste runner minutes on every branch push.
- A nightly cron workflow runs at 02:00 UTC to rebuild Docker image caches, keeping scheduled maintenance off the critical path.
- A team uses workflow_dispatch to allow manual one-click deployments to production from the GitHub Actions UI.
More examples
Trigger on push and PR with filters
Fires on push to main or any release branch but skips runs when only Markdown or documentation files changed.
on:
push:
branches: [main, 'release/**']
paths-ignore: ['**.md', 'docs/**']
pull_request:
branches: [main]Scheduled cron trigger
Schedules the workflow on weekday mornings and also adds a manual trigger so it can be run on demand from the Actions tab.
on:
schedule:
# Every weekday at 03:00 UTC
- cron: '0 3 * * 1-5'
workflow_dispatch:Trigger on an external repository event
repository_dispatch lets an external system POST to the GitHub API to fire this workflow with a custom event type and payload.
on:
repository_dispatch:
types: [deploy-staging]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- run: echo "Deploying ${{ github.event.client_payload.version }}"
Discussion