fix: use gmail.readonly scope in +triage to avoid metadata scope 403

[zerone0x]

Summary

• Fix gmail +triage failing with 403 PERMISSION_DENIED when the OAuth token includes gmail.metadata scope alongside other Gmail scopes
• Switch the +triage helper from requesting gmail.modify to gmail.readonly scope, which supports the q query parameter and matches the read-only nature of triage
• Add GMAIL_READONLY_SCOPE constant for reuse by read-only Gmail helpers

Root Cause

The +triage helper uses the q query parameter when calling messages.list, but Gmail's metadata scope does not support q and returns 403. When a user's OAuth token carries both gmail.metadata and gmail.modify scopes, the Gmail API may resolve to the metadata code path and reject the query with PERMISSION_DENIED.

Test plan

• cargo clippy -- -D warnings passes with no warnings
• cargo test passes (429 tests)
• Manual: run gws gmail +triage with a token that has both gmail.metadata and gmail.readonly scopes -- should return unread inbox summary without 403

Fixes #265

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 1ee52fe

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@googleworkspace/cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a critical 403 PERMISSION_DENIED error encountered by the gmail +triage command. The issue stemmed from a conflict when an OAuth token contained both gmail.metadata and gmail.modify scopes, causing the Gmail API to reject queries using the q parameter. By transitioning the +triage helper to use the gmail.readonly scope, which inherently supports the q parameter and is appropriate for a read-only operation, the command now functions reliably without scope-related authentication failures.

Highlights

• Fix 403 error in gmail +triage: Resolved the 403 PERMISSION_DENIED error that occurred when the OAuth token included gmail.metadata scope alongside other Gmail scopes, specifically impacting the +triage helper.
• Scope change for +triage: Switched the +triage helper from requesting the gmail.modify scope to gmail.readonly, which correctly supports the q query parameter and aligns with the read-only nature of the triage operation.
• New constant for read-only scope: Added a GMAIL_READONLY_SCOPE constant to src/helpers/gmail/mod.rs for consistent reuse by read-only Gmail helpers.

Changelog

• .changeset/fix-gmail-triage-scope.md
  • Added a new changeset file documenting the fix for the Gmail triage scope issue.
• src/helpers/gmail/mod.rs
  • Introduced a new constant GMAIL_READONLY_SCOPE for the Gmail read-only API.
• src/helpers/gmail/triage.rs
  • Updated the authentication scope for the +triage helper from gmail.modify to gmail.readonly to resolve 403 errors.

Activity

• The pull request aims to fix issue bug: gmail +triage selects metadata scope and fails with q parameter (403) #265.
• Automated checks for cargo clippy -- -D warnings and cargo test passed successfully.
• A manual test is planned to verify gws gmail +triage with specific token scopes.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request correctly addresses a 403 PERMISSION_DENIED error in the gmail +triage command by switching from the gmail.modify scope to the more appropriate gmail.readonly scope. This change resolves a conflict with the gmail.metadata scope, which does not support the q query parameter used by the triage feature. The introduction of a GMAIL_READONLY_SCOPE constant is a good practice for maintainability. The changes are sound and effectively fix the bug.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 59.09%. Comparing base (95bb24e) to head (1ee52fe).
⚠️ Report is 14 commits behind head on main.

Files with missing lines	Patch %	Lines
src/helpers/gmail/triage.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #304   +/-   ##
=======================================
  Coverage   59.09%   59.09%           
=======================================
  Files          36       36           
  Lines       12953    12953           
=======================================
  Hits         7654     7654           
  Misses       5299     5299           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.