GitHub Actions Triggers, Events, Caching, Artifacts and Outputs (GH-200)

A workflow starts when an event named under its on: key happens. The GH-200 guide groups these into four kinds, plus two that link workflows together:

A workflow can list several events, and each event can carry its own filters:

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:
  schedule:
    - cron: '30 2 * * 1-5'

Several of these triggers — schedule, workflow_dispatch, repository_dispatch and workflow_run — only consider workflow files that exist on the default branch. A workflow that lives only on a feature branch can be triggered by pushes or pull requests on that branch, but never by these. That single rule explains many "my workflow never ran" scenarios.

A schedule trigger runs a workflow on a POSIX cron expression (minute, hour, day of month, month, day of week), and it behaves differently from every other trigger in five ways:

• Default branch only. Scheduled runs use the workflow file and the latest commit on the default branch. A cron added only on a feature branch never fires until it is merged.
• UTC unless you say otherwise. Cron is evaluated in UTC by default. You can add a timezone key with an IANA zone name (for example Europe/London) beside a cron entry; the schedule then follows that zone, including daylight saving changes. A hand-converted UTC time drifts by an hour twice a year. On the night clocks spring forward, a time inside the skipped hour runs at the next valid time (02:30 becomes 03:00) instead of being skipped.
• Five minutes is the shortest interval. Schedules more frequent than every five minutes are not supported.
• Not exact. Runs can be delayed at times of high load (the start of every hour is busiest), and very delayed runs may be dropped. Pick an odd minute when timing matters.
• Auto-disabled in quiet public repositories. In a public repository, GitHub disables scheduled workflows after 60 days with no repository activity. The symptom is no runs at all — not failing runs. Re-enable the workflow in the Actions tab (or via the API) once the repository is active again.

workflow_dispatch lets a person or a script start a workflow on demand and pass it typed inputs. Each input can have a description, required, default and a type:

on:
  workflow_dispatch:
    inputs:
      region:
        description: Region to rebuild
        type: choice
        options: [eu-west, us-east, ap-south]
        default: eu-west
      verbose:
        type: boolean
        required: false
        default: false

How inputs are validated. GitHub checks the declared inputs on every dispatch, not only in the form. The Run workflow form will not submit while a required input is empty, offers only the listed options for a choice input, and pre-fills each default. A dispatch through the REST API or gh workflow run is rejected (the API returns 422 Unprocessable Entity and no run is created) when it omits a required input that has no default, sends a value that is not in a choice input's options, or names an input the workflow does not declare. An omitted optional input takes its default. API callers send every value as JSON; the type declared in the workflow decides how it appears in the inputs context. Anything the type system cannot express — a version format, a value range — is validated in a step that fails the job.

Where the file must be. The Run workflow button only appears for workflow files on the default branch, and API dispatches of a file that is not there fail. Once a file with the trigger exists on the default branch, you can dispatch it against any ref (UI branch picker, ref in the API, gh workflow run --ref), and that run uses the workflow file and code from the chosen ref. The usual way to test a new manual workflow is therefore to merge a minimal stub to the default branch, then dispatch the feature branch.

Read inputs from the inputs context. inputs.<name> keeps each input's type, so a boolean is a real boolean. The older github.event.inputs.<name> turns every value into a string. Because expressions coerce mismatched types to numbers when comparing, github.event.inputs.verbose == false compares the string 'false' (which becomes NaN) with false and is never true; inputs.verbose == false works.

External systems: repository_dispatch

repository_dispatch is the trigger for activity that happens outside GitHub: a registry publishing a package, an incident tool, a CMS. The external system sends POST /repos/{owner}/{repo}/dispatches with a token, an event_type it chooses, and an optional client_payload of arbitrary JSON. GitHub answers 204 No Content, which only means the event was created — not that any workflow matched it.

on:
  repository_dispatch:
    types: [package-published, package-yanked]
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - run: echo "${{ github.event.action }} ${{ github.event.client_payload.version }}"

• types filters on event_type. A workflow without types runs for every dispatch; a workflow with types ignores event types it does not list.
• The event type is available as github.event.action, so one workflow can branch its jobs per signal.
• Payload fields are read from github.event.client_payload.<field> — not from inputs, which belongs to workflow_dispatch and workflow_call.

