contributions: clarify Maintainer team access

[SSakutaro]

---

• Have you followed our Contributing guidelines?
• Have you checked for other open Pull Requests for the same change?
• Have you explained what your changes do? Performance claims (e.g. "this is faster") must include Hyperfine benchmarks.
• Have you explained why you'd like these changes included, not just what they do?
• For bug fixes, have you given step-by-step brew commands to reproduce the bug?
• Have you written new tests (excluding integration tests)? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) locally?

---

• I did not use AI/LLM to create this PR, or I disclosed the tool/model below and reviewed its output; I did not attribute commits to AI and will answer maintainer questions and review comments myself without AI/LLM.

Codex (GPT-5) assisted with investigating the issue, drafting the implementation and tests. I reviewed the resulting diff, reproduced the issue and fallback locally, and ran the relevant tests and brew lgtm --online.

---

brew contributions fetches the Homebrew/maintainers team by default. When the current GitHub account cannot view organization teams, the command incorrectly reports that the token needs read:org, even when that scope is already present.

This change replaces the scope-specific error with an actionable message covering both GitHub account access and
token permissions. It also documents that the default Maintainer search requires access to the Homebrew/maintainers team.

Reproduction

$ gh auth status
Token scopes: 'gist', 'read:org', 'repo', 'workflow'

$ brew contributions
Error: Your token needs the 'read:org' scope to access this API

With this change:

$ brew contributions
 Error: Could not access the team Homebrew/maintainers. Please check that your GitHub account has access to the team and that your token has the required permissions.

Testing

Added a test covering an inaccessible team without assuming that the token is missing a particular scope.

$ brew lgtm --online

[Copilot]

Pull request overview

This PR improves brew contributions behavior when GitHub organization teams are not accessible to the current user/token by introducing a dedicated TeamAccessError and adding a fallback that reads the public Maintainers list from Homebrew/brew’s README.md.

Changes:

• Add GitHub::TeamAccessError and update GitHub.members_by_team to raise it when a team is missing or inaccessible (instead of a misleading scope message).
• Update brew contributions to use default maintainers (team-first, README fallback) when no --team/--user/report mode is specified, reusing the existing README maintainer parser.
• Add specs covering the inaccessible-team error and the README fallback path.

Reviewed changes

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

File	Description
Library/Homebrew/utils/github.rb	Introduces TeamAccessError and changes members_by_team error handling for inaccessible teams.
Library/Homebrew/dev-cmd/contributions.rb	Adds default maintainer resolution and README-based fallback by reusing the README parser.
Library/Homebrew/test/utils/github_spec.rb	Adds a unit test asserting members_by_team raises TeamAccessError for inaccessible teams.
Library/Homebrew/test/dev-cmd/contributions_spec.rb	Adds a test for the brew contributions README fallback behavior when team access fails.

---

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

[MikeMcQuaid]

@SSakutaro why are you trying to run brew contributions on the maintainers without this access scope?

[SSakutaro]

@MikeMcQuaid

I originally encountered this while investigating obviously incorrect results from brew contributions --user SSakutaro:

$ brew contributions --user SSakutaro
Fetching latest commits for Homebrew/brew...
Fetching latest commits for Homebrew/homebrew-core...
Fetching latest commits for Homebrew/homebrew-cask...
SSakutaro contributed >=1001 times (merged PRs authored), >=1000 times (PRs merged), >=1001 times (qualifying merged PRs), 39 times (approved-review search matches), 98 times(co-authored commits) and >=1138 times (total) between 2025-08-01 and 2026-08-02.

I have not authored or merged anywhere near that many PRs, so as part of the investigation I checked the command's behavior both with and without arguments. That is when I encountered this error.

My original goal was not to inspect the Maintainers' contribution totals.

I was also confused by this error message:

Error: Your token needs the 'read:org' scope to access this API

My token already has the read:org scope. My understanding is that read:org allows the token to read organization information that is visible to the authenticated account; it does not itself grant organization membership or permission to view teams.

I therefore believe the team lookup fails because I am not a member of the Homebrew organization, rather than because the token is missing the required scope. Since the error still says that read:org is required, it did not appear to accurately describe the cause of the failure.

I proposed the README fallback because the Maintainer list is already public, and the documentation for brew contributions does not state that running it without arguments is limited to members of the Homebrew organization.

However, if the no-argument form of brew contributions is intended only for Homebrew organization members who can view the team, then I agree that the README fallback would not be appropriate. In that case, I would be happy to narrow this PR to improving the error message and documentation, or close it if preferred.

[MikeMcQuaid]

I have not authored or merged anywhere near that many PRs, so as part of the investigation I checked the command's behavior both with and without arguments. That is when I encountered this error.

Interesting. Would love a fix for that!

In that case, I would be happy to narrow this PR to improving the error message and documentation

This would be great, thanks 🙇🏻

[SSakutaro]

Got it, thanks!

I'll narrow this PR to improving the error message and documentation, and remove the README fallback.

After that, I'll investigate the incorrect contribution counts separately and follow up with another PR when I have a focused fix.

[MikeMcQuaid]

Thanks, looks good! GitHub Copilot review comment worth a look.

[SSakutaro]

Got it. I've incorporated the review.

[MikeMcQuaid]

Thanks!