From 849bca107414a515c1f02e4dff5e57f6e4a0a573 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 10 Sep 2026 13:49:32 +0000 Subject: [PATCH] Extract pre-flight check into optional side quest Move the lock-file/billing pre-flight checklist out of Step 8 (Run and Watch Your Workflow) into a new optional side quest so the main run-workflow path stays focused on triggering and watching a run. - workshop/08-run-your-workflow.md now has a short pre-flight summary with an Optional Side Quest callout - workshop/side-quest-08-02-preflight-check.md holds the full lock-file-and-billing checklist, with a return link back to Step 8 - workshop/README.md lists the new side quest in the optional section Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- workshop/08-run-your-workflow.md | 32 ++++-------- workshop/README.md | 1 + workshop/side-quest-08-02-preflight-check.md | 51 ++++++++++++++++++++ 3 files changed, 61 insertions(+), 23 deletions(-) create mode 100644 workshop/side-quest-08-02-preflight-check.md diff --git a/workshop/08-run-your-workflow.md b/workshop/08-run-your-workflow.md index 206d59e2..2350929a 100644 --- a/workshop/08-run-your-workflow.md +++ b/workshop/08-run-your-workflow.md @@ -16,29 +16,15 @@ You'll trigger the `daily-report-status` workflow from Step 7, watch it start in ## Pre-flight check -A stale or missing [lock file](https://github.github.com/gh-aw/reference/glossary/#workflow-lock-file-lockyml) is the leading cause of `model-access-not-configured` failures at this step. Run these checks before triggering the workflow — each takes less than a minute. - -**Lock file is present and current.** Open `.github/workflows/` in your repository on GitHub and confirm both files are there: - -- `daily-report-status.md` (source) -- `daily-report-status.lock.yml` (compiled lock file) - -If either file is missing, return to [Step 7](07-your-first-workflow.md) to complete the workflow creation steps. If the lock file is present but you are unsure it is current, recompile and push before continuing: - -```bash -gh aw compile -git add . -git commit -m "chore: sync lock file" && git push -``` - -**Billing configuration matches the lock file.** Open `daily-report-status.lock.yml` (or `daily-report-status.md`) and confirm the `permissions:` block matches the billing path you chose in Step 7d: - -| Billing path | `copilot-requests: write` present | -|---|---| -| Organization centralized billing | Yes | -| Personal billing | No — and `COPILOT_GITHUB_TOKEN` is set in **Settings → Secrets → Actions** | - -Any mismatch means returning to [Confirm Model Access](07d-confirm-model-access.md) to fix the configuration and recompile. +A stale or missing [lock file](https://github.github.com/gh-aw/reference/glossary/#workflow-lock-file-lockyml) or a billing mismatch is the leading cause of `model-access-not-configured` failures at this step. Confirm `daily-report-status.md` and `daily-report-status.lock.yml` are both committed on `main` and that the `permissions:` block matches your chosen billing path before you trigger a run. + +> [!TIP] +>
+> Optional Side Quest: Want the full two-minute lock-file-and-billing checklist before your first run? +> +> Work through [Side Quest: Pre-Flight Check Before Your First Run](side-quest-08-02-preflight-check.md), then come back here. +> +>
## Run the workflow diff --git a/workshop/README.md b/workshop/README.md index 0d14b9a6..b5ea9314 100644 --- a/workshop/README.md +++ b/workshop/README.md @@ -56,6 +56,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo - [Install `gh-aw` in a Local Terminal](side-quest-06-04-install-local.md) — optional alternative for learners who completed the local terminal setup side quest and want to continue on their own machine. - [Using `gh aw compile` to Catch Errors Early](side-quest-07-01-compile-workflow.md) — quick reference for `gh aw compile`, `--validate`, `--watch`, and common compile errors; branches from [Step 7](07-your-first-workflow.md) or [Step 9](09-agentic-editing.md). - [Fix Codespaces `actions:write` Errors When Running `gh aw run`](side-quest-08-01-codespaces-actions-write.md) — troubleshooting guide for Codespaces workflow-trigger permission errors with an Actions-tab option and advanced recovery steps; branches from [Step 8](08-run-your-workflow.md). +- [Pre-Flight Check Before Your First Run](side-quest-08-02-preflight-check.md) — two-minute checklist for confirming your lock file is current and your billing configuration matches before triggering your first run; branches from [Step 8](08-run-your-workflow.md). - [Diagnosing Common Agent Output Patterns](side-quest-09-01-debug-output.md) — expanded troubleshooting guide for the five most common log patterns; branches from [Step 9](08b-interpret-your-run.md). - [Pattern: Long `[plan]` Chains](side-quest-09-01a-pattern-long-plan-chain.md) — how to spot a planning loop and rewrite your workflow brief so the agent starts with an explicit first tool call; branches from [Diagnosing Common Agent Output Patterns](side-quest-09-01-debug-output.md). - [Pattern: Empty `[result]` Data](side-quest-09-01b-pattern-empty-results.md) — how to diagnose empty tool responses and decide whether the root cause is missing read scope, over-filtering, or truly empty repository data; branches from [Diagnosing Common Agent Output Patterns](side-quest-09-01-debug-output.md). diff --git a/workshop/side-quest-08-02-preflight-check.md b/workshop/side-quest-08-02-preflight-check.md new file mode 100644 index 00000000..9f8ba90b --- /dev/null +++ b/workshop/side-quest-08-02-preflight-check.md @@ -0,0 +1,51 @@ + + +# Side Quest: Pre-Flight Check Before Your First Run + +> _A stale lock file or a billing mismatch is the leading cause of failed first runs — catch both in under two minutes._ + +## :dart: What You'll Do + +You'll verify that your `daily-report-status` workflow's compiled lock file is present and current, and that its `permissions:` block matches the billing path you configured in [Confirm Model Access](07d-confirm-model-access.md). By the end, you'll know exactly what to check whenever a run fails with a `model-access-not-configured` error. + +## :clipboard: Before You Start + +- Completed [Confirm Model Access](07d-confirm-model-access.md) +- `daily-report-status.md` exists in `.github/workflows/` on `main` + +## Steps + +### Confirm the lock file is present and current + +Open `.github/workflows/` in your repository on GitHub and confirm both files are there: + +- `daily-report-status.md` (source) +- `daily-report-status.lock.yml` (compiled lock file) + +If either file is missing, return to [Step 7](07-your-first-workflow.md) to complete the workflow creation steps. If the lock file is present but you are unsure it is current, recompile and push before continuing: + +```bash +gh aw compile +git add . +git commit -m "chore: sync lock file" && git push +``` + +### Confirm billing configuration matches the lock file + +Open `daily-report-status.lock.yml` (or `daily-report-status.md`) and confirm the `permissions:` block matches the billing path you chose in Step 7d: + +| Billing path | `copilot-requests: write` present | +|---|---| +| Organization centralized billing | Yes | +| Personal billing | No — and `COPILOT_GITHUB_TOKEN` is set in **Settings → Secrets → Actions** | + +Any mismatch means returning to [Confirm Model Access](07d-confirm-model-access.md) to fix the configuration and recompile. + +## :white_check_mark: Checkpoint + +- [ ] I confirmed `daily-report-status.md` and `daily-report-status.lock.yml` are both present in `.github/workflows/` on `main` +- [ ] I recompiled and pushed if the lock file was stale +- [ ] I confirmed the `permissions:` block matches my chosen billing path +- [ ] I know where to return if the lock file or billing configuration needs fixing + +**Return to the main adventure:** [Run and Watch Your Workflow](08-run-your-workflow.md)