Skip to content

feat(sources): connect Gmail from the connection dialog, with Connect with Google - #420

Merged
adeelahmad merged 2 commits into
mainfrom
claude/project-thread-yergon
Oct 15, 2026
Merged

adeelahmad merged 2 commits into
mainfrom
claude/project-thread-yergon

Conversation

@adeelahmad

Copy link
Copy Markdown
Owner

Requested by Adeel · project thread

Description

Before: a Gmail source (#405) could be added only through the API, by pasting a Google account's authorized user JSON or a service account key. Add connection had no Gmail option.

After: Add connection › Gmail offers Google account or Service account, as Google Calendar does.

  • Google account: Connect with Google saves the connection and opens Google's consent screen. Google asks to read mail, read only; reading over IMAP asks for all of Gmail, because Google has no read-only scope for IMAP. Back on Sources, the account's address is the connection's user and its labels open, ready to pick one to watch. Pasting an authorized user JSON still works under the fold.
  • Service account: it takes the key file and the address of the person whose mail Lens reads. It also says which client ID and scope a Workspace admin must allow, and where to do that.

A Gmail row whose sign-in stopped working shows Connect Google account.

How: Gmail joins the one consent flow that Google Calendar brought in #407. gmail.SCOPES(params) names the scopes and ACCOUNT = "user" names the parameter that gets the address; google_auth._module finds gmail too. The form's Google account block now serves both types.

Motivation and Context

Second half of Adeel's request for Gmail and Google Workspace as a sensor, by OAuth or service account, over the API or IMAP. #405 shipped the source. This PR is the one-click OAuth and the dialog.

Steps to reproduce (if appropriate):

  1. Set up Google in Settings › Sign-in, or enter an OAuth client in the form.
  2. Go to Sources › Add connection › Gmail and click Connect with Google.
  3. Allow access on Google's page. The labels open; pick Inbox to watch.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change; ! in the title)

Checklist:

  • The title is a Conventional Commit.
  • My code follows the code style of this project (ruff, mypy, prettier, eslint, tsc clean).
  • I added or updated tests:
    • test_connecting_the_account_in_the_browser: the consent asks for the right scopes, an unticked box leaves the source unconnected, the address becomes user, and IMAP asks for all of Gmail;
    • __tests__/add-connection.test.tsx: Gmail with Connect with Google, and a service account needs the address;
    • __tests__/sources-model.test.ts: Gmail's validation and payload.
    • Locally the whole web suite passed (923 tests), and the backend suite (1123 passed, 20 skipped).
  • My change requires documentation updates, and I have updated docs/ accordingly (docs/processing.md, Gmail and Google Workspace).
  • Users need more than the title to understand it, so I wrote it under ## Unreleased in CHANGELOG.md.

Done questions (AGENTS.md)

  • Goal: Gmail by OAuth is one click, and by service account it's the key plus an address. Together with feat(sources): Gmail and Google Workspace as an email sensor #405 this completes the request; merging on green.
  • Agents: an agent creates the source and saves an authorized user JSON as token, or a key, through the API. The consent itself has to be a person in a browser (feat(sources): Connect with Google for Google Calendar connections #407's rule).
  • Zero setup: nothing to install. With Google sign-in set up there is nothing to enter.
  • Fewest clicks: one click to Google and one Allow there; the labels open on return.
  • Configurable: via, user and the sign-in are edited in the form. Nothing is added to the setup wizard.
  • Light: no new dependency or process.
  • Private and secure: the flow is feat(sources): Connect with Google for Google Calendar connections #407's: admin only, single-use state bound to the browser, PKCE, and sealed secrets. The token is kept only when Google granted the source's scope. The threat model's Connect with Google entry now says that Gmail over IMAP needs all of Gmail.
  • Cost: no model calls; the code exchange is a google.token row in the activity ledger.
  • User decides: nothing connects until an admin clicks and consents. Defaults are unchanged (via stays api).
  • Upgrades: n/a, stored data keeps its shape.
  • Honest: the docs describe what is built.
  • Tests, docs and generated files are updated (make openapi).
  • Open: OAuth 2.0 with PKCE, and the OpenID Connect id token.
  • Reported: refine later: name a new connection after its address ("Gmail · mara@…") once it's connected.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q


Generated by Claude Code

… with Google

Add connection › Gmail connects the account through the same consent flow
as Google Calendar (#407): Google asks to read mail (all of Gmail for
IMAP), the account's address becomes the source's user, and its labels
open. A Workspace service account takes its key and the address it acts
for, and says which client id and scope an admin must allow. A Gmail row
whose sign-in stopped working offers Connect Google account.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q
…e's wording

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q
@adeelahmad
adeelahmad merged commit f75176e into main Oct 15, 2026
11 checks passed
@adeelahmad
adeelahmad deleted the claude/project-thread-yergon branch October 15, 2026 14:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants