/gear

Triggers and Events

Purpose: Choose the right GitHub Actions event, filter it safely, and avoid unsafe or over-coupled trigger graphs.

Contents

• Event selection
• Trigger limits and gotchas
• Filtering rules
• Safe fork PR handling
• Common patterns
• Decision ladder

Event Selection

Trigger Limits And Gotchas

• workflow_dispatch inputs are capped at 25 keys (raised from 10 on Dec 4, 2025) and 65,535 characters total. Same cap applies to repository_dispatch.client_payload.
• repository_dispatch needs a token that can call the API. GITHUB_TOKEN cannot trigger another workflow through this event.
• workflow_run should filter by upstream conclusion:

if: github.event.workflow_run.conclusion == 'success'

• Workflow-level paths filters can skip the whole workflow only. For job-level routing, use dorny/paths-filter.
• Merge queue checks must include merge_group; pull_request alone is not enough. Misalignment between the required check name on the pull_request run and the merge_group run will block the queue indefinitely.
• "Required Workflows" (the legacy org-level setting) was retired Oct 18, 2023 — required workflows are now configured via Repository Rules / Rulesets. Rulesets evaluate the workflow against pull_request and/or merge_group triggers; reusable workflows entered via workflow_call cannot be made required.
• schedule honors timezone: (IANA) as of March 2026 — write timezone: 'Asia/Tokyo' next to the cron expression instead of pre-computing UTC offsets. Scheduler lag (15 min - 2+ h) still applies during peak hours.
• pull_request_target treats all fork-controlled data as hostile: titles, branch names, labels, artifacts, the Actions cache (May 2026 TanStack incident), and code.

Filtering Rules

Rule: do not mix branches with branches-ignore for the same event. Use negation inside branches when you need both inclusion and exclusion.

Safe Fork PR Handling

Use pull_request for normal CI on forks. Use pull_request_target only when you need base-repo permissions for metadata workflows such as labeling or comment-driven automation.

Secrets are not available to pull_request workflows triggered from forks — that is the platform safety guarantee. Reaching for pull_request_target to "get secrets back" is the exact failure mode that Mini Shai-Hulud (Sept 2025 - May 2026) repeatedly exploited; route deployments through workflow_run after the trusted push/merge instead.

Safe pattern:

on:
  pull_request_target:
    types: [opened, synchronize, labeled]

jobs:
  metadata-only:
    permissions:
      pull-requests: write
      contents: read
    steps:
      - run: echo "Label, comment, or gate only. Do not checkout fork code."

Unsafe patterns (do not ship):

# Checkout of fork-controlled head in pull_request_target context
- uses: actions/checkout@<sha>
  with:
    ref: ${{ github.event.pull_request.head.sha }}

# Restoring an Actions cache key that a fork PR can influence
- uses: actions/cache@<sha>
  with:
    key: build-${{ github.event.pull_request.head.ref }}

Both leak base-repo secrets / OIDC tokens to fork-controlled code paths.

Common Patterns

Decision Ladder

1. Start with push and pull_request.
2. Add merge_group if merge queue exists, and make sure the required check name matches the pull_request run.
3. Use workflow_dispatch for manual replay, rollback, or safe testing (up to 25 typed inputs).
4. Use repository_dispatch when another repo or an external system must trigger the workflow.
5. Use workflow_run only for post-success chaining, and redesign if the chain wants to reach depth 3.
6. Use pull_request_target only for metadata workflows that never execute untrusted fork code, never restore a cache key influenced by fork data, and never grant write tokens beyond the metadata surface (pull-requests: write at most).
7. Use schedule with timezone: for periodic jobs; expect scheduler drift and re-arm the 60-day idle disable by keeping the repo active (real commits / PRs, not keep-alive bumps).