docs: document fine-grained token scopes for ORG_SCORECARD_TOKEN

[don-petry]

Documents the required Fine-Grained Personal Access Token scopes (specifically Administration: Read-only) for the ORG_SCORECARD_TOKEN to resolve false-positive compliance audit issues regarding repository settings like delete_branch_on_merge.

Summary by CodeRabbit

• Documentation

  • Added explicit guidance for CI audit tokens: required repository access and specific fine‑grained read-only permissions needed for scorecard/audit workflows.

• Bug Fixes

  • Improved authentication preflight error message to clearly tell operators which token and fine‑grained repository permissions to verify for successful validation.

[coderabbitai]

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 25 minutes and 3 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: 9f5528e4-e0ae-4b8b-b0e1-b8e43417716e

📥 Commits

Reviewing files that changed from the base of the PR and between 63cc4c5 and 0016f04.

📒 Files selected for processing (2)

• .gitignore
• scripts/compliance-audit.sh

📝 Walkthrough

Walkthrough

This PR updates token scope requirements for the OpenSSF Scorecard integration across two coordinated locations: the compliance audit script's error message now directs operators to verify ORG_SCORECARD_TOKEN validity and Fine-Grained token scopes, and the CI standards documentation now explicitly specifies those scope requirements.

Changes

ORG_SCORECARD_TOKEN scope requirements

Layer / File(s)	Summary
Token scope error message and documentation scripts/compliance-audit.sh, standards/ci-standards.md	Updated the gh auth status failure message to reference Fine-Grained token scope requirements (Administration: Read-only, Metadata: Read-only) and added corresponding documentation detailing repository access and explicit scope requirements for ORG_SCORECARD_TOKEN.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• petry-projects/.github#12: Updates to the compliance audit script and ORG_SCORECARD_TOKEN scope guidance relate to the initial introduction and usage of org token configuration.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: documenting fine-grained token scopes for ORG_SCORECARD_TOKEN, which is the core objective of both the script and documentation updates.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch update-scorecard-token-docs

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[gemini-code-assist]

Code Review

This pull request updates the compliance audit script and documentation to clarify the requirements for the ORG_SCORECARD_TOKEN when using Fine-Grained Personal Access Tokens. The reviewer suggested including the necessary Organization-level 'Metadata: Read-only' scope in both the script's error message and the documentation to ensure repository discovery works correctly. Additionally, it was recommended to specify 'Read and write' access for Issues since the script manages them.

[Copilot]

Pull request overview

This PR updates the org standards documentation and audit-script messaging to clarify required Fine-Grained PAT permissions for ORG_SCORECARD_TOKEN, intended to prevent false-positive compliance findings when reading repository settings such as delete_branch_on_merge.

Changes:

• Document Fine-Grained PAT requirements for ORG_SCORECARD_TOKEN in standards/ci-standards.md.
• Update the gh auth status failure message in scripts/compliance-audit.sh to reference Fine-Grained PAT permissions.

Reviewed changes

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

File	Description
standards/ci-standards.md	Adds documentation for the Fine-Grained PAT permissions needed by ORG_SCORECARD_TOKEN.
scripts/compliance-audit.sh	Adjusts authentication failure guidance to mention Fine-Grained PAT permissions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/compliance-audit.sh`:
- Line 1319: Update the error message string that currently says "Check that
ORG_SCORECARD_TOKEN is valid. If using a Fine-Grained token, ensure it has
'Administration: Read-only' and 'Metadata: Read-only' repository scopes." to
either enumerate all five required Fine-Grained token scopes (Administration:
Read-only; Metadata: Read-only; Contents: Read-only; Issues: Read and write;
Organization: Metadata (Read-only)) or replace the inline scope list with a
short pointer to the full documentation (e.g., "see standards/ci-standards.md
lines 964-968") so operators receive complete remediation guidance; locate and
edit the exact message literal in scripts/compliance-audit.sh that emits the
ORG_SCORECARD_TOKEN guidance.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4167fc72-e5e4-414e-aa59-bfece5cca38b

📥 Commits

Reviewing files that changed from the base of the PR and between 3403601 and a4ca4f8.

📒 Files selected for processing (2)

• scripts/compliance-audit.sh
• standards/ci-standards.md

[github-actions]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved manually.

Please resolve the conflicts and push:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[donpetry-bot]

Superseded by automated re-review at 70d8cd39c7d570d9c64bbbfe4de82f996ead1e7c — click to expand prior review.

Review — fix requested (cycle 1/3)

The automated review identified the following issues. Please address each one:

Findings to fix

[Findings would be inserted here]

Additional tasks

1. Resolve all unresolved review thread comments from other reviewers
2. Ensure all CI checks pass after your changes
3. Rebase on the target branch if behind
4. Do NOT modify files unrelated to the findings above

The review cascade will automatically re-review after new commits are pushed.

[donpetry-bot]

Superseded by automated re-review at da5fa6b1f4bb527ed6b83b62d64236caec6c2a2f — click to expand prior review.

Review — fix requested (cycle 2/3)

The automated review identified the following issues. Please address each one:

Findings to fix

[Findings would be inserted here]

Additional tasks

1. Resolve all unresolved review thread comments from other reviewers
2. Ensure all CI checks pass after your changes
3. Rebase on the target branch if behind
4. Do NOT modify files unrelated to the findings above

The review cascade will automatically re-review after new commits are pushed.

[don-petry]

@dev-lead please process and advance this PR — fix any failing CI, resolve outstanding review threads, and enable auto-merge once it's green and approvable.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[donpetry-bot]

Automated review — APPROVED ✓

Risk: LOW
Reviewed commit: 0016f040c4b5bd328a1690b4e030df3b43dbe75e
Review mode: triage-approved (single reviewer)

Summary

Documentation-only changes (plus a one-line error-message tweak) clarifying the Fine-Grained PAT permissions required for ORG_SCORECARD_TOKEN. Triage classification (LOW) confirmed: no auth/secret/migration/CI-security surface beyond a clearer permissions list. All five prior reviewer threads (gemini, copilot, coderabbit) are resolved on the current SHA and the substantive feedback (Organization Metadata Read-only, fine-grained vs OAuth phrasing, completing the permission list) has been incorporated.

Linked issue analysis

No closing issue references on this PR. The PR description ties the change to false-positive compliance findings on delete_branch_on_merge; the new documentation in standards/ci-standards.md and the updated preflight error message in scripts/compliance-audit.sh directly address that motivation by spelling out the Administration: Read-only permission (and the rest) operators need on the token.

Findings

Nit — duplicate .gitignore entry (non-blocking): .dev-lead/ is now listed twice at the bottom of .gitignore (lines 392 and 393). Git treats duplicates as a no-op, so this has zero functional effect, but it is a minor cleanup worth folding into the next touch of this file.

No other issues identified. The expanded error message in scripts/compliance-audit.sh:1722 matches the permission list documented in standards/ci-standards.md:1063-1067, and the org-level Metadata permission is called out in both places as flagged by earlier reviewers.

CI status

All 19 status checks completed: 13 SUCCESS (AgentShield, Lint, ShellCheck, Secret scan (gitleaks), Agent Security Scan, CodeQL (actions + meta), SonarCloud x3, CodeRabbit, pr-auto-review check-and-dispatch, Detect ecosystems, Dependency audit dispatcher) and 6 SKIPPED (dependabot-automerge, ecosystem-specific audits with no manifests). No failures, no pending checks.

---

Reviewed automatically by the PR-review agent (single-reviewer mode: opus 4.7). Reply if you need a human review.