> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud Pub/Sub

> Trigger workflows from Pub/Sub messages and publish events to Pub/Sub topics

Google Cloud Pub/Sub is Google's managed message broker. The Noxus integration lets you:

* **Trigger workflows** from any pull subscription using the **Google Pub/Sub Message Received** trigger.
* **Publish messages** to topics from inside a workflow using the **Publish to Pub/Sub** node.

This is the right integration for general-purpose event-driven workflows. If you specifically need to receive **Google Chat** events via Pub/Sub (for environments where the Noxus relay can't accept inbound webhooks), see the [Google Chat Pub/Sub delivery](https://docs.noxus.ai/platform/agents/deployments/google-chat.md) guide instead.

## Authentication

The integration uses **service-account credentials only**. OAuth user tokens don't pair naturally with Pub/Sub IAM, and supporting them would require constant token-refresh juggling for what is effectively backend infrastructure.

**1. Create a Google Cloud service account**

In [Google Cloud Console](https://console.cloud.google.com), open **IAM & Admin → Service Accounts** in the project that owns your Pub/Sub topics and subscriptions. Create a service account dedicated to Noxus (e.g. `noxus-pubsub@MY_PROJECT.iam.gserviceaccount.com`).

Click **Keys → Add Key → Create new key → JSON** to download the JSON key file.

**2. Enable the Pub/Sub API**

On the same Google Cloud project, open **APIs & Services → Library**, search for **Cloud Pub/Sub API**, and click **Enable** if it's not already on.

**3. Connect the credential in Noxus**

In Noxus, open **Connections** → **Add connection** → **Google Pub/Sub**. Paste the entire contents of the JSON key file into **Service account JSON** and click **Connect**.

Noxus mints a token from the key, hits the Pub/Sub API in your project, and surfaces a validation error if anything is wrong (disabled SA, missing API, blocked project, etc.). On success the integration card shows the connected SA's email and project ID.

> [!NOTE]
>
> **The service account just authenticates** — it doesn't grant access to anything by itself. You still need to grant per-resource IAM roles on each topic or subscription the integration touches (see below).

## IAM grants

Two IAM roles, granted on **different resources** depending on which surface you're using:

| Surface | Resource | Role to grant the Noxus SA |
| :- | :- | :- |
| **Trigger** (workflow listens for messages) | The **subscription** | `roles/pubsub.subscriber` |
| **Publish node** (workflow sends messages) | The **topic** | `roles/pubsub.publisher` |

Activate-time validation catches missing grants on the trigger side; for the publish node the error surfaces on the first publish call with an actionable message.

```bash theme={null}
# Trigger side — grant the Noxus SA permission to consume a subscription
gcloud pubsub subscriptions add-iam-policy-binding YOUR_SUBSCRIPTION \
  --project=YOUR_PROJECT \
  --member=serviceAccount:noxus-pubsub@YOUR_PROJECT.iam.gserviceaccount.com \
  --role=roles/pubsub.subscriber

# Publish-node side — grant the Noxus SA permission to publish to a topic
gcloud pubsub topics add-iam-policy-binding YOUR_TOPIC \
  --project=YOUR_PROJECT \
  --member=serviceAccount:noxus-pubsub@YOUR_PROJECT.iam.gserviceaccount.com \
  --role=roles/pubsub.publisher
```

## Workflow trigger: Pub/Sub Message Received

A `BaseConsumerTrigger`-backed workflow trigger that holds a persistent streaming-pull connection to a customer-owned pull subscription. Every published message starts a fresh workflow run.

### Configuration

| Field | Description |
| :- | :- |
| **Service account credential** | The connected Google Pub/Sub credential to authenticate with. |
| **Pub/Sub subscription** | Full resource name, e.g. `projects/MY_PROJECT/subscriptions/orders-sub`. **Not the topic** — Pub/Sub publishes to topics and consumers pull from subscriptions on those topics. |

### Output fields

The trigger emits these fields into each workflow run; bind any of them to your workflow's input connectors:

| Field | Type | Description |
| :- | :- | :- |
| `message_id` | `str` | Pub/Sub server-assigned ID, globally unique per subscription. Used for dedup. |
| `data` | `str` | Best-effort UTF-8 decode of the payload. Empty for binary payloads. |
| `data_base64` | `str` | Raw payload, base64-encoded. Always present, use for binary or when you don't trust the encoding. |
| `attributes` | `dict[str, str]` | The published message's attributes. |
| `publish_time` | `str` | ISO-8601 timestamp from the Pub/Sub server. |
| `ordering_key` | `str` | Set only when the topic has message ordering enabled. |

### Delivery semantics

* **At-least-once delivery.** Pub/Sub can redeliver a message if Noxus crashes after receiving but before ack'ing. The trigger dedups on `message_id` (5-minute cache) so the workflow runs exactly once in practice.
* **Ack-after-commit.** Messages are only ack'd after the workflow event row is durably committed. A relay crash mid-processing causes Pub/Sub to redeliver, which the dedup cache absorbs.
* **Concurrency cap.** Each subscription's stream is bounded at 20 in-flight messages so a flooded subscription can't starve other consumers in the same relay process.
* **Failure visibility.** IAM errors, NotFound, Unauthenticated, and generic failures surface on the **Deployment Events** tab (and in the workflow's run history) with the exception class and message — you don't need to read relay logs.

## Workflow node: Publish to Pub/Sub

Publishes a single message to a topic from inside a workflow. Common patterns: emit "order processed" events, send notifications to a downstream pipeline, push to a queue for an external worker.

### Configuration

| Field | Description |
| :- | :- |
| **Topic** | Full topic resource name, e.g. `projects/MY_PROJECT/topics/order-events`. |

### Inputs

| Input | Type | Description |
| :- | :- | :- |
| **Message** | `str` (or `dict` / `list`) | The message body. Dicts and lists are auto-JSON-encoded; everything else is sent as UTF-8 text. |
| **Attributes** | `dict[str, str]` *(optional)* | Pub/Sub message attributes. Reserved keys (`topic`, `data`, `ordering_key`, `retry`, `timeout`) are dropped to prevent accidental shadowing of the SDK call. |
| **Ordering key** | `str` *(optional)* | Set only if the topic has message ordering enabled. |

### Output

| Output | Type | Description |
| :- | :- | :- |
| `message_id` | `str` | The server-assigned ID for the published message. Use it to correlate with a downstream subscription event. |

### Error handling

The node classifies the most common Pub/Sub failures into actionable messages:

* **`PermissionDenied`** → "Service account cannot publish to '…'. Grant `roles/pubsub.publisher` on the topic." Includes the underlying SDK error for debugging.
* **`NotFound`** → "Pub/Sub topic '…' does not exist." Verify the project ID and topic name.
* **Anything else** → wrapped in `IntegrationFailedError` with the exception class name + first 200 chars so the workflow's run log shows what failed without leaking raw gRPC traces.

## Example workflow

A simple "process an order and emit a downstream event" flow:

```
Pub/Sub Trigger: subscription = projects/MY_PROJECT/subscriptions/orders-in
  Output: data (JSON string with order details)
    ↓
Parse JSON: data → order
    ↓
Validate Order: order
    ↓
[business logic: write to DB, charge card, etc.]
    ↓
Publish to Pub/Sub:
  Topic: projects/MY_PROJECT/topics/order-processed
  Message: { order_id: ((order.id)), status: "processed", timestamp: ((now)) }
  Attributes: { source: "noxus", tenant: ((tenant_id)) }
  Output: message_id
    ↓
Send Slack Notification: "Order ((order.id)) processed (pubsub mid=((message_id)))"
```

## Troubleshooting

> [accordion] Trigger activates but no messages arrive
>
> **Verify the publisher side**: the role grant on the subscription only covers consumption, not publishing. If no one is publishing to the topic, the subscription stays empty. Confirm with:
>
> ```bash theme={null}
> gcloud pubsub subscriptions pull projects/YOUR_PROJECT/subscriptions/YOUR_SUB \
>   --project=YOUR_PROJECT --limit=5 --auto-ack
> ```
>
> If this returns messages, the trigger is misconfigured. If it returns nothing, the publisher isn't sending.

> [accordion] Trigger activation fails with 'cannot consume from'
>
> The connected service account is missing `roles/pubsub.subscriber` on the subscription. The error message names the exact SA email and subscription path. Grant the role and retry activation.

> [accordion] Publish node fails with 'cannot publish to'
>
> The connected service account is missing `roles/pubsub.publisher` on the **topic** (not the subscription). Grant the role and re-run the workflow.

> [accordion] Pasted a topic in the subscription field (or vice versa)
>
> Topics and subscriptions are different resources. Pub/Sub publishes to **topics**; consumers pull from **subscriptions** on those topics. The Noxus form validates the resource type and explicitly tells you when the wrong one was pasted.

> [accordion] Activation succeeds but events never trigger the workflow
>
> Pub/Sub guarantees at-least-once delivery; if your subscription has no `ackDeadlineSeconds` or it's set very short, the broker may redeliver before the workflow run starts and you'll see duplicates rather than missing runs. Default subscription settings (10s ack deadline, with the SDK auto-extending) work correctly with Noxus' ack-after-commit semantics.

***

> [card] [Google Workspace](https://docs.noxus.ai/integrations/providers/google.md)
>
> Gmail, Drive, Sheets, Docs, Calendar

> [card] [Google Chat (Pub/Sub mode)](https://docs.noxus.ai/platform/agents/deployments/google-chat.md)
>
> Receive Chat events via Pub/Sub when a public webhook isn't an option

> [card] [Triggers](https://docs.noxus.ai/building/automation/triggers)
>
> All workflow trigger types

> [card] [Authentication](https://docs.noxus.ai/integrations/authentication.md)
>
> OAuth and service-account setup


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.