Checkpoint Lab — Events, Triggers, Filters, Schedules, Manual Runs, and Repository Dispatch

1. Checkpoint scope and authorization

2. Final checkpoint workflow

name: Chapter 03 checkpoint

on:
  push:
    branches:
      - main
      - 'feature/**'
    paths:
      - 'app/**'
      - '.github/workflows/ch03-checkpoint.yml'
  pull_request:
    branches:
      - main
    paths:
      - 'app/**'
      - '.github/workflows/ch03-checkpoint.yml'
  workflow_dispatch:
    inputs:
      scenario:
        description: 'Synthetic scenario label'
        type: choice
        required: true
        options: [smoke, regression]
      dry_run:
        description: 'No external side effects'
        type: boolean
        required: true
        default: true
  repository_dispatch:
    types: [academy_probe]
  schedule:
    - cron: '23 4 * * 1-5'
      timezone: 'Etc/UTC'

permissions: {}

defaults:
  run:
    shell: bash

jobs:
  inspect:
    runs-on: ubuntu-24.04
    env:
      EVENT_NAME: ${{ github.event_name }}
      EVENT_ACTION: ${{ github.event.action }}
      ACTOR: ${{ github.actor }}
      REF: ${{ github.ref }}
      SHA: ${{ github.sha }}
      BASE_REF: ${{ github.base_ref }}
      HEAD_REF: ${{ github.head_ref }}
      PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
      MANUAL_SCENARIO: ${{ inputs.scenario }}
      MANUAL_DRY_RUN: ${{ inputs.dry_run }}
      DISPATCH_SOURCE: ${{ github.event.client_payload.source }}
      DISPATCH_DRY_RUN: ${{ github.event.client_payload.dry_run }}
      SCHEDULE_EXPR: ${{ github.event.schedule }}
    steps:
      - name: Record bounded trigger evidence
        run: |
          printf 'event=%s action=%s actor=%s\n' "$EVENT_NAME" "$EVENT_ACTION" "$ACTOR"
          printf 'ref=%s sha=%s\n' "$REF" "$SHA"
          printf 'base=%s head=%s pr_head_sha=%s\n' "$BASE_REF" "$HEAD_REF" "$PR_HEAD_SHA"
          printf 'manual_scenario=%s manual_dry_run=%s\n' "$MANUAL_SCENARIO" "$MANUAL_DRY_RUN"
          printf 'dispatch_source=%s dispatch_dry_run=%s\n' "$DISPATCH_SOURCE" "$DISPATCH_DRY_RUN"
          printf 'schedule=%s\n' "$SCHEDULE_EXPR"
          printf 'run=%s attempt=%s\n' "$GITHUB_RUN_ID" "$GITHUB_RUN_ATTEMPT"

3. Prediction matrix — complete before execution

4. Execute T1–T4 in controlled order

1. T1: commit docs-only change on feature/probe. Record commit SHA and prove no new checkpoint run exists.
2. T2: commit app/message.txt. Record run ID/attempt/ref/SHA and job conclusion.
3. T3: open/update PR targeting main. Record merge ref/SHA plus PR_HEAD_SHA; explain why they differ.
4. Merge workflow definition to main before T4/T5. This satisfies current dispatch default-branch presence rules.
5. T4: manually dispatch with smoke/true; record selected ref, input values, run ID/attempt.

Do not combine T1 and T2 in one commit. The checkpoint is designed to isolate path filtering as the only material variable.

5. Execute optional authenticated T5 safely

Confirm the target before making the request:

export GH_REPO='OWNER/chapter03-trigger-lab'
printf 'dispatch target=%s\n' "$GH_REPO"
gh repo view "$GH_REPO" --json nameWithOwner,defaultBranchRef

Then create the custom event:

gh api --method POST "repos/$GH_REPO/dispatches" \
  -f event_type='academy_probe' \
  -f 'client_payload[source]=chapter03-checkpoint' \
  -F 'client_payload[dry_run]=true'

Record the API success response/status, resulting run ID, event name, payload fields, default-branch ref, and SHA. If your environment has no authenticated GitHub CLI, document T5 as a faithful request/response simulation instead; the chapter remains complete without exposing a token.

6. T6 schedule verification without waiting

Verify the workflow on main, record the exact cron/timezone, and predict that a scheduled run uses the latest default-branch commit. Record the limitation that current GitHub schedules may be delayed and are not a hard real-time guarantee. If a naturally occurring scheduled run happens during the lab window, capture its actual start timestamp and compare it with the configured schedule; otherwise do not manufacture a run.

7. Reconciliation table

8. Required evidence packet

• Repository name/default branch and checkpoint workflow path/hash.
• Prediction matrix completed before execution.
• For every created run: event name/action, actor, ref/SHA, workflow ref, run ID/attempt, runner label, final job conclusion.
• For T3: base/head refs, PR merge SHA, PR head SHA, explanation of intended CI question.
• For T4: input definitions and actual typed input values.
• For T5: event type, synthetic payload, API status or simulation note, default-branch ref/SHA.
• For T1: negative evidence proving a matching branch with a nonmatching path created no run.
• For T6: cron/timezone, default-branch rule, five-minute minimum, schedule-delay limitation.
• Assumptions/limitations: no secrets, artifacts, caches, environment approvals, OIDC, cloud deployment, self-hosted runner, or third-party action.

9. Verification checklist

• Chapter 03 workflow exists on default branch before manual/custom dispatch testing.
• Both branch and path filters are interpreted with AND semantics.
• PR evidence distinguishes merge SHA from head SHA.
• No whole-context dump or direct untrusted expression interpolation appears.
• permissions: {} is sufficient because the workflow only reads context/environment and writes logs.
• Repository dispatch targets only the explicitly named disposable repository.
• Schedule is documented as approximate and default-branch based.
• Negative “no run” evidence is retained rather than hidden.

10. Cleanup / rollback

1. Close the disposable PR if it remains open.
2. Keep run IDs/attempts and the checkpoint packet until review is complete.
3. Delete only the learner-owned disposable branch/repository if no longer needed.
4. Do not delete surprising runs merely to produce an all-green history.
5. No cloud, registry, package, runner registration, or production resource rollback is required.

11. What Chapter 03 adds to the operating model

Chapter 03 adds the trigger contract: event identity/activity, branch/path/type filters, event-specific ref/SHA semantics, workflow revision selection, default-branch eligibility rules, manual/custom dispatch input contracts, schedule assumptions, and explicit differentiation between “no run,” “run with skipped job,” and “run with failed job.”

Chapter 04 builds directly on this: once a run exists, contexts and expressions determine conditional behavior and data selection inside that run.

Knowledge check

Official references and version notes

• Events that trigger workflows — authoritative event-specific ref/SHA, default-branch, activity-type, schedule, and dispatch semantics.
• Triggering a workflow — branch/path filters, manual inputs, event configuration, and trigger examples.
• Workflow syntax for GitHub Actions — current on syntax, filter combination rules, schedule syntax, and manual input types.
• Contexts reference — current github context fields and safe access patterns.
• Variables reference — current meanings of GITHUB_REF, GITHUB_SHA, event path, and run identity variables.
• Troubleshooting workflows — current guidance for trigger conditions, default-branch requirements, merge-conflict behavior, and schedule delays.
• Manually running a workflow — current manual dispatch requirements and CLI examples.
• REST API endpoints for repositories — repository dispatch API contract and authorization model.
• GITHUB_TOKEN concepts — event recursion behavior relevant to trigger chains.