GitHub Actions / Events, execution, and data boundaries / Lesson 3

Events, refs, and checkout identity

Know which event created a run and which source revision the job actually reads.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish push, pull_request, dispatch, and schedule contexts.
Explain why a pull-request head differs from a tested merge result.

The event selects a context

A push, pull_request, workflow_dispatch, and schedule do not provide identical event payloads or source-reference semantics. A pull request includes source and target information; a manual dispatch has selected inputs and a ref; a schedule follows documented default-branch behavior and timing constraints. Parcel’s workflow should state which cases it supports before reading event-specific properties. An expression that succeeds for a push can evaluate to empty data for a schedule. Event identity explains why the run exists, not automatically what checkout will produce.

Record immutable identity alongside friendly refs

github.ref is a reference name appropriate to the event; github.sha identifies the event-associated commit under documented event semantics. A checkout action can override repository and ref, so the actual working tree may differ from a casual reading of the trigger. Record the intended test identity and verify the effective checkout contract. A moving branch name is useful context but insufficient release evidence. A rerun of an older event should not silently become a new release of whatever main happens to contain now.

Source-head and merged-state tests differ

For pull_request events, default checkout behavior commonly tests the pull request merge reference rather than only the head commit. This evaluates a proposed combination with the target; a head-only test answers a different question. If the target changes, old combined-state evidence may no longer describe the next merge. Use the platform’s supported merge queue or revalidation policy where appropriate. Never switch to a privileged event merely to obtain secrets for untrusted pull-request builds; that changes the authority boundary as well as the source context.

text Three related identities

proposal head: contributor change by itself
merge result: contributor change combined with a target state
release candidate: identified output from the intended trusted path

These are conceptual categories, not fabricated commit hashes. The repository’s event, checkout inputs, merge policy, and actual run metadata determine the concrete identities.

Read filter combinations carefully

Branch and path filters can constrain event handling, but their exact combination and pattern ordering matter. A pull_request branch filter targets the base branch rather than the contributor’s head branch. Required checks can remain pending when an entire workflow is excluded, depending on the configured protection path. Shared build inputs also affect code outside an edited directory. Design a table of supported events and expected checks, then review exclusions against dependency impact instead of treating filename matching as a complete risk model.

yaml An event declaration fragment

on:
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      fixture:
        description: Synthetic fixture name
        required: true
        type: choice
        options: [parcel-a, parcel-b]

The pull_request filter refers to the target branch. The choice input limits dispatch choices at the interface but is not a production authorization rule. This fragment is not placed in a repository and triggers nothing.

Verify event authority separately

A familiar branch name in a fork does not establish protected-source trust. Actor identity, repository origin, token permissions, environment rules, and organization policies constrain authority independently of the event label. Record these boundaries when designing promotion. Tests for untrusted changes should run without privileged release credentials. A later trusted workflow must treat downloaded reports or artifacts as untrusted data unless their origin and relationship are verified, and must avoid executing arbitrary content merely because a prior run uploaded it.

Common errors and fixes

A pull-request branch filter is expected to match the head branch.

Why it happens: The filter actually applies to the base branch for this event.
How to fix it: Review the documented event-specific filter semantics.
Prevent it next time: Keep example event cases with expected selection results.

A checkout override silently tests another revision.

Why it happens: Trigger metadata was assumed to determine the working tree unconditionally.
How to fix it: Review checkout repository and ref inputs and record the effective identity.
Prevent it next time: Bind evidence to the actual tested source.

A fork branch named main is treated as trusted release source.

Why it happens: A friendly ref name replaced repository-origin and protection checks.
How to fix it: Use verified platform identity and restricted release policy.
Prevent it next time: Separate test eligibility from release authority.

Check your understanding

1. A proposal’s head commit is unchanged but its target branch advances. Is its old merged-result evidence automatically current?

Show worked solution

No. The combined state can change even when the head does not. Revalidate the intended combination according to the repository’s merge policy and retain the tested identities. Head-only and merge-result checks should not be represented as interchangeable.

2. A manual input offers production as a choice. Does choosing it authorize deployment?