Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 44 Β· GitHub Actions Basics

Triggers: push, pull_request, schedule and More

Learn GitHub Actions triggers: branch and path filters, pull_request versus pull_request_target, manual runs with inputs, cron schedules and release events.

The on: key decides when a workflow runs, and getting it right matters more than it first seems. A trigger that is too wide wastes minutes (and money) by running on every irrelevant push. A trigger that is too narrow lets broken code reach main without a check. And one trigger in particular, pull_request_target, can open a serious security hole when used carelessly.

This lesson covers the triggers you will use daily: push and pull_request with branch, tag and path filters, manual runs with inputs, scheduled runs, workflows that other workflows call, and release events. Because GitHub itself cannot run on this website, the YAML is read-only. Two stand-ins let you practise the logic: one matches events against filters, and one calculates the next run times of a cron schedule.

The on key

You can write on in three ways. A single event name is the shortest:

YAML
on: push

A list runs the workflow for any of several events:

YAML
on: [push, pull_request]

A mapping lets you configure each event with filters and options. It is the form you will use most:

YAML
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

push and pull_request

push runs when commits are pushed to a branch or a tag is pushed. pull_request runs when something happens to a pull request. Its default activity types are opened, synchronize (new commits pushed to the branch) and reopened, which is what you want for CI. You can list other types, such as ready_for_review or labeled, with types:.

A common setup runs CI on pull requests and on pushes to main:

YAML
on:
  push:
    branches: [main]
  pull_request:

Careful: if you listed push: with no branch filter and pull_request:, then a push to a branch with an open pull request would start two runs: one for each event. Limiting push to main avoids that duplication.

Filters for branches, tags and paths

Filters narrow when an event starts the workflow.

YAML
on:
  push:
    branches:
      - main
      - "release/**"
    paths:
      - "src/**"
      - "package*.json"
  pull_request:
    paths-ignore:
      - "docs/**"
      - "**.md"

The rules are easy to get wrong, so learn them well:

  • Patterns use glob-like wildcards. * matches any characters except /; ** matches any characters including /. So release/* matches release/1.0 but not release/1.0/hotfix, whereas release/** matches both.
  • Branches and paths must both match when you use both. The workflow starts only if the branch matches and at least one changed file matches paths.
  • branches and branches-ignore cannot be combined for one event; the same is true for paths and paths-ignore. To both include and exclude, use one list with ! patterns: ["**", "!experiment/**"]. Patterns are evaluated in order, and a later ! pattern removes matches from earlier ones.
  • Tags are separate. A branches filter alone does not trigger on tag pushes. To run on v1.2.0, use tags: ["v*.*.*"].
  • Quote patterns that start with *, ! or other special YAML characters (see YAML for Pipeline Authors).

Path filters have one catch. If a workflow is a required status check for merging, and a path filter makes it skip, the check never reports and the pull request can be blocked as "waiting". Plan for that when you combine branch protection with path filters.

The next stand-in implements these matching rules. It does not use GitHub's real engine: it supports *, ** and !, and does not implement ?, + or character classes. Read the output and compare each decision with the rules above.

JS Which workflows run for which events?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try editing the filters: change docs.yml to paths: ["docs/**"] and see the README push stop matching, or add a ! pattern to ci.yml.

pull_request versus pull_request_target

Both events fire for pull requests, but they run in very different security contexts.

pull_request pull_request_target
Which workflow file runs The one from the pull request's merge commit The one from the base branch (for example main)
Code checked out by default The merged result of the pull request The base branch, not the pull request code
Secrets and write token for forks No secrets, read-only token Secrets and a read/write token are available
Typical use Build and test the proposed change Label or comment on pull requests, including those from forks

The point of the table: for a pull request from a fork, plain pull_request runs with no secrets and a read-only token, so untrusted code can do little damage. pull_request_target gives the workflow privileges. If that workflow then checks out the pull request's code and runs it (a build script, an npm install with install scripts), the attacker's code runs with your secrets. This mistake has led to real compromises. The rule: never check out and execute untrusted pull request code in a pull_request_target workflow. Use it only for tasks that do not run that code, such as adding labels. Securing Your Pipeline returns to this.

Manual runs with workflow_dispatch

workflow_dispatch adds a Run workflow button to the Actions tab (and lets the GitHub CLI or API start the workflow). It can take typed inputs that you read through the inputs context:

YAML
on:
  workflow_dispatch:
    inputs:
      environment:
        description: "Where to deploy"
        type: choice
        options: [staging, production]
        default: staging
      dry_run:
        description: "Skip the actual deploy"
        type: boolean
        default: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to ${{ inputs.environment }}, dry run is ${{ inputs.dry_run }}"

Input types include string, boolean, choice and environment. The button only appears when the workflow file exists on the repository's default branch, which surprises many people who test on a feature branch.

Scheduled runs

The schedule event runs a workflow at times you describe with a cron expression:

YAML
on:
  schedule:
    - cron: "30 5 * * 1-5"   # 05:30 UTC, Monday to Friday

A cron expression has five fields: minute, hour, day of month, month, day of week.

TEXT
 β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ minute (0-59)
 β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ hour (0-23)
 β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€ day of month (1-31)
 β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€ month (1-12)
 β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€ day of week (0-6, Sunday is 0)
 * * * * *

Special characters: * means every value, , lists values (5,17), - is a range (1-5) and / is a step (*/15 means every 15 units). Things to remember about GitHub's schedules:

  • Times are in UTC, not your local time zone.
  • They run from the workflow file on the default branch only.
  • The shortest interval is every 5 minutes, and runs can be delayed when GitHub is busy, so never rely on exact timing.
  • In public repositories, scheduled workflows are automatically disabled after a period (60 days) with no repository activity.
  • Always quote the expression, because * at the start of a YAML value has a special meaning.

