# 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.