Google Sheets Port

Purpose

This is the reference integration for the Google Sheets API and Harbor's Action Model.

Use it when:

• building Google Sheets actions in Harbor
• extending the Dock / Hub Google Sheets entry
• teaching Codex or OpenClaw how to map a spreadsheet API into Harbor Ports and Harbor Actions without turning Harbor into a generic proxy

Harbor Port worksheet

Product

• Product: Google Sheets API
• Publisher slug: google
• Publisher name: Google
• Category: Productivity
• Tags: google, sheets, spreadsheets, productivity, data

Safe Harbor Port metadata

• Kind: http_api
• Label: Google Sheets API
• Description: Google Sheets API connection managed locally through Harbor.
• Base URL: https://sheets.googleapis.com/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Google Sheets is a good Harbor fit when every action stays on fixed spreadsheet-scoped routes with typed input.path values for spreadsheetId and range.

Good Harbor Google Sheets actions:

• GET reads for spreadsheet metadata and cell range values
• bounded POST and PUT writes for appending, overwriting, clearing, and batch-updating
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for bounded writes
• resultMode: "json_summary" for all starter actions
• typed input.path values for spreadsheetId and range on every action that needs them

Avoid for now:

• actions that accept an arbitrary spreadsheetId supplied directly in a full URL
• batchGet via query-string ranges arrays
• developer metadata endpoints
• arbitrary range formatting surfaces with many optional parameters
• automatic publish of any write action

Starter Google Sheets actions

Automatic read actions

• get-spreadsheet -> GET /v4/spreadsheets/{spreadsheetId}
• read-range -> GET /v4/spreadsheets/{spreadsheetId}/values/{range}

Approval-friendly write actions

• append-row -> POST /v4/spreadsheets/{spreadsheetId}/values/{range}:append
• update-range -> PUT /v4/spreadsheets/{spreadsheetId}/values/{range}
• clear-range -> POST /v4/spreadsheets/{spreadsheetId}/values/{range}:clear
• batch-update -> POST /v4/spreadsheets/{spreadsheetId}:batchUpdate

Action Input Notes

Every action here uses at least input.path.spreadsheetId. Range-scoped actions also use input.path.range.

When running these actions, pass values like:

• input.path.spreadsheetId: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
• input.path.range: Sheet1!A1:D10

The colon in range strings (A1:D10) is a standard Sheets notation and is distinct from the :append / :clear / :batchUpdate custom method suffixes that Google appends to the route path. Harbor treats the custom method suffix as a literal part of the path template, and input.path.range remains the typed range input.

Why these actions

These routes fit Harbor's Action Model because they:

• stay under one fixed Sheets API origin
• use explicit named path inputs that operators supply at execution time
• keep inputs bounded and reviewable
• can be reviewed as named capabilities
• keep hidden auth entirely local to Harbor Node

Suggested operator workflow

1. Import the Google Sheets Dock entry from Dock / Hub.
2. Configure the local Google bearer token in Harbor Node with the https://www.googleapis.com/auth/spreadsheets scope.
3. Use get-spreadsheet first to confirm the port is working and inspect available sheets.
4. Use read-range with an explicit range such as Sheet1!A1:Z1 to verify read access.
5. Keep all write actions on require_approval unless there is a deliberate local policy reason not to.

Suggested agent workflow

1. Inspect the existing Google Sheets Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed-path actions only.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents must never:

• ask Harbor for the stored token
• edit hidden Google Sheets auth
• widen an action into a generic arbitrary proxy

Current update strategy

For now, Google Sheets updates are manual:

• update the Dock / Hub Google Sheets integration document in apps/hub/catalog/integrations/google/google-sheets.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Official reference starting points

• Google Sheets API overview: https://developers.google.com/sheets/api/reference/rest
• Spreadsheets get: https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/get
• Values get: https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/get
• Values append: https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/append
• Values update: https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/update
• Values clear: https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/clear
• Spreadsheets batchUpdate: https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/batchUpdate