Filters narrow a repository event so the workflow runs only for the activity you care about. There are two families.

Activity types

Many events have several activity types. Without a types filter, pull_request (and pull_request_target) run only for opened, synchronize (new commits pushed) and reopened. Setting types replaces that default, so to add a type you list the defaults again:

on:
  pull_request:
    types: [opened, synchronize, reopened, labeled]

Each event family owns its own activity types. Labelling a pull request is the labeled activity of pull_request (or pull_request_target); the label event tracks the label definitions themselves (created, edited, deleted), and issues activity types cover issues only.

Branch, tag and path filters

• branches / branches-ignore and tags / tags-ignore take glob patterns. For pull_request, branches matches the base branch.
• On push, if you define only tags, branch pushes do not run the workflow (and vice versa) — the ref type you left out is not matched. on: push with tags: ['v*'] is the standard trigger for version tags pushed from the command line; release fires only for GitHub releases, and create also fires for new branches.
• paths runs the workflow when at least one changed file matches. paths-ignore skips it only when every changed file matches the ignored patterns — one file outside them is enough to run.
• When an event has both a branch (or tag) filter and a path filter, both must be satisfied.

Picking the right event is also a security decision, because each event decides which code runs, with which token and which secrets.

The dangerous combination is pull_request_target plus a checkout of github.event.pull_request.head.sha plus a build or test step: anything the fork controls — build scripts, test configuration, package-manager install hooks — then executes with the repository's secrets and a write-capable token. The workflow YAML itself still comes from the base branch, which is why the risk is easy to miss.

The standard pattern when untrusted code must be tested and something privileged must happen afterwards (posting results as a comment, for example) is a split: run the tests under pull_request, upload the results as an artifact, and let a second workflow on workflow_run download that artifact and post the comment — without ever executing fork code.

Events caused by the GITHUB_TOKEN

To prevent recursive runs, most events caused by the GITHUB_TOKEN — pushing a tag, pushing a commit outside a pull request, creating a release or an issue — do not start new workflow runs. The documented exceptions are workflow_dispatch and repository_dispatch, which a workflow creates deliberately. Pull requests are a special case: when a workflow creates or updates a pull request with the GITHUB_TOKEN (including pushing to its branch), the pull_request runs are created but wait until someone with write access approves them. When a follow-on workflow must run for something a workflow did, authenticate that action with a GitHub App installation token or a personal access token instead; extra permissions on the GITHUB_TOKEN do not change the rule.

Scope the GITHUB_TOKEN with permissions

Scope and permissions belong to the same decision as the event: choose the narrowest event and filters that do the job, and give the token only the scopes the jobs need. The token starts from the default set in the repository or organization settings — permissive (read and write for most scopes) or restricted (read access to contents and packages only); new organizations and repositories default to restricted. A permissions: key overrides that default at workflow level or for one job, and the moment you list any scope, every scope you did not list becomes none:

permissions:
  contents: read          # workflow default for every job
jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write       # this job only: comment on issues
    steps:
      - run: echo "triage"

Each scope takes read, write or none (write includes read). Pick the scope named after the object the job changes — issues for issue comments, contents for commits, tags and releases, pull-requests for pull request comments and reviews, actions for runs and artifacts — and only the access level it needs. Write access never makes the token's own events start new runs. Token hardening in depth is covered in the "Secure and optimize automation" domain.

workflow_run starts a workflow when another workflow, named in workflows, is requested, in_progress or completed. Use it when two workflows must stay separate files — needs only links jobs inside one workflow.

on:
  workflow_run:
    workflows: [CI]
    types: [completed]
    branches: [main]
jobs:
  deploy:
    if: github.event.workflow_run.conclusion == 'success'
    runs-on: ubuntu-latest

