Principle:Testtimescaling Testtimescaling github io Event Driven Step Progression
| Knowledge Sources | |
|---|---|
| Domains | Education, CI_CD, Event_Driven |
| Last Updated | 2026-02-14 00:00 GMT |
Overview
Event-driven state machine for guided learning progression that automatically detects learner actions and advances course instructions without manual intervention.
Description
After the course environment is bootstrapped (step 0), learners progress through a series of steps by performing specific actions: enabling GitHub Pages, editing configuration files, customizing their homepage, creating a blog post, and merging their pull request. Each of these actions triggers a GitHub event that a corresponding workflow detects.
Every step workflow follows an identical structural pattern:
- Read current step from the flat-file state store (Template:Code)
- Guard execution with a conditional that checks both the step number and the template flag
- Advance the step using Template:Code, which updates the state file and replaces the README with the next set of instructions
This pattern implements a finite state machine where states are integers stored in a file, transitions are triggered by GitHub events, and guard conditions ensure only the correct transition fires at any given time. The result is a self-advancing course that requires no instructor involvement -- the learner simply performs the requested action, and the course detects it and moves forward.
The five step transitions and their event triggers are:
| Step | Workflow | Event | Path Filter | From | To |
|---|---|---|---|---|---|
| 1 | 1-enable-github-pages.yml | Template:Code | -- | 1 | 2 |
| 2 | 2-configure-your-site.yml | Template:Code to my-pages | Template:Code | 2 | 3 |
| 3 | 3-customize-your-homepage.yml | Template:Code to my-pages | Template:Code | 3 | 4 |
| 4 | 4-create-a-blog-post.yml | Template:Code to my-pages | Template:Code | 4 | 5 |
| 5 | 5-merge-your-pull-request.yml | Template:Code to main | -- | 5 | X (finish) |
Usage
Use this principle when:
- Building step-by-step learning experiences on GitHub that automatically detect learner progress and advance instructions
- Designing any workflow that must enforce a strict sequential ordering of actions, where each action unlocks the next
- Implementing event-driven state machines where state is stored in a version-controlled flat file and transitions are triggered by CI/CD events
- The pattern is generic and works for any GitHub Skills course, regardless of the specific learning content
Theoretical Basis
The event-driven step progression pattern implements a deterministic finite automaton (DFA) with the following formal components:
States: The set of integers {1, 2, 3, 4, 5, X} stored in Template:Code. State 0 is handled by the bootstrapping workflow and is not part of this pattern.
Alphabet (input events): GitHub webhook events -- Template:Code, Template:Code with various branch and path filters.
Transition function: Each workflow file defines exactly one transition. The guard condition Template:Code combined with the event trigger determines whether the transition fires.
Initial state: State 1 (set by the bootstrapping workflow).
Accept state: State X (course complete).
The design provides several guarantees:
Idempotency. If a workflow triggers but the step has already advanced past its guard value, the workflow exits without side effects. This handles duplicate events, manual re-triggers, and race conditions.
Template safety. The Template:Code condition prevents workflows from executing in the template repository itself. Only learner repositories (created from the template) run the progression logic.
Linear ordering. Because each workflow checks for exactly one step value, steps cannot be skipped or executed out of order. Step 3 cannot fire until step 2 has completed and advanced the counter to 3.
Separation of concerns. The state machine logic (read step, check guard, advance step) is identical across all five workflows. The only variation is:
- The trigger event type and filters
- The Template:Code and Template:Code values
- The job and step names (cosmetic)
This uniformity makes the pattern highly maintainable. Adding a new step requires only copying an existing workflow file and changing the step numbers and trigger filters.
State persistence. The step counter is stored in a committed file on the default branch, making it durable across workflow runs and visible in the repository history. The Template:Code action handles the read-verify-write-commit cycle atomically.