From a5c83f7860c2d6567c590e3956f474ebb1cfb380 Mon Sep 17 00:00:00 2001 From: serenakeyitan Date: Thu, 23 Apr 2026 14:35:44 -0700 Subject: [PATCH 1/2] docs(onboarding): gate Step 6.2 watch check on `notifications` token scope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #332. `gh api /repos//subscription` returns 404 for every repo when the user's token lacks the `notifications` OAuth scope — which default `gh auth login` does not grant (`admin:org, gist, repo, workflow`). An agent following Step 6.2 on a default token would: 1. Run the check → get 404. 2. Conclude "not watching," tell the user to click Watch. 3. User already is watching, clicks again, refreshes, reruns → still 404. 4. Stuck. Change: - Step 6.2 now checks `gh auth status` for the `notifications` scope first; if missing, instructs the user to run `gh auth refresh -h github.com -s notifications` (interactive) and wait for confirmation. - Pitfalls section gains a bullet explaining the 404-without-scope trap, so agents that skim ahead still catch it. Discovered during v0.2.15 onboarding test. --- skills/first-tree/references/onboarding.md | 25 ++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/skills/first-tree/references/onboarding.md b/skills/first-tree/references/onboarding.md index 3d928f4..b335d2b 100644 --- a/skills/first-tree/references/onboarding.md +++ b/skills/first-tree/references/onboarding.md @@ -214,6 +214,25 @@ answer is missing or ambiguous, stop and re-ask. ### 6.2 Verify Watch Status +First, confirm the user's `gh` token has the `notifications` scope — +without it `/subscription` returns 404 for every repo, whether +watching or not: + +```bash +gh auth status 2>&1 | grep -i 'notifications' +``` + +If the scope is missing, instruct the user to run: + +```bash +gh auth refresh -h github.com -s notifications +``` + +This is interactive and opens a browser for consent. Wait for the +user to confirm before proceeding. + +Once the scope is present, check the subscription: + ```bash gh api /repos//subscription # 200 → watching @@ -356,6 +375,12 @@ ignore them. first-time setup). - Pull-based dispatch silently no-ops without a GitHub watch subscription. Verify before claiming setup is complete. +- `gh api /repos//subscription` returns 404 when the user's + token lacks the `notifications` scope — which default `gh auth + login` does **not** grant. Check `gh auth status` for the scope + first; if missing, run `gh auth refresh -h github.com -s + notifications`. Treat 404 as "not watching" only after the scope + is confirmed present. - `TREE_REPO_TOKEN` must be in the environment for every `gardener` invocation, not just at setup. From 045ad06ab327f13b334f4268fd76366b168d0114 Mon Sep 17 00:00:00 2001 From: serenakeyitan Date: Thu, 23 Apr 2026 14:41:24 -0700 Subject: [PATCH 2/2] docs(onboarding): scope notifications-scope check to active github.com account Addresses review feedback on #333. On gh setups with multiple hosts or multiple stored accounts, a bare `gh auth status | grep notifications` can match a scope on a different host/account than the one `gh api` will actually use, letting the agent skip the refresh and loop back on the same 404. Change both the Step 6.2 check and the Pitfalls bullet to use `gh auth status --active --hostname github.com` so the grep only sees the active github.com account's token scopes. --- skills/first-tree/references/onboarding.md | 26 +++++++++++++--------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/skills/first-tree/references/onboarding.md b/skills/first-tree/references/onboarding.md index b335d2b..b34a580 100644 --- a/skills/first-tree/references/onboarding.md +++ b/skills/first-tree/references/onboarding.md @@ -214,12 +214,15 @@ answer is missing or ambiguous, stop and re-ask. ### 6.2 Verify Watch Status -First, confirm the user's `gh` token has the `notifications` scope — -without it `/subscription` returns 404 for every repo, whether -watching or not: +First, confirm the user's active `github.com` `gh` token has the +`notifications` scope — without it `/subscription` returns 404 for +every repo, whether watching or not. Scope the check to the active +`github.com` account; a bare `gh auth status | grep notifications` +can false-positive on multi-host or multi-account setups where +another stored account has the scope: ```bash -gh auth status 2>&1 | grep -i 'notifications' +gh auth status --active --hostname github.com 2>&1 | grep -i 'notifications' ``` If the scope is missing, instruct the user to run: @@ -375,12 +378,15 @@ ignore them. first-time setup). - Pull-based dispatch silently no-ops without a GitHub watch subscription. Verify before claiming setup is complete. -- `gh api /repos//subscription` returns 404 when the user's - token lacks the `notifications` scope — which default `gh auth - login` does **not** grant. Check `gh auth status` for the scope - first; if missing, run `gh auth refresh -h github.com -s - notifications`. Treat 404 as "not watching" only after the scope - is confirmed present. +- `gh api /repos//subscription` returns 404 when the active + `github.com` token lacks the `notifications` scope — which default + `gh auth login` does **not** grant. Check scope with + `gh auth status --active --hostname github.com 2>&1 | grep -i + notifications` (scope the check to the active account — a bare + `gh auth status` grep can false-positive on multi-host or + multi-account setups). If missing, run + `gh auth refresh -h github.com -s notifications`. Treat 404 as + "not watching" only after the scope is confirmed present. - `TREE_REPO_TOKEN` must be in the environment for every `gardener` invocation, not just at setup.