• completed fires for every outcome — success, failure, cancelled — so check github.event.workflow_run.conclusion before deploying.
• branches filters on the branch the triggering workflow ran on.
• Chains stop after three levels: with A → B → C → D → E → F, workflows E and F never run, even when everything succeeds. Long pipelines belong in one workflow as jobs connected with needs, or in reusable workflows.
• Which commit it runs on: like schedule and repository_dispatch (but unlike workflow_dispatch, which runs on the ref it was dispatched on), a workflow_run run gets GITHUB_SHA and GITHUB_REF for the latest commit on the default branch, so a plain actions/checkout (and github.sha) gives you the default branch — not the code the triggering run tested. To build or deploy that exact commit, check out github.event.workflow_run.head_sha. head_branch only names the branch, and its tip may have moved on since the triggering run.
• To use files from the triggering run, download its artifacts with its run id (github.event.workflow_run.id) — see the artifacts section below.

- uses: actions/checkout@v4
  with:
    ref: ${{ github.event.workflow_run.head_sha }}

Checking out the triggering commit suits runs that came from your own branches. When the triggering run came from a fork pull request, that commit is untrusted code, so a privileged workflow_run job should only consume its artifacts, never build or run it.

on: workflow_call turns a workflow into a reusable one that a job in another workflow calls with uses:. Data crosses the boundary only through what the called workflow declares.

Inputs

workflow_call inputs accept only three types: boolean, number and string (no choice or environment — validate the value inside the called workflow instead). Each can be required or have a default. The caller passes values with with:. Environment variables set in the caller's env are not propagated to the called workflow, and a calling job cannot set env or runs-on at all — it accepts keys such as with, secrets, needs, if, strategy and permissions. Per-caller values therefore always travel as inputs.

Secrets

A called workflow receives only the secrets its caller passes. The caller either maps them one by one, or uses secrets: inherit to pass all of its secrets implicitly — available when the reusable workflow is in the same organization or enterprise. A secret the called workflow declares as required: true must be supplied by one of these two methods or the call fails.

# caller
jobs:
  deploy:
    uses: acme/platform/.github/workflows/publish.yml@v1
    with:
      channel: beta
    secrets:
      registry_token: ${{ secrets.REGISTRY_TOKEN }}   # or: secrets: inherit

Outputs: three hops out, one hop in

Inside the reusable workflow, a value leaves in three hops — a step writes it to GITHUB_OUTPUT, the job maps it under jobs.<job>.outputs, and on.workflow_call.outputs exposes it with a value that references jobs.<job>.outputs. A workflow-level output cannot reference steps directly, because steps are scoped to a job.

on:
  workflow_call:
    outputs:
      report_url:
        value: ${{ jobs.scan.outputs.url }}
jobs:
  scan:
    runs-on: ubuntu-latest
    outputs:
      url: ${{ steps.upload.outputs.link }}
    steps:
      - id: upload
        run: echo "link=https://reports.example.com/r/88" >> "$GITHUB_OUTPUT"

The caller treats the whole call as one job: a dependent job declares needs: <calling-job> and reads the workflow-level output name from it, here needs.<calling-job>.outputs.report_url. The called workflow's internal job and output names are invisible to the caller.

What you pass and how far it must travel decide the mechanism:

GITHUB_ENV takes effect from the next step. The step that writes the variable cannot read the new value through its own environment — use a shell variable there. Values never reach other jobs; each job runs on its own runner.

- name: Pick channel
  run: |
    ch=nightly
    echo "CHANNEL=$ch" >> "$GITHUB_ENV"
    echo "Using $ch"            # use the shell variable in this step
- run: echo "Publishing to $CHANNEL"  # set from this step on

Across jobs, both halves are required: a step with an id writes to GITHUB_OUTPUT, and the producing job maps it under outputs; the consumer declares needs and reads needs.<job>.outputs.<name>.

Multi-line values use a delimiter, in GITHUB_OUTPUT as in GITHUB_ENV:

- id: notes
  run: |
    {
      echo "body<<EOF"
      cat notes.md
      echo "EOF"
    } >> "$GITHUB_OUTPUT"

The old ::set-output workflow command is deprecated; use the environment files. Workflow commands in general (annotations, masking, grouping) are covered with workflow structure.

Caching and artifacts both store files, but for opposite purposes: a cache reuses files that rarely change — dependencies — between runs to make them faster; an artifact keeps files a run produced — binaries, test reports — so later jobs, other workflows or people can download them.

actions/cache: keys and restore-keys

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-${{ runner.os }}-${{ hashFiles('requirements*.txt') }}
    restore-keys: |
      pip-${{ runner.os }}-

