Update PAT setup guide

[strawgate]

Deep link to https://github.com/settings/personal-access-tokens/new?name=COPILOT_GITHUB_TOKEN&description=GitHub+Agentic+Workflows+-+Copilot+engine+authentication&user_copilot_requests=read to one click create the right PAT, suggest the user updates the allowed duration to something longer than the 30 day default though

[github-actions]

3 related issues

• Document creating a copilot secret for gh-aw #130 — it added documentation for creating and storing COPILOT_GITHUB_TOKEN, which is the same setup area and provides prior context for documentation wording.
• [docs-new-contributor] New contributor docs review — invalid secret setup command in install guide #303 — it corrected the secret setup command in the install guide for the same token, which is directly relevant to further setup-guide improvements.
• Offer quick setup script #140 — it implemented quick setup automation that creates/sets the same token, which may inform how to present one-click PAT guidance in docs.

---

What is this? | From workflow: Duplicate Issue Detector

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[github-actions]

TL;DR: This is a valid docs gap—docs/workflows/gh-agent-workflows.md should be updated to include a one-click PAT creation link and explicit guidance to choose a longer expiration than the default 30 days, and the docs/script URL parameters should be aligned to avoid confusion.

Recommendation

Update the canonical PAT setup section in docs/workflows/gh-agent-workflows.md (Secrets section) to:

1. Add a deep link for creating COPILOT_GITHUB_TOKEN with prefilled permissions.
2. Add a clear note to change expiration to a longer duration (for example 90 days or 1 year, per team policy).
3. Keep docs/index.md brief, but optionally add one sentence pointing users to the canonical PAT setup section.
4. Reconcile parameter naming/value between issue proposal (user_copilot_requests=read) and current script behavior (copilot_requests=write) before finalizing wording.

Findings

• docs/workflows/gh-agent-workflows.md:128-139 currently documents PAT creation and secret storage, but has no deep-link and no expiration guidance.
• scripts/quick-setup.sh:218 already generates a prefilled PAT URL, but with different query params than requested in this issue:
  • current: ...&copilot_requests=write
  • requested: ...&user_copilot_requests=read
• docs/index.md:80-84 is a summary entry and already points to full setup docs; canonical detailed change should be in docs/workflows/gh-agent-workflows.md.
• Related history:
  • [docs-new-contributor] New contributor docs review — invalid secret setup command in install guide #303 (closed): prior fix in this same docs area for secret setup correctness.
  • Offer quick setup script #140 (closed) and PR Add quick setup script for gh-aw workflows #163: introduced quick setup flow and PAT guidance/script.

Verification

I verified the current state directly from the repo:

$ nl -ba docs/workflows/gh-agent-workflows.md | sed -n '126,140p'
128  These workflows require a Copilot PAT stored as `COPILOT_GITHUB_TOKEN`.
130  1. Create a Copilot PAT with the `copilot-requests` scope ...
133  printf '%s' "(pat)" | gh secret set COPILOT_GITHUB_TOKEN --repo OWNER/REPO

$ nl -ba scripts/quick-setup.sh | sed -n '215,231p'
218  token_url="https://github.com/settings/personal-access-tokens/new?...&copilot_requests=write"
224  echo "A fine-grained PAT with the 'Copilot requests' permission is needed."

$ nl -ba docs/index.md | sed -n '78,85p'
80  1. **Store a Copilot PAT** as `COPILOT_GITHUB_TOKEN` in your repo secrets
84  ... See the [full setup docs](workflows/gh-agent-workflows.md)

Detailed Action Plan

1. Edit docs/workflows/gh-agent-workflows.md Secrets section (~126-140):
   • Add “Create PAT” deep-link line directly under step 1.
   • Add explicit expiration guidance: choose a duration longer than default 30 days.
2. Confirm desired permission query parameter with current behavior:
   • Compare issue request URL vs scripts/quick-setup.sh:218.
   • Decide one canonical URL shape and use it consistently in docs + script.
3. (Optional) Edit docs/index.md (~80-84) with a short pointer like “Use the PAT deep-link in full setup docs.”
4. Run docs checks used by repo CI (if applicable) and verify links render correctly in MkDocs pages.
5. Close this issue once docs + script (if needed) are aligned.

Related Items

Type	Link	Relevance
Issue	#457	Current request
Issue	#303	Prior docs fix in same PAT setup area
Issue	#140	Requested quick setup script + PAT setup flow
PR	#163	Added quick setup script and PAT setup docs references
File	docs/workflows/gh-agent-workflows.md:128-139	Canonical PAT setup section to update
File	scripts/quick-setup.sh:218	Existing PAT deep-link generation
File	docs/index.md:80-84	High-level setup summary pointing to canonical docs

---

What is this? | From workflow: Issue Triage

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.