From feea8eb7425f042706fe2a9f961d8f8d1844f233 Mon Sep 17 00:00:00 2001 From: bgagent <345885+scottschreckengaust@users.noreply.github.com> Date: Thu, 21 May 2026 02:31:16 +0000 Subject: [PATCH] docs: add classic PAT guidance for collaborator/cross-org repos Fine-grained PATs cannot target repos the user doesn't own (or orgs that haven't opted in). Document the classic PAT alternative with repo + read:org scopes, add a "when to use which" decision table to agent/README.md, and fix the dead "edge cases" reference in the Developer Guide. Co-Authored-By: Claude Opus 4.6 (1M context) --- agent/README.md | 30 +++++++++++++++++-- docs/guides/DEVELOPER_GUIDE.md | 2 +- docs/guides/QUICK_START.md | 2 ++ .../developer-guide/Repository-preparation.md | 2 +- .../docs/getting-started/Quick-start.md | 2 ++ 5 files changed, 34 insertions(+), 4 deletions(-) diff --git a/agent/README.md b/agent/README.md index dfa71f43..1964d449 100644 --- a/agent/README.md +++ b/agent/README.md @@ -15,7 +15,11 @@ The Docker image is built for `linux/arm64` to match AgentCore Runtime requireme ### GitHub PAT — Minimal Permissions -Create a **fine-grained PAT** at GitHub > Settings > Developer settings > Personal access tokens > Fine-grained tokens. +Two token types work. Choose based on your access model: + +#### Fine-grained PAT (recommended for repos you own) + +Go to GitHub > **Settings** > **Developer settings** > **Fine-grained tokens**. **Repository access**: Select only the specific repo(s) the agent will work on. @@ -26,7 +30,29 @@ Create a **fine-grained PAT** at GitHub > Settings > Developer settings > Person | **Issues** | Read | Fetch issue title, body, and comments for context | | **Metadata** | Read | Granted by default | -No other permissions are needed. +**Limitation:** Fine-grained PATs can only target repos you own or repos in organizations that have opted in to fine-grained token access. If you are a collaborator on someone else's repo (or an org that hasn't enabled the feature), the repo won't appear in the token creation UI. + +#### Classic PAT (required for collaborator/cross-org access) + +Use a classic PAT when fine-grained tokens cannot reach the target repository — typically when you are a collaborator on a repo owned by another user or an organization that has not enabled fine-grained token access. + +Go to GitHub > **Settings** > **Developer settings** > **Personal access tokens** > **Tokens (classic)**. + +| Scope | Reason | +|-------|--------| +| `repo` | Full repository access (clone, push, PRs, issues) | +| `read:org` | Resolve org membership for org-owned repos | + +Set an expiration (90 days recommended) and store it in Secrets Manager the same way as a fine-grained token. + +#### When to use which + +| Scenario | Token type | +|----------|-----------| +| Your own repos or your org has fine-grained enabled | Fine-grained | +| Collaborator on another user's repo | Classic | +| Org has not opted in to fine-grained tokens | Classic | +| Targeting repos across multiple orgs | Classic (single token covers all) | ### AWS Credentials diff --git a/docs/guides/DEVELOPER_GUIDE.md b/docs/guides/DEVELOPER_GUIDE.md index 31bdae1e..8f8e32f3 100644 --- a/docs/guides/DEVELOPER_GUIDE.md +++ b/docs/guides/DEVELOPER_GUIDE.md @@ -41,7 +41,7 @@ Permission requirements vary by task type: - `new_task` and `pr_iteration` require Contents (read/write) and Pull requests (read/write). - `pr_review` only needs Triage or higher since it does not push branches. -Classic PATs with `repo` scope also work. See `agent/README.md` for edge cases. +Classic PATs with `repo` + `read:org` scopes also work and are required when fine-grained tokens cannot reach the target repo (collaborator access, cross-org repos). See [agent/README.md](../../agent/README.md#github-pat--minimal-permissions) for when to use which token type. ### Quick setup (single repo) diff --git a/docs/guides/QUICK_START.md b/docs/guides/QUICK_START.md index 7259b0ff..3d91df13 100644 --- a/docs/guides/QUICK_START.md +++ b/docs/guides/QUICK_START.md @@ -57,6 +57,8 @@ The agent authenticates to GitHub using a **fine-grained personal access token ( Keep the token value - you will store it in AWS Secrets Manager after deploying. +> **Collaborator or cross-org repos?** Fine-grained tokens only work for repos you own (or orgs that have opted in). If you're a collaborator on someone else's repo, create a **classic PAT** with `repo` + `read:org` scopes instead. See [agent/README.md](../../agent/README.md#github-pat--minimal-permissions) for details. + ### Register the repo in CDK Every repository the agent can work on must be **onboarded** as a `Blueprint` construct in the CDK stack. The Blueprint writes a configuration record to DynamoDB; the orchestrator checks this before accepting tasks. diff --git a/docs/src/content/docs/developer-guide/Repository-preparation.md b/docs/src/content/docs/developer-guide/Repository-preparation.md index ed9f56d3..5aeedf0f 100644 --- a/docs/src/content/docs/developer-guide/Repository-preparation.md +++ b/docs/src/content/docs/developer-guide/Repository-preparation.md @@ -13,7 +13,7 @@ Permission requirements vary by task type: - `new_task` and `pr_iteration` require Contents (read/write) and Pull requests (read/write). - `pr_review` only needs Triage or higher since it does not push branches. -Classic PATs with `repo` scope also work. See `agent/README.md` for edge cases. +Classic PATs with `repo` + `read:org` scopes also work and are required when fine-grained tokens cannot reach the target repo (collaborator access, cross-org repos). See [agent/README.md](/architecture/readme#github-pat--minimal-permissions) for when to use which token type. ### Quick setup (single repo) diff --git a/docs/src/content/docs/getting-started/Quick-start.md b/docs/src/content/docs/getting-started/Quick-start.md index 39deecb7..8d74523d 100644 --- a/docs/src/content/docs/getting-started/Quick-start.md +++ b/docs/src/content/docs/getting-started/Quick-start.md @@ -61,6 +61,8 @@ The agent authenticates to GitHub using a **fine-grained personal access token ( Keep the token value - you will store it in AWS Secrets Manager after deploying. +> **Collaborator or cross-org repos?** Fine-grained tokens only work for repos you own (or orgs that have opted in). If you're a collaborator on someone else's repo, create a **classic PAT** with `repo` + `read:org` scopes instead. See [agent/README.md](/architecture/readme#github-pat--minimal-permissions) for details. + ### Register the repo in CDK Every repository the agent can work on must be **onboarded** as a `Blueprint` construct in the CDK stack. The Blueprint writes a configuration record to DynamoDB; the orchestrator checks this before accepting tasks.