• The action first looks for an exact match on key (output cache-hit is true).
• On a miss, it tries each restore-keys entry as a prefix and restores the most recently created matching cache; cache-hit is false.
• When the primary key missed, the action's post step saves a new cache under that key at the end of the job — by default only when the job succeeds, so a failed job leaves no cache behind. Caches are immutable — an existing entry is never updated, so a changing key (such as a lockfile hash) is how content is refreshed.
• Caches not accessed for 7 days are evicted, and a repository has a total size limit beyond which the oldest caches are removed.

Which caches a run may restore: those created on its own branch and on the default branch; a pull request run can also restore caches from its base branch. Caches from sibling or child branches — including other pull requests — are isolated. Many setup actions (such as actions/setup-python with cache: pip) wrap the same mechanism.

Artifacts with upload-artifact / download-artifact v4

• Files between jobs: upload in the producing job, download in a job that needs it. Job outputs and GITHUB_ENV carry strings, not files, and runner disks do not persist between jobs.
• Names are unique and immutable per run. Several jobs cannot upload into one artifact. In a matrix, put a matrix value in the name (test-results-${{ matrix.os }}). overwrite: true replaces an earlier artifact of the same name — it does not merge.
• retention-days on an upload sets that artifact's lifetime, within the repository's maximum.
• From another run (for example in a workflow_run workflow), download-artifact@v4 needs both run-id — the triggering run's id, github.event.workflow_run.id, not github.run_id — and github-token, a token with actions: read on that repository.

Retention policies through the REST API

Retention decides how long a run's artifacts and logs are kept; the Actions REST API lets you set it once for an organization or a repository and clean up individual objects.

Three tools, three jobs: the retention endpoint changes the policy for future runs, the delete endpoints clean up what already exists, and retention-days on an upload overrides the lifetime of a single artifact. A repository cannot keep data longer than its organization (or enterprise) allows. Finding and downloading artifacts and logs in the UI and API is covered in "Interpret workflow results, artifacts and logs".

A job summary is GitHub-flavored Markdown that a step writes to the file at $GITHUB_STEP_SUMMARY; it appears on the workflow run's summary page, grouped by job, so tables, headings and links are visible without opening logs or downloading anything.

- run: |
    echo "## Test results" >> "$GITHUB_STEP_SUMMARY"
    echo "| Suite | Result |" >> "$GITHUB_STEP_SUMMARY"
    echo "| --- | --- |" >> "$GITHUB_STEP_SUMMARY"
    echo "| api | passed |" >> "$GITHUB_STEP_SUMMARY"

• Each step has its own file. When the step finishes, its summary is uploaded and later steps cannot change it; the job summary shows the step summaries in order.
• >> appends to the current step's summary; > overwrites only the current step's content, never an earlier step's.
• Each step's summary is limited to 1 MiB, and secrets are masked just as in logs.
• Compare: annotations carry short messages, GITHUB_OUTPUT carries data for other steps, artifacts must be downloaded.

Status badges

A status badge is an SVG image showing the latest result of a workflow, addressed by the workflow file name — not its display name:

https://github.com/OWNER/REPO/actions/workflows/deploy.yml/badge.svg
https://github.com/OWNER/REPO/actions/workflows/deploy.yml/badge.svg?branch=main
https://github.com/OWNER/REPO/actions/workflows/deploy.yml/badge.svg?event=push

Without parameters the badge reflects the default branch; branch selects another branch and event limits it to runs from one event type. The Actions tab can generate the Markdown for you. A badge for a private repository is visible only to people who can access the repository, so it cannot be embedded on or linked from an external site.

Environment protections

Environment protections gate deployment jobs. A job opts in with environment: <name>, and the environment's protection rules are evaluated before the job starts:

By default, repository administrators can bypass these rules; the environment setting that disallows administrator bypass makes the rules apply to everyone.

Environment secrets are released only to jobs that reference the environment, and only after its rules pass. A job without environment: gets an empty value and triggers no review; moving the secret to repository level would "work" but bypass the gate. Compare near-twins: branch protection governs merges, not deployments; timeout-minutes cancels long jobs; concurrency allows one run or job in a group at a time (queueing or cancelling the others) but sets no fixed wait.