What's changed: New GH-200 Chapter 1 (triggers & events = push/pull_request/schedule/workflow_dispatch/repository_dispatch/workflow_call with inputs/secrets; workflow structure = jobs/steps/needs/if, env/$GITHUB_ENV, service containers, strategy.matrix, contexts/${{ }}, YAML anchors; execution mgmt = artifacts/$GITHUB_OUTPUT/cache/$GITHUB_STEP_SUMMARY/badges/environment protections/retention REST API)
1.1Workflow Triggers and Events
Design when and on what a workflow runs. Understand scheduled, manual (workflow_dispatch), webhook, and repository events; defining workflow_dispatch inputs; passing inputs and secrets to reusable workflows via workflow_call; and choosing appropriate scope and permissions for each event.
A GitHub Actions workflow is a YAML file placed under .github/workflows/ in a repository. At its top it always uses the on: key to declare its trigger (event)—what has to happen for the workflow to run. GH-200 first tests choosing the right event. The common ones are push and pull_request (driven by code changes), schedule (periodic runs), workflow_dispatch (manual, human-started), repository_dispatch (started via API from another repo/external system), and many repository events such as issues, releases, and labels.
1.1.1Event types and when to use them
push and pull_request are the core of CI; filters like branches and paths narrow which branches/file changes trigger a run (use paths-ignore/branches-ignore to exclude). schedule runs periodically via a cron expression (UTC-based)—good for nightly tests or dependency checks, but watch the minimum interval, delays under load, and that schedules stop when a repo is inactive. workflow_dispatch allows manual starts from the GitHub UI/API/CLI, fitting operational tasks (deploys, data migrations). repository_dispatch is a webhook-style trigger from external systems, started via the API (POST) with a custom event name.
| Event | Triggered by | Typical use |
|---|---|---|
| push / pull_request | Code push, PR open/update | CI (build, test, lint) |
| schedule | cron expression (UTC) | Nightly tests, periodic checks |
| workflow_dispatch | Manual start from UI/API/CLI | Deploys, operational tasks |
| repository_dispatch | External API (POST) + custom event name | External system integration |
| workflow_call | Called by another workflow | Reusable workflows |
1.1.2workflow_dispatch inputs
workflow_dispatch can accept parameters at manual start. Under inputs you define each input with type (string, boolean, choice, number, environment), required, default, and—for choice—a list of options. Inside the workflow, read values via the inputs.<name> context (or github.event.inputs.<name>). This lets you build, for example, an operational workflow that "picks a target environment and runs." Inputs are validated (type, required, options), preventing invalid values.
1.1.3Reusable workflows (workflow_call) with inputs and secrets
To reuse the same logic across workflows, make a reusable workflow declaring on: workflow_call. The caller references it with uses: (owner/repo/.github/workflows/file.yml@ref) and passes inputs via with: and secrets via secrets:. Secrets can be passed individually or via secrets: inherit to forward all of the caller’s secrets. A reusable workflow can define outputs to return results to the caller. This centralizes and versions common logic like "build" or "deploy" in one place and standardizes it across the organization.
1.1.4Scope, permissions, and GITHUB_TOKEN
Once you pick an event, also scope the permissions you grant the workflow. Each run is issued a temporary credential called GITHUB_TOKEN for reading/writing the repo. Using the permissions: key to set least privilege (e.g., contents: read) is the safe default—elevate only the jobs that need writes. Especially when pull_request runs on PRs from forks, an external contributor’s code executes, so design to avoid write permissions and secret exposure (be careful with pull_request_target).
Common: (1) "manual start + parameters" = workflow_dispatch (inputs with type/required/default/options). (2) "periodic" = schedule (cron, UTC). (3) "started by external API" = repository_dispatch. (4) "call shared logic from another workflow" = workflow_call (reusable workflow) passing with: inputs and secrets: (inherit allowed). (5) Scope with permissions (least privilege); per-run credential is GITHUB_TOKEN.
Watch out: (1) schedule cron is UTC—writing local time drifts. It also has minimum intervals and delays, so it does not guarantee exact on-time runs. (2) workflow_dispatch (manual) and repository_dispatch (external API) are different. (3) Reusable workflows (workflow_call), starter workflows (copy a scaffold), and composite actions (an action bundling steps) are distinct concepts (Chapters 2–3). (4) Handling secrets on fork PRs risks exposure—mind pull_request vs pull_request_target.
1.1.5Section summary
- Declare triggers in
on:: push/pull_request (filter via branches/paths), schedule (cron, UTC), workflow_dispatch (manual), repository_dispatch (external API) - workflow_dispatch inputs: define type/required/default/options and read via inputs.<name>
- Reusable workflows: on: workflow_call with caller uses: / with: inputs / secrets: (inherit) / outputs
- Scope via permissions (least privilege); per-run temporary credential is GITHUB_TOKEN; mind fork-PR exposure
Sign in to track progress — Log in.
Quick check
(just a quick review)Q1. You want a workflow an operator starts via a button in the GitHub UI, choosing a "target environment" at start. Which trigger do you use?
Q2. For a schedule trigger running nightly tests via cron, which caution is correct?
Q3. You want to call a shared "build" logic from workflows in multiple repos and manage it centrally. Which event does the called workflow declare?
Q4. How do you forward all of the caller’s secrets to a reusable workflow at once?
Q5. A security review says to make the workflow’s GITHUB_TOKEN least privilege. What is the right action?
Q6. An external CI integration starts a GitHub workflow via API (POST) using a custom event name. Which trigger matches?