From 2a2047bbfbbbd5fcd4ddf661f63da0cf4e63fbc5 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Sun, 22 Mar 2026 00:19:55 -0700 Subject: [PATCH] docs: restore GitHub auth setup documentation (#488) Add guide covering gh CLI authentication for project board management, multi-account switching, required scopes, and common pitfalls. Closes #488 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/guide/github-auth-setup.md | 190 ++++++++++++++++++ test/docs-build.test.ts | 2 +- 2 files changed, 191 insertions(+), 1 deletion(-) create mode 100644 docs/src/content/docs/guide/github-auth-setup.md diff --git a/docs/src/content/docs/guide/github-auth-setup.md b/docs/src/content/docs/guide/github-auth-setup.md new file mode 100644 index 000000000..06391b942 --- /dev/null +++ b/docs/src/content/docs/guide/github-auth-setup.md @@ -0,0 +1,190 @@ +# GitHub auth setup for project boards + +**Try this to verify your auth setup:** +``` +gh auth status +``` + +**Try this to switch accounts before working with project boards:** +``` +gh auth switch --user YOUR_USERNAME +``` + +You need an authenticated GitHub CLI to manage project boards with Squad. This guide covers login, required scopes, multi-account switching, and common pitfalls. + +--- + +## Log in with `gh auth login` + +If you haven't authenticated yet, run: + +```bash +gh auth login +``` + +Follow the interactive prompts. When asked about scopes, request the ones Squad needs for project board management (see the next section). + +To add scopes to an existing session: + +```bash +gh auth refresh -s repo,read:org,workflow,delete_repo,gist +``` + +--- + +## Required scopes + +Project board management requires specific token scopes. Without them, `gh project` commands fail silently or return permission errors. + +| Scope | Why you need it | +|-------|----------------| +| `repo` | Read and write access to repositories and their linked project boards | +| `read:org` | Read organization membership — required to access org-level project boards | +| `workflow` | Trigger and manage GitHub Actions workflows from Squad agents | +| `delete_repo` | Allow Squad to clean up temporary repos during testing (optional but recommended) | +| `gist` | Create gists for sharing logs and snippets (optional but recommended) | + +### Verify your scopes + +```bash +gh auth status +``` + +Look for the `Token scopes` line in the output: + +``` +github.com + ✓ Logged in to github.com account your-username (keyring) + - Active account: true + - Git operations protocol: https + - Token: gho_**** + - Token scopes: 'delete_repo', 'gist', 'read:org', 'repo', 'workflow' +``` + +If scopes are missing, refresh your token: + +```bash +gh auth refresh -s repo,read:org,workflow +``` + +--- + +## Switch between multiple accounts + +If you have both a personal GitHub account and an Enterprise Managed User (EMU) account, the `gh` CLI lets you authenticate with both and switch between them. + +### Log in with both accounts + +```bash +# Personal account +gh auth login + +# EMU account (same hostname or dedicated instance) +gh auth login --hostname github.com +``` + +### Switch to the account you need + +```bash +# Interactive picker +gh auth switch + +# Direct switch by username +gh auth switch --user your-personal-username +``` + +### Verify the active account + +Always verify after switching — especially before project board operations: + +```bash +gh auth status +``` + +Confirm the account marked **Active account: true** is the one you want. + +--- + +## Common pitfalls + +### EMU account reactivates between commands + +**Problem:** You switch to your personal account with `gh auth switch`, but subsequent commands run under your EMU account. + +**Why it happens:** Some credential managers and enterprise policies can reactivate the EMU account. Background processes or IDE extensions may also trigger re-authentication with the work account. + +**Fix:** Always verify with `gh auth status` immediately before running `gh project` or `gh pr` commands. If the wrong account is active, switch again: + +```bash +gh auth status +# If wrong account is active: +gh auth switch --user your-personal-username +gh auth status # Verify the switch stuck +``` + +### Token scope errors on project boards + +**Problem:** `gh project` commands return permission errors even though you're logged in. + +**Why it happens:** Your token was created without the `read:org` or `project` scopes that project board access requires. + +**Fix:** Refresh your token with the required scopes: + +```bash +gh auth refresh -s repo,read:org +``` + +### Wrong account creates issues or PRs + +**Problem:** Issues or PRs appear under your EMU username instead of your personal account. + +**Why it happens:** The active `gh` account changed between when you started work and when the PR was created. + +**Fix:** Check `gh auth status` before every `gh pr create` or `gh issue create` command. Add a verification step to your workflow: + +```bash +# Verify, then create +gh auth status +gh pr create --repo your-org/your-repo --base main --title "Your PR" +``` + +### `gh project` commands return "not found" + +**Problem:** You run `gh project list` or `gh project view` and get a "not found" error. + +**Why it happens:** The active account doesn't have access to the organization that owns the project board, or the `read:org` scope is missing. + +**Fix:** +1. Verify you're on the right account: `gh auth status` +2. Verify your scopes include `read:org`: look at the `Token scopes` line +3. If the scope is missing: `gh auth refresh -s read:org` + +--- + +## Quick verification checklist + +Run these commands before starting a Squad session that involves project boards: + +```bash +# 1. Check which account is active +gh auth status + +# 2. Switch if needed +gh auth switch --user your-username + +# 3. Verify scopes include repo and read:org +gh auth status | grep "Token scopes" + +# 4. Test project board access +gh project list --owner YOUR_ORG +``` + +If all four steps succeed, you're ready to manage project boards with Squad. + +--- + +## See also + +- [Cross-organization authentication](../scenarios/cross-org-auth) — multi-account auth patterns for Squad agents +- [Troubleshooting](../scenarios/troubleshooting) — common Squad issues and fixes +- [Private repos](../scenarios/private-repos) — privacy and security for enterprise repos diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts index 352c85145..7355e85c0 100644 --- a/test/docs-build.test.ts +++ b/test/docs-build.test.ts @@ -17,7 +17,7 @@ const DIST_DIR = join(DOCS_DIR, 'dist'); // Expected content directories in src/content/docs/ const EXPECTED_GET_STARTED = ['choose-your-interface', 'first-session', 'installation', 'migration']; -const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell', 'faq', 'extensibility', 'building-extensions']; +const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell', 'faq', 'extensibility', 'building-extensions', 'github-auth-setup']; const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks', 'glossary'];