When both "day of month" and "day of week" are restricted, classic cron runs when either matches. The stand-in below follows that rule. It simulates cron matching minute by minute; it is a teaching model, not GitHub's scheduler.

JS When does this cron expression run next?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Change the expressions and the start date to explore. For example, 0 0 13 * 5 (the 13th, or any Friday) shows the "either field" rule.

workflow_call and release events

workflow_call makes a workflow callable by other workflows, which turns it into a reusable building block with inputs, secrets and outputs. The details come in Reusable Workflows and Composite Actions. The line that enables it is simply:

YAML
on:
  workflow_call:

Release automation uses two kinds of triggers. Pushing a version tag is the simplest:

YAML
on:
  push:
    tags:
      - "v*.*.*"

The release event reacts to GitHub Releases, with activity types such as published, created and released:

YAML
on:
  release:
    types: [published]

Choose published unless you have a reason not to: it fires when a release (or pre-release) becomes public, while created also fires for drafts being created. Other events worth knowing are workflow_run (run after another workflow finishes), repository_dispatch (start from an external API call), issues and issue_comment.

flowchart TD
    E["Event happens on GitHub"] --> M{"Does the event type<br/>match on:?"}
    M -->|"No"| X["Nothing runs"]
    M -->|"Yes"| F{"Do branch, tag<br/>and path filters match?"}
    F -->|"No"| X
    F -->|"Yes"| R["Workflow run starts"]

GitHub checks the event type first, then the filters. Both must pass.

Check your understanding

Quick check Β· 5 questions

of 5 answered You scored / 5 Β· perfect!

  1. 1. A workflow has on: push: branches: [main] and paths: ["src/**"]. A push to main changes only README.md. What happens?

    When both filters are present, both must be satisfied: the branch matches, but no changed file matches src/**, so the workflow is skipped.
  2. 2. Why is pull_request_target dangerous if the workflow checks out and runs the pull request's code?

    pull_request_target runs in the privileged context of the base repository. Running a fork's code there hands that code your secrets. Use plain pull_request for building and testing.
  3. 3. In which time zone does a GitHub Actions schedule cron expression run?

    Schedules are evaluated in UTC, and they are read from the workflow file on the default branch.
  4. 4. Which pattern matches release/1.0/hotfix?

    A single * never crosses a slash, so release/* only matches one level. ** matches any characters, including slashes.
  5. 5. You added workflow_dispatch on a feature branch, but the Run workflow button does not appear. Why?

    Merge the workflow file into the default branch to get the button. You can still start it from a branch through the CLI or API once the file exists on the default branch.

Summary

  • on can be an event name, a list or a mapping; use the mapping to add filters.
  • push and pull_request accept branches, tags and paths filters (and -ignore variants); * stops at /, ** does not, and a branch and a path filter must both match.
  • Prefer pull_request for CI; use pull_request_target only for tasks that never run untrusted pull request code.
  • workflow_dispatch adds a manual button with typed inputs, available once the file is on the default branch.
  • schedule uses five-field cron in UTC, runs from the default branch, may be delayed and has a five-minute minimum interval.
  • workflow_call makes a workflow reusable; tags and release events drive release automation.

Next: Jobs, Steps and Dependencies