diff --git a/.github/skills/micro-environment-simulator/simulator.js b/.github/skills/micro-environment-simulator/simulator.js index 1a30c2b..6465ef1 100644 --- a/.github/skills/micro-environment-simulator/simulator.js +++ b/.github/skills/micro-environment-simulator/simulator.js @@ -71,7 +71,9 @@ function defaultEnvironmentForStudent(student, dayOfYear) { sawAgenticIntro: false, hasRepo: false, hasWorkflowFile: false, - ranWorkflow: false + ranWorkflow: false, + environmentReady: false, + agentCredentialsConfigured: false } }); } diff --git a/.github/skills/micro-environment-simulator/workshop-student-journey.js b/.github/skills/micro-environment-simulator/workshop-student-journey.js index d9511aa..220bc16 100644 --- a/.github/skills/micro-environment-simulator/workshop-student-journey.js +++ b/.github/skills/micro-environment-simulator/workshop-student-journey.js @@ -55,12 +55,16 @@ function buildTransitions() { "Create the repository via the GitHub web UI before opening a Codespace." ); if (!repoCheck.ok) return repoCheck; - return ensure( + const terminalCheck = ensure( VALID_TERMINALS[state.os] && VALID_TERMINALS[state.os].has(state.terminal), `Terminal '${state.terminal}' is not valid for OS '${state.os}'`, "terminal-os-mismatch", "Use bash/zsh for macOS/Linux and powershell/cmd for Windows." ); + if (!terminalCheck.ok) return terminalCheck; + const next = cloneState(state); + next.flags.environmentReady = true; + return { ok: true, state: deepFreeze(next) }; }, "04-actions-intro": (state) => { const next = cloneState(state); @@ -81,6 +85,13 @@ function buildTransitions() { return { ok: true, state: deepFreeze(next) }; }, "06-install-gh-aw": (state) => { + const envCheck = ensure( + state.flags.environmentReady, + "gh CLI cannot be installed before a Codespace or local terminal is open", + "environment-not-ready", + "Complete the setup step (02-setup) to open a Codespace or local terminal before installing gh." + ); + if (!envCheck.ok) return envCheck; if (!state.installed.gh) { return ensure( false, @@ -91,6 +102,9 @@ function buildTransitions() { } const next = cloneState(state); next.installed.aw = "latest"; + // In the simulation model, isLoggedIn serves as a proxy for having Copilot-enabled + // credentials. A real-world check would also verify Copilot subscription access. + next.flags.agentCredentialsConfigured = Boolean(state.auth.isLoggedIn); return { ok: true, state: deepFreeze(next) }; }, "07-first-workflow": (state) => { @@ -122,6 +136,14 @@ function buildTransitions() { ); if (!authCheck.ok) return authCheck; + const credCheck = ensure( + state.flags.agentCredentialsConfigured, + "Agent credentials have not been configured", + "agent-credentials-missing", + "Complete the gh-aw install step and ensure gh auth login was run before triggering a workflow run." + ); + if (!credCheck.ok) return credCheck; + const next = cloneState(state); next.flags.ranWorkflow = true; return { ok: true, state: deepFreeze(next) }; diff --git a/.github/workflows/guidelines.md b/.github/workflows/guidelines.md index 7fdab48..33006f2 100644 --- a/.github/workflows/guidelines.md +++ b/.github/workflows/guidelines.md @@ -27,6 +27,11 @@ Use these rules across workshop authoring/editing workflows to keep the tutorial - Keep command-heavy content narrow, purposeful, and optional when possible. - When terminal use is unavoidable, point learners to Codespaces as a low-friction bridge. -## 5) Consistency check +## 5) Step ordering: environment before tools, credentials before running + +- Do not instruct learners to install `gh` or `gh-aw` before a Codespace or local terminal session is open. The install step must always come after the environment setup step (Codespace or local terminal). +- Always configure agent credentials (via `gh auth login` with Copilot access) before guiding learners to trigger a workflow run. Do not place credential setup steps after the run-workflow step. Learners can verify their Copilot access is included in their authentication by running `gh auth status` and confirming the `github.com` token includes the `read:org` scope or that a Copilot subscription is active under their account (covered in [Step 6: Install the gh-aw CLI Extension](../../workshop/06-install-gh-aw.md)). + +## 6) Consistency check Before finalizing workshop edits, quickly confirm that early steps remain UI-first and do not require `gh` before it is truly needed.