Events and triggers: what fires a workflow, and the pull_request_target trap

The on: block is the whole entry point

A workflow does nothing until an event matches its on: block. There are three broad event families, and the distinction governs both behavior and security:

on:
  push:
    branches: [main, "release/**"]
    paths-ignore: ["docs/**"]
  pull_request:
    types: [opened, synchronize, reopened]
  schedule:
    - cron: "17 3 * * 1-5"   # 03:17 UTC, Mon–Fri — offset to dodge the top-of-hour stampede
  workflow_dispatch:          # manual, with typed inputs
  workflow_call:              # invoked as a reusable workflow by another

Filters compose with AND across keys, OR within a list: branches: [main] and paths: [src/**] both must hold, but any branch in the list matches. paths and paths-ignore are mutually exclusive on one event; mixing positive and negative globs in a single paths list is the usual source of “why didn’t my workflow run.” A subtlety that bites teams using required status checks: if a paths filter skips a workflow, the required check is reported as skipped, not passed — and a branch protection rule that requires it will block the merge forever unless you make the check pass-through. schedule cron is UTC-only and is best-effort: GitHub explicitly drops scheduled runs under high load, and runs on the top of the hour are the most likely to be delayed or dropped, which is why production schedules use an offset like 17 3.

pull_request vs pull_request_target — the security fork in the road

For a PR from a fork, pull_request runs the workflow from the PR’s head ref, in a sandbox with a read-only GITHUB_TOKEN and no access to secrets. That is the safe default: untrusted code runs, but it can’t reach anything valuable. pull_request_target runs the workflow from the base branch (so the workflow file is trusted) but in the context of the base repo with full secrets and a read-write token — while the fork’s code is what would be checked out if you naively actions/checkout the PR head. That combination is the exfiltration vector from the Hook: trusted trigger, untrusted code, live secrets.

# DANGEROUS: secrets in scope, then checks out the fork's code and runs it
on: pull_request_target
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}  # ← attacker's code
      - run: npm ci && npm test   # ← runs with NPM_TOKEN in env

The rule of thumb: use pull_request_target only to do trusted work that never executes fork code (label a PR, post a comment, run a check that reads metadata). The moment you need to build or test the contributor’s actual code, use pull_request and accept that secrets are off the table — or gate the privileged step behind a manual approval environment.

Concurrency: cancel the stale run before it wastes a runner

Every busy PR branch leaks runner minutes on runs that will be overtaken before they finish — and without a concurrency policy you pay for each one. Ask yourself: does anything useful come from running a CI suite against a commit that was superseded forty seconds ago?

When a contributor pushes three commits in five minutes, three runs queue. Without concurrency control all three execute, and the first two are obsolete the moment the third starts. The concurrency block fixes this:

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

cancel-in-progress: true cancels any in-progress run in the same group when a new one starts — the canonical PR pattern, keying on github.ref so each branch is its own group. This routinely cuts wasted minutes by a large fraction on busy branches. The inverse pattern matters too: for deploy workflows you want cancel-in-progress: false so a deploy is never killed mid-flight, and the group serializes deploys to one-at-a-time instead. When you add concurrency to a deploy workflow and a second deploy fires mid-run, decide first which failure mode you’d rather face — a half-deployed environment, or a queued deploy that waits. Concurrency is a queue gate, not a trigger — the event still fires; concurrency just decides which runs survive.