docs(connectors): rewrite the Google client-ID walkthrough for the current console#2189
Merged
Merged
Conversation
…t console The connect-your-Gmail docs had drifted from the live Google Cloud Console and the real connector flow, so a maintainer following them hit four undocumented walls: the OAuth settings moved to the Google Auth Platform (Branding/Audience/Clients), enabling the Gmail/Calendar APIs is a hard prerequisite (skipping it 403s the first mailbox call, #2116), personal accounts must use External consent + a test user (with ~7-day token expiry), and connecting is not enough — the email agent needs an explicit per-agent grant until #2117 lands. Update all three doc surfaces together: the user-facing BYO-client walkthrough (connectors/google), the email guide's connect section + the AGENT_NOT_GRANTED troubleshooting entry, and the AMD-internal runbook — keeping the AMD-managed client + rotation content distinct from the BYO path and cross-linking #2104 as the end state that removes the BYO step. Also corrects the runbook's stale 'no client secret' claim to match the connector code, which requires the secret even for Desktop-app PKCE clients. Part of #2014 Closes #2120
github-actions
Bot
added
documentation
added 3 commits
July 17, 2026 17:57
…nces Self-review pass against the connector code: - CLI connect must pass --scopes: start_authorization falls back to default_scopes (openid/email/profile) when --scopes is omitted, so the bare 'gaia connectors connect google' never authorizes the Gmail/Calendar scopes and the per-agent grant alone would fail with a scope error. - Grant is only half on the CLI — clarify that the connection must be authorized with the scopes first (connect --scopes) then granted. - Runbook: a missing client id raises ConfigurationError, but a missing secret is not caught there (Google's token endpoint rejects it later); correct the pluralized wording to match providers/google.py.
…ole URLs in link check - Remove stray tool-call closing tags accidentally written to the end of connectors/google.mdx, which made Mintlify fail to parse the file (and falsely report the page missing from docs.json). - Add console.cloud.google.com, support.google.com, and myaccount.google.com to the doc link checker's SKIP_DOMAINS: all redirect unauthenticated requests to sign-in (302) or locale-gate automated requests (404), so a CI bot can never resolve them — same class as the existing support.microsoft.com / platform.openai.com skips. The walkthrough needs these direct console links (#2120), and pre-existing console/myaccount links hit the same wall.
kovtcharov
approved these changes
Jul 18, 2026
Collaborator
|
One merge-ordering issue before this ships: the Agent UI tab states that Connect/Reconnect "grants the Email Triage agent these scopes for you, so no separate grant step is needed" — but that auto-grant behavior only lands with #2195, which is still open. On main today no UI flow writes grants, so a user following the Agent UI tab as documented connects and then hits Suggest either merging this after #2195, or wording the Agent UI tab to match current behavior until it lands. |
This was referenced Jul 18, 2026
pull Bot
pushed a commit
to bhardwajRahul/gaia
that referenced
this pull request
Jul 19, 2026
…ok (amd#2264) ## Why this matters The runbook's security-boundaries section tells operators `client_id_hash` is a sha256 of the client id and therefore safe to log without leaking it — but the provider actually computes a CRC32 fingerprint (`zlib.crc32`, explicitly non-cryptographic, for log correlation and the rotation tripwire only). The doc now matches the code instead of overstating the guarantee. This is the surviving remainder of the amd#2119/amd#2120 branch — everything else on it was superseded by amd#2189, amd#2193, and amd#2195 landing on main first. ## Test plan - [x] Doc-only change; verified against `src/gaia/connectors/providers/google.py` (`client_id_hash = format(zlib.crc32(...), "08x")`)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why this matters
Following our own connect-your-Gmail docs live, a maintainer hit four undocumented walls — because the walkthrough had drifted from both the current Google Cloud Console and the real connector flow. Before: the docs sent users to APIs & Services → Credentials (a menu Google removed), never mentioned enabling the Gmail/Calendar APIs (so the first mailbox call 403s with a raw Google error even though the connection looks healthy, #2116), didn't cover the personal-account path (External consent + test user, ~7-day token expiry, the "unverified app" interstitial), and implied that connecting was enough. After: a verified step-by-step that matches the live Google Auth Platform (Branding/Audience/Clients) layout, treats API enablement as the hard prerequisite it is, and documents the required per-agent grant (
gaia connectors grants grant google installed:email …) plus the exactAGENT_NOT_GRANTEDerror that signals it.All three doc surfaces are updated together per the CLAUDE.md multi-surface rule: the user-facing BYO-client walkthrough (
connectors/google), the email guide's connect section +AGENT_NOT_GRANTEDtroubleshooting entry, and the AMD-internal runbook. The runbook stays focused on the AMD-managed client + rotation and cross-links #2104 as the end state that removes the BYO step; its stale "no client secret" claim is corrected to match the connector code (the secret is required even for Desktop-app PKCE clients).Test plan
connectors/google.mdxrenders: Step 2 (enable APIs, 403/feat(email): map Google's API-not-enabled 403 to an actionable error naming the enable URL #2116 warning, 1–2 min propagation), Step 3 (Google Auth Platform → Branding/Audience, External-only for personal Gmail, test user, 7-day expiry), Step 4 (Clients tab,console.cloud.google.com/auth/clients), Step 6 (email-agent grant with full scope URLs), and the two new Common-issues entries.installed:emailagent id (connector_routes.py) and the fourhttps://www.googleapis.com/auth/…scopes (scopes.py)./connectors,/connectors/google,/guides/email#setup,/security/connections, in-page anchors, and the runbook's relative../connectors/google.mdx.docs/docs.jsonunchanged (both edited pages already in nav; the runbook is referenced via GitHub blob links).Part of #2014
Closes #2120