fix: support fine-grained tokens in pr-review scope validation by don-petry · Pull Request #442 · petry-projects/.github-private

don-petry · 2026-06-06T13:45:16Z

Summary

Fix auth scope validation to support fine-grained GitHub tokens alongside classic PATs.

Problem

PR #353 added strict auth scope validation requiring the repo scope (full repository control), which breaks workflows using fine-grained tokens with minimal permissions.

Solution

Updated validation to accept either classic PAT (repo scope) or fine-grained tokens (contents:read + pull_requests:write)
Document required scopes for both token types
Recommend fine-grained tokens for better security (principle of least privilege)

Changes

.github/workflows/pr-review.yml: Flexible scope validation with clear error messages
agents/pr-reviewer.md: Add required scopes documentation
docs/pr-review-agent/pr-review-agent.md: Update setup guide with both token options

Closes #435

🤖 Generated with Claude Code

The Lint workflow (added in #424) flags trailing-spaces in deploy-pr-review.yml and force-deploy-pr-review.yml. These blank-line trailing spaces predate the Lint check and now fail it on every PR (observed blocking #435). Strip them so the YAML lint passes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The auth scope check was overly strict, requiring 'repo' scope (full repo control) even though the PR review agent only needs read/write access to specific resources. Changes: - Modify scope validation to accept either classic PAT (repo scope) or fine-grained tokens (contents:read + pull_requests:write) - Document required scopes in pr-reviewer.md with fine-grained token requirements - Update pr-review-agent.md setup guide to recommend fine-grained tokens over classic PATs for better security (principle of least privilege) - Support both token types for backward compatibility This fixes PR #435 auth failure while improving security posture. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

coderabbitai · 2026-06-06T13:45:22Z

Warning

Review limit reached

@don-petry, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 1 minute and 55 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 51a00169-7f6c-4575-9a33-a77983e918fc

📥 Commits

Reviewing files that changed from the base of the PR and between 5f8ad45 and 6d83d24.

📒 Files selected for processing (5)

.github/workflows/deploy-pr-review.yml
.github/workflows/force-deploy-pr-review.yml
.github/workflows/pr-review.yml
agents/pr-reviewer.md
docs/pr-review-agent/pr-review-agent.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/yaml-trailing-whitespace-deploy-workflows

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

don-petry · 2026-06-06T13:46:12Z

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

Issues addressed: 0
Files changed: none
Skipped (informational): 1
- Rate limit notification: The bot was unable to complete a review due to hitting the hourly PR review rate limit and exhausted organization usage credits. No code issues were identified — the comment contains no actionable findings.
```
The bot comment is purely a rate limit/billing notification. CodeRabbit never ran its analysis, so there are no code issues to fix. CI checks and review states are both empty (no Tier 1 blockers). No action is required.

gemini-code-assist

Code Review

This pull request updates the documentation and agent configuration to support and recommend fine-grained GitHub Personal Access Tokens (PATs) alongside classic PATs, detailing the specific minimum permissions required. The review feedback correctly points out that the documented contents:read permission is insufficient because the agent requires write access (contents:write) to perform branch rebases.

gemini-code-assist · 2026-06-06T13:46:15Z

+The agent requires a GitHub personal access token (PAT) with these minimum permissions:
+
+**Repository permissions:**
+- `contents:read` — read file contents and diffs


Since the agent is configured to rebase branches that are behind their base branch, it requires write access to the repository contents. Using contents:read will cause the rebase push to fail. Please update this permission to contents:write (read file contents, diffs, and push rebase commits).

gemini-code-assist · 2026-06-06T13:46:15Z

+   - **Resource owner:** select your organization (e.g. `petry-projects`)
+   - **Repository access:** All repositories (or specific repos if preferred)
+   - **Repository permissions:**
+     - `contents:read` — read files and diffs


Since the agent rebases branches when they are behind the base branch, it requires write access to the repository contents. contents:read is insufficient for pushing the rebased commits back to the branch. Please update this permission to contents:write (read files/diffs and push rebase commits).

don-petry · 2026-06-06T13:46:40Z

Closed in favor of PR #443 (rebased on main)

Copilot

Pull request overview

Updates the PR-review agent workflow and docs to allow fine-grained GitHub PATs (in addition to classic PATs) to be used for authentication in pr-review.yml, aiming to reduce required privileges while keeping scope validation diagnosable.

Changes:

Adjusts the Verify auth scopes logic in .github/workflows/pr-review.yml to accept multiple token types.
Documents fine-grained vs classic PAT setup requirements in docs/pr-review-agent/pr-review-agent.md.
Adds token permission guidance to the agents/pr-reviewer.md agent profile.

Reviewed changes

Copilot reviewed 3 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`.github/workflows/pr-review.yml`	Modifies the early auth/scope validation logic to support fine-grained tokens.
`docs/pr-review-agent/pr-review-agent.md`	Updates setup instructions to include fine-grained PAT option and required permissions.
`agents/pr-reviewer.md`	Adds a “required token” section for the PR reviewer agent profile.
`.github/workflows/force-deploy-pr-review.yml`	Whitespace-only formatting changes.
`.github/workflows/deploy-pr-review.yml`	Whitespace-only formatting changes.

          scopes_line="$(printf '%s\n' "$auth_status" | grep 'Token scopes:' || true)"
          normalized_scopes="$(printf '%s' "$scopes_line" | sed "s/[',]/ /g")"
-          required_scopes=(repo read:org)
-          for required_scope in "${required_scopes[@]}"; do
-            if ! grep -qE "(^|[[:space:]])${required_scope}([[:space:]]|$)" <<< "$normalized_scopes"; then
-              echo "::error::GH_TOKEN is missing required scope: ${required_scope}"
-              exit 1
-            fi
-          done
+
+          # Check for required scopes. Accept either:
+          # - Classic PAT: 'repo' scope (grants full repo access)


+After saving either token type, trigger a workflow run and confirm the
+`gh auth status` output reports the bot's login (not yours) and lists the
+required scopes.


-   - **Expiration:** 1 year (set a calendar reminder to rotate)
-   - **Scopes:** ✅ `repo`, ✅ `workflow`, ✅ `read:org`
+   - **Token name:** `pr-review-agent`
+   - **Expiration:** 90 days (auto-rotate for security)



 You are the PR Review Agent for the petry-projects organization.

+## Required GitHub token scopes


+**Organization permissions:**
+- `members:read` — read organization members for code owner routing
+
+These are fine-grained token scopes. The legacy `repo` scope (which grants full repository control) is NOT required.


chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6d83d24362

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-06-06T13:50:02Z

+            for required_scope in contents pull_requests; do
+              if ! grep -qE "(^|[[:space:]])${required_scope}([[:space:]]|$)" <<< "$normalized_scopes"; then


Don’t validate fine-grained PATs as OAuth scopes

For runs using the newly recommended fine-grained PAT, this loop still looks for contents and pull_requests in the Token scopes: line from gh auth status. GitHub distinguishes fine-grained PAT permissions from classic PAT OAuth scopes, and gh auth status surfaces OAuth scopes from the token headers, so a valid fine-grained token with Contents read and Pull requests write can still have no literal contents/pull_requests scopes and fail here before any review starts. Probe the required endpoints/permissions instead, or only scope-check classic PATs.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-06-06T13:50:02Z

+   - **Resource owner:** select your organization (e.g. `petry-projects`)
+   - **Repository access:** All repositories (or specific repos if preferred)
+   - **Repository permissions:**
+     - `contents:read` — read files and diffs


Grant contents write for auto-merge

When someone follows the new recommended fine-grained PAT setup, approvals can be posted but auto-merge will not be enabled because scripts/post-pr-review.sh later runs gh pr merge "$PR_URL" --auto --squash, and GitHub requires the fine-grained token to have Contents write for PR merges. With only contents:read, that command is swallowed by || true, so the log can still say the review was posted and auto-merge enabled while the approved PR remains unmerged.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-06-06T13:50:02Z

+   (org-level secret or repo secret on `.github`). Use the same PAT created above
+   in [step 2](#2-create-a-pat-for-the-bot-classic-or-fine-grained).


Don’t reuse the read-only PAT for mention dispatch

For mention-triggered reviews, this now tells operators to put the same fine-grained PAT into petry-projects/.github, but that recommended token only has contents:read. The mention listener dispatches to .github-private via POST /repos/.../dispatches, and GitHub documents that creating a repository dispatch event with a fine-grained token requires Contents write, so @donpetry-bot mentions configured this way will acknowledge/resolve the PR but fail to start the review run.

Useful? React with 👍 / 👎.

donpetry-bot and others added 2 commits June 6, 2026 07:46

Copilot AI review requested due to automatic review settings June 6, 2026 13:45

Copilot started reviewing on behalf of don-petry June 6, 2026 13:45 View session

gemini-code-assist Bot reviewed Jun 6, 2026

View reviewed changes

don-petry closed this Jun 6, 2026

Copilot AI reviewed Jun 6, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed Jun 6, 2026

View reviewed changes

github-actions Bot mentioned this pull request Jun 20, 2026

petry-projects — workflow failures detected 2026-06-20 #831

Closed

github-actions Bot mentioned this pull request May 31, 2026

petry-projects — workflow failures detected 2026-05-31 #415

Closed

This was referenced Aug 5, 2026

petry-projects — workflow failures detected 2026-08-05 #1464

Closed

petry-projects — workflow failures detected 2026-08-07 #1471

Closed

Navigation Menu

Uh oh!

fix: support fine-grained tokens in pr-review scope validation - #442

fix: support fine-grained tokens in pr-review scope validation#442
don-petry wants to merge 2 commits into
mainfrom
fix/yaml-trailing-whitespace-deploy-workflows

don-petry commented Jun 6, 2026

Uh oh!

coderabbitai Bot commented Jun 6, 2026

Review limit reached

Uh oh!

don-petry commented Jun 6, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Jun 6, 2026

Uh oh!

gemini-code-assist Bot Jun 6, 2026

Uh oh!

don-petry commented Jun 6, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jun 6, 2026

Uh oh!

chatgpt-codex-connector Bot Jun 6, 2026

Uh oh!

chatgpt-codex-connector Bot Jun 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		You are the PR Review Agent for the petry-projects organization.

		## Required GitHub token scopes

		for required_scope in contents pull_requests; do
		if ! grep -qE "(^\|[[:space:]])${required_scope}([[:space:]]\|$)" <<< "$normalized_scopes"; then

		(org-level secret or repo secret on `.github`). Use the same PAT created above
		in [step 2](#2-create-a-pat-for-the-bot-classic-or-fine-grained).

Uh oh!

Conversation

don-petry commented Jun 6, 2026

Summary

Problem

Solution

Changes

Uh oh!

coderabbitai Bot commented Jun 6, 2026

Review limit reached

Uh oh!

don-petry commented Jun 6, 2026

Dev-Lead — fix-bot-comment (no-changes)

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

don-petry commented Jun 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants