Triggers & Events: Controlling When Pipelines Run — CI/CD Pipelines with GitHub Actions

A pipeline that runs at the wrong time is worse than no pipeline. In this lesson you'll master the on: block — the gatekeeper that decides when your automation fires.

The Mental Model: Events → Workflows

GitHub constantly emits events as things happen in your repository. Your workflow's on: block subscribes to specific events — like a webhook listener.

Only events matching your on: filter trigger the workflow. Everything else is ignored.

Think of on: as a subscription filter. GitHub emits hundreds of event types — your workflow only wakes up for the ones you explicitly subscribe to.

The Trigger Categories

All triggers fall into four categories. As an architect, you'll use all four:

The four trigger categories — most workflows use Code Events + one other

Push & Pull Request: The Workhorses

90% of your triggers will be push and pull_request. Here's the crucial difference:

Branch & Path Filtering

Raw triggers are too broad. Filters narrow them to exactly what you need:

Branch Filters

on:
  push:
    branches:
      - main            # exact match
      - 'release/**'    # glob: release/1.0, release/2.0, etc.
    branches-ignore:
      - 'dependabot/**' # skip auto-update branches

Path Filters (Critical for Mono-Repos)

on:
  push:
    paths:
      - 'src/**'             # Only when source code changes
      - 'package-lock.json'  # Or when deps change
    paths-ignore:
      - '**.md'              # Never run for docs changes
      - 'docs/**'

Path filters prevent wasted pipeline runs — if only docs changed, why rebuild?

Architect decision: Path filters save minutes and money. In a mono-repo with 10 services, you don't want ALL services rebuilding when only one service's code changed. This is how you solve it.

Tag Triggers (Releases)

on:
  push:
    tags:
      - 'v*'           # v1.0.0, v2.3.1, v0.1.0-rc.1
      - '!v*-rc*'      # exclude release candidates

This is how release pipelines work: you tag a commit → pipeline builds and publishes the release. We'll build this in a later lesson.

Schedule (Cron Syntax)

on:
  schedule:
    - cron: '0 2 * * 1'   # Every Monday at 2:00 AM UTC

Cron syntax: minute hour day-of-month month day-of-week (* = any)

Manual Trigger: workflow_dispatch

This adds a "Run workflow" button in the GitHub UI. Essential for operational tasks:

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options:
          - staging
          - production
      reason:
        description: 'Why are you deploying?'
        required: true
        type: string

workflow_dispatch creates an interactive form in the GitHub Actions UI

Access inputs in your workflow with ${{ inputs.environment }}

🏋️ Exercise: Multi-Trigger Workflow

Update your ci.yml to use multiple triggers with filters:

name: CI

on:
  push:
    branches: [main]
    paths-ignore:
      - '**.md'
  pull_request:
    branches: [main]
  workflow_dispatch:  # manual trigger too

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test
      - name: Show trigger info
        run: |
          echo "Triggered by: ${{ github.event_name }}"
          echo "Branch: ${{ github.ref_name }}"

Test it three ways:

Push to main → watch it trigger
Edit only README.md and push → it should NOT trigger (paths-ignore)
Go to Actions tab → click "Run workflow" → it runs manually

Decision Framework: Which Trigger When?

Scenario	Trigger	Why
Validate PR before merge	`pull_request`	Gatekeeper — catch bugs before main
Deploy after merge	`push: branches: [main]`	Only deploy validated code
Create a release	`push: tags: ['v*']`	Version tag = release intent
Nightly security scan	`schedule: cron`	Catch new CVEs even without code changes
Emergency rollback	`workflow_dispatch`	Human-initiated, parameterised
Mono-repo: only changed service	`push: paths: ['svc-a/**']`	Don't waste time rebuilding unchanged services

🧠 Recall Check

What's the difference between on: push and on: pull_request in terms of when they fire?
You change only README.md. Your workflow has paths-ignore: ['**.md']. Does it run?
How do you make a workflow runnable manually from the GitHub UI?
What trigger would you use for a "scan for vulnerabilities every night" workflow?

Reveal answers

push fires when commits land on a branch (after merge/direct push). pull_request fires when a PR is opened, updated, or reopened (before merge).
No. The only changed file matches paths-ignore, so the workflow is skipped.
Add workflow_dispatch: to the on: block. Optionally define inputs: for parameters.
schedule with a cron expression, e.g., cron: '0 2 * * *' for 2 AM daily.

You now control when your pipeline runs — and equally important, when it doesn't. Next lesson: controlling how work is organised within a pipeline (jobs, parallelism, dependencies).