GitHub Actions Triggers

A trigger tells GitHub Actions when to start a workflow. Without a trigger, a workflow never runs. GitHub supports over 35 different events, from code pushes to scheduled times to manual button clicks. This topic covers the triggers you will use most often.

How Triggers Work

Think of triggers like motion sensors in a building. The lights do nothing until someone walks through the door. The motion sensor (trigger) detects the movement (event) and turns on the lights (workflow).

Developer opens a pull request → (Event fires)
            ↓
GitHub detects the event → (Trigger activates)
            ↓
Workflow starts automatically → (Jobs run)

You define triggers in the on section at the top of your workflow file.

The push Trigger

The push trigger fires when someone pushes code to the repository. You can limit it to specific branches or tags.

on:
  push:
    branches:
      - main
      - develop

This workflow runs only when code is pushed to the main or develop branches. Pushes to other branches (like feature branches) are ignored.

Filtering by file path

You can also trigger only when specific files change:

on:
  push:
    paths:
      - 'src/**'
      - 'package.json'

The ** wildcard matches any file inside the src folder. Changes to other files (like README edits) will not start this workflow.

The pull_request Trigger

The pull_request trigger fires when a pull request is opened, updated, or synchronized against a target branch.

on:
  pull_request:
    branches:
      - main

This is the standard trigger for running tests before code gets merged. Teams rely on it to catch bugs before they reach the main branch.

Pull request activity types

You can narrow the trigger to specific pull request actions:

on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize

• opened — fires when a new pull request is created
• reopened — fires when a closed pull request is reopened
• synchronize — fires when new commits are pushed to the pull request

The schedule Trigger

The schedule trigger runs a workflow at a fixed time using cron syntax. Cron is a standard format for expressing time-based schedules.

on:
  schedule:
    - cron: '0 9 * * 1'

Reading cron format from left to right:

  0    9    *    *    1
  │    │    │    │    └─ Day of week (1 = Monday)
  │    │    │    └────── Month (any)
  │    │    └─────────── Day of month (any)
  │    └──────────────── Hour (9 AM UTC)
  └───────────────────── Minute (0 = start of hour)

The example above runs the workflow every Monday at 9:00 AM UTC. Teams use scheduled triggers for nightly builds, weekly cleanup tasks, and regular health checks.

The workflow_dispatch Trigger

The workflow_dispatch trigger adds a manual "Run workflow" button to the Actions tab in GitHub. You click it whenever you want to start the workflow on demand.

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

The inputs block lets you define form fields that appear when the button is clicked. In this example, the person running the workflow chooses between "staging" and "production" before starting it.

The release Trigger

The release trigger fires when a GitHub release is published, edited, or deleted.

on:
  release:
    types:
      - published

Teams use this trigger to deploy new versions of their application automatically when a release is published on GitHub.

Combining Multiple Triggers

One workflow can listen for multiple events at the same time:

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

This workflow runs when code is pushed to main, when a pull request targets main, or when someone clicks the manual run button. Each trigger is independent — any one of them starts the workflow.

Trigger Comparison at a Glance

Trigger              | When it fires
---------------------|------------------------------------------
push                 | Code pushed to a branch or tag
pull_request         | PR opened, updated, or synchronized
schedule             | Fixed time using cron expression
workflow_dispatch    | Manual button click in GitHub UI
release              | GitHub release published or updated
workflow_call        | Called by another workflow (covered later)

Branch Protection and Triggers

Many teams set up branch protection rules on their main branch. These rules can require that specific workflows pass before a pull request can be merged. The pull_request trigger powers this gate — it runs the test workflow on every pull request, and GitHub blocks the merge if the workflow fails.