Use an existing Google Sheet with Topline

Use this guide when the Google Sheet already exists and Topline should read or update it directly for a task. This is different from connecting the Sheet as a managed data source.

Find the Topline sharing identities

1. In Topline, open Account > Sources.
2. Choose Add data source, then Google Sheets.
3. In Google Sheets access, copy the identity for the access you need.

Topline shows separate identities because reads and writes use different, least-privileged Google service accounts:

• For read-only access, share the Sheet with the Read-only sharing email as a Viewer.
• For read-write access, share the Sheet with the Read-only sharing email as a Viewer and the Read-write sharing email as an Editor.

Copy the identity from the current Topline screen. Do not reuse an address from an old message or another environment.

Share without creating a managed pipeline

Open the Sheet's Share dialog, add only the required Topline identity or identities, and keep General access set to Restricted. Never change the Sheet to "Anyone with the link" or public access for Topline.

Sharing the Sheet does not create a Topline source, copy the Sheet into reporting tables, or schedule a sync. Stop on the Google Sheets setup page after copying the identities if direct task access is all you need. Continue through Check, Review, and Save only when you intentionally want a managed connector and scheduled pipeline.

Direct Sheet bridge tools are task-scoped: they are available only while a Topline build or task is running. A deployed artifact app cannot call those tools at runtime. If a deployed app must read Sheet data, create a managed Google Sheets source and sync pipeline, materialize the approved data into the Topline catalog, and expose only bounded artifact datasets. Do not put Google service-account JSON, OAuth tokens, or Google credentials in artifact secretBindings for either path.

After sharing, give the Topline task the Sheet URL or spreadsheet ID and the smallest necessary tab or A1 range. Do not paste OAuth tokens, service-account keys, other secrets, or Sheet contents into setup instructions.

For a task that has the approved Google Sheets skill, Topline can call get_google_sheet_access_setup to return the same current reader and writer identities plus broker readiness without exposing credentials or Sheet data. It can then call verify_google_sheet with accessMode: "read" or accessMode: "write"; both are non-mutating reachability checks with the selected identity. A successful writer-identity check does not prove that Google granted Editor permission, so confirm the writer is listed as an Editor before relying on writes. When launching a Coding task that must use these tools, declare google_sheets_read or google_sheets_write in requiredCapabilities. Topline checks the project skill before launch and asks the workspace owner to add it when missing; it never grants the capability automatically.

Keep access least-privileged

• Prefer Viewer access. Add the writer identity only when the task must change cells or append rows.
• Give the task a bounded range rather than broad instructions to inspect or rewrite the entire workbook.
• Confirm the exact range and intended change before a write.
• Do not grant access to unrelated Drive folders or files.

Revoke access

Open the Sheet's Share dialog and remove the Topline reader and writer identities that were added. This ends future direct access to the Sheet.

If the Sheet was also saved as a managed source, removing Google sharing stops future reads and syncs but does not delete data that was already materialized in Topline. Archive or delete that source separately according to your retention requirements.

Troubleshoot access

• Not shared or permission denied: Confirm that the current identity from Topline was added exactly and that General access remains Restricted.
• Reads work but writes fail: Confirm that the reader is a Viewer and the writer is an Editor. The reader identity cannot write.
• A sharing identity is not configured: Ask a Topline administrator to check the Google Workspace foundation. Do not substitute a personal account, JSON service-account key, or OAuth token.
• Google blocks the share: A Google Workspace policy may prevent sharing outside the domain. Ask the Sheet owner's Workspace administrator to approve the restricted share; do not make the Sheet public as a workaround.
• The task cannot see Google Sheet tools: Ask the workspace manager to add the approved Google Sheets Task Queue skill under Project Settings > Skills, then retry the task. Do not create a managed connector merely to bypass a missing task capability.
• A deployed artifact app needs the data: Task bridge tools stop at the task boundary. Use a managed Google Sheets source, sync pipeline, materialized catalog data, and bounded artifact datasets instead of app-held credentials.

For audit review, use the Sheet's Google Drive activity to inspect sharing and cell changes. For build/task-time bridge calls, Topline also records successful and failed brokered Sheet operations with the task, spreadsheet ID, bounded range, selected identity, access mode, and a redacted reason or cell/row count. It does not put Sheet contents, provider payloads, tokens, or credential values in the audit record.