workflow
on:
Declares the events that trigger the workflow. Accepts a single event, a list, or a map with per-event filters (branches, paths, tags, types).
on: <event> | [event1, event2] | { event: {filters} }Common values / subkeys
| Value / Subkey | Purpose |
|---|---|
| push | Trigger on pushes; filter with branches/paths/tags |
| pull_request | Trigger on PR events; filter with types (opened, synchronize, closed) |
| workflow_dispatch | Manual run with optional typed inputs |
| schedule | Cron trigger (UTC only) |
| workflow_call | Marks workflow as reusable/callable |
| workflow_run | Trigger after another workflow completes |
Examples
on: [push, pull_request]Shorthand list of events, no filters
on:
push:
branches: [main]
paths: ['src/**']Push to main with path filter
on:
schedule:
- cron: '0 6 * * 1-5'Weekdays at 06:00 UTC
on:
workflow_dispatch:
inputs:
env:
type: choice
options: [dev, prod]Manual trigger with typed input
Gotcha
Cron schedules run in UTC and may be delayed under load; scheduled workflows on inactive repos are auto-disabled after 60 days.
Related keywords
concurrency:
Limits concurrent runs that share the same group so only one is active (and at most one pending). Set at the workflow or job level to serialize deploys or cancel superseded PR builds.
uses: <workflow_call>
Reusable workflows are files that declare `on: workflow_call` and can be invoked as a job in another workflow. The caller passes typed `with:` inputs and either inherits or explicitly forwards secrets.
${{ vars.* }} / ${{ inputs.* }}
`vars` exposes non-secret configuration variables defined at the repository, environment, or organization level. `inputs` exposes typed parameters passed to `workflow_dispatch`, `workflow_call`, or composite actions.
permissions:
Controls the scopes granted to the automatically generated GITHUB_TOKEN. Can be set at the workflow or job level; the job-level block overrides the workflow default.
env:
Defines environment variables for a scope. Declared at the workflow, job, or step level and read back via the `env` context or as real environment variables inside `run:` scripts.