Google Sheets: Append rows

Adds rows below a sheet’s table, once, even when the step is retried.

• Kind: google-sheets.append_rows
• Palette: Integrations, under Google Sheets
• Credential: a credential of kind bearer, named in credential
• Other Google Sheets actions: Read rows as objects, Update or append a row by key, Read range, Update range, Clear range, Get spreadsheet details, Create spreadsheet, Add sheet

When to use

• Logging: one row per run, per order, per alert.
• Collecting results from a fan_out into a sheet a person reads.

Google appends whatever it is sent, so a retried append would add the rows twice. Give key_column a column the rows leave empty: each row carries the step’s key there, the action looks for the key before writing, and appends nothing when it is already in the sheet. To update a row that may already exist, use update_row_by_key.

Connection (with)

Field	Required	Description
spreadsheet_id	yes	The id in the spreadsheet’s address: docs.google.com/spreadsheets/d/<id>/edit. For example: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms.

Input (input)

Field	Type	Required	Description
sheet	string	yes	The sheet (tab) to add rows to, by name. They go below its table.
values	array of array	yes	Rows to add, from column A: a list of lists, e.g. [[“2026-09-26”, “north”, 12]].
key_column	string	no	A column the rows leave empty, e.g. F. Each row gets the step’s key there, and a retry that finds it appends nothing, so the rows are written once.
key	string	no	What key_column is checked for and written with. Absent: the step’s own key, which is the same on every retry of the step.
value_input	string	no	Parse the values as if typed (formulas, dates), or store them as given. One of "USER_ENTERED", "RAW". Default "USER_ENTERED".

Settings

Beside with and input in the node’s config.

Field	Type	Required	Description
credential	string	yes	Name of the project credential the action authenticates with.
optional_when_untrusted	boolean	no	Run without the credential when the run is untrusted (a fork pull request), instead of failing. The credential is still withheld.

Output

What the action’s script returns, read as nodes.<id>.output.<field>.

Field	Type	Description
appended	boolean	False when the key was already in key_column, so nothing was written.
key	string	The key in key_column, when there is one.
range	string	Where they went, in A1 notation.
rows	integer	How many rows were written.

How it runs

• On an agent with the connector capability. The managed environments have one, so this needs no agent of your own.
• A script: appendRows from the connector’s sheets.js, which may call only sheets.googleapis.com. The credential goes on those requests as headers, and the script never sees it.
• The script decides what counts as a failure, so retry_on and fail_on_error_status do not apply.

Example

version: hyperspool-graph/v1
nodes:
  - id: log
    type: google-sheets.append_rows
    config:
      credential: sheets
      with: { spreadsheet_id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms }
      input:
        sheet: Deploys
        key_column: F
        values:
          - - { $expr: "run.id" }
            - { $expr: "input.service" }
            - { $expr: "input.version" }
edges: []

The rows start at column A, so here they fill A to C and the key goes in F. The output says whether it appended, how many rows, and the range they went to.

See Connectors for credentials and versions, and the node reference for every other node.