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)