Triggers and Events
push, pull_request, schedule, workflow_dispatch, paths, and branches filters
Skills taught: cicd.triggers, cicd.push, cicd.pull-request, cicd.schedule, cicd.paths-filter
Every way to trigger a workflow
on:
# ── Code events ────────────────────────────────────────
# Push to specific branches
push:
branches:
- main
- 'release/**' # wildcard: release/1.0, release/2.0
- '!dev/**' # ! = exclude this pattern
tags:
- 'v*' # any tag starting with v (v1.0, v2.3.1)
paths:
- 'src/**' # only trigger if src/ files changed
- '!src/**/*.test.ts' # but NOT test files
# Pull request events
pull_request:
types: [opened, synchronize, reopened] # default
branches: [main]
# ── Manual triggers ─────────────────────────────────────
# Manual run from GitHub UI or API
workflow_dispatch:
inputs:
environment:
description: 'Deploy target'
required: true
default: 'staging'
type: choice
options: [staging, production]
dry_run:
description: 'Dry run only (no actual deploy)'
type: boolean
default: false
# Called by another workflow
workflow_call:
inputs:
image_tag:
required: true
type: string
# ── Scheduled triggers ──────────────────────────────────
# Cron syntax (UTC): daily at 2:30am
schedule:
- cron: '30 2 * * *' # daily at 2:30 UTC
- cron: '0 9 * * 1' # every Monday at 9am UTC
# ── Other useful events ─────────────────────────────────
release:
types: [published] # runs when a GitHub Release is published
issues:
types: [opened] # run on new issue
repository_dispatch: # external HTTP call triggers this
types: [deploy]
Practical trigger patterns
# ── Pattern 1: PR check (validate before merge) ──────────
name: PR Check
on:
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci && npm test
---
# ── Pattern 2: Deploy on push to main ────────────────────
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: ./deploy.sh
---
# ── Pattern 3: Nightly dependency audit ─────────────────
name: Security Audit
on:
schedule:
- cron: '0 6 * * *' # 6am UTC daily
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm audit --audit-level=high
---
# ── Pattern 4: Only run when relevant files change ───────
name: Backend CI
on:
push:
paths:
- 'server/**'
- 'packages/api/**'
- '!**/*.md' # ignore markdown changes
Using workflow_dispatch inputs
name: Manual Deploy
on:
workflow_dispatch:
inputs:
environment:
type: choice
options: [staging, production]
required: true
image_tag:
description: 'Docker image tag to deploy'
required: true
default: 'latest'
jobs:
deploy:
runs-on: ubuntu-latest
environment: ${{ inputs.environment }} # requires manual approval if set up
steps:
- name: Deploy
run: |
echo "Deploying tag: ${{ inputs.image_tag }}"
echo "Target: ${{ inputs.environment }}"
./scripts/deploy.sh \
--env ${{ inputs.environment }} \
--tag ${{ inputs.image_tag }}
Tip: Use paths filtering to speed up monorepos. In a monorepo with frontend and backend packages, add paths: ['server/**'] to the backend workflow so backend CI only runs when backend files change. Without this, a README fix in the frontend triggers the entire backend test suite — wasting minutes of CI time on every commit.
Frequently Asked Questions
How do I trigger a workflow from another workflow?
Two ways: (1) workflow_call — defines a reusable workflow that other workflows call with 'uses: ./.github/workflows/shared.yml'. (2) repository_dispatch — one workflow makes an HTTP POST to the GitHub API to trigger another. workflow_call is preferred for same-repo orchestration.