# Google Cloud Storage Sink Configuration Guide

This guide walks you through creating a service account, assigning least-privilege permissions, and gathering the information required to configure Google Cloud Storage (GCS) as a Sink provider with Synqly's Sink connector. Events are written to your GCS bucket as compressed JSON files.

## Prerequisites

Before you begin, ensure you have:

- A Google Cloud project with billing enabled
- Access to the [Google Cloud Console](https://console.cloud.google.com) with permission to create service accounts and manage IAM
- An existing GCS bucket, or permission to create one


## Required Permissions

The Synqly Sink connector writes event files to your GCS bucket. The minimum IAM permissions required on the target bucket are:

| Permission | Purpose |
|  --- | --- |
| `storage.objects.create` | Write event files to the bucket |
| `storage.objects.delete` | Overwrite existing files (required by GCS for object creation) |


The built-in **Storage Object User** role (`roles/storage.objectUser`) covers these permissions and is the recommended choice. If you prefer true least-privilege, you can create a custom role with only the permissions listed above.

Scope the service account's role to the specific bucket used for this integration. See step 2 below for instructions on adding an IAM condition.

## 1. Create a GCS Bucket

If you already have a bucket, skip to step 2 and note the bucket name.

1. In the Google Cloud Console, navigate to **Cloud Storage > Buckets**.
2. Click **Create**.
3. Enter a globally unique name for the bucket and select a location.
4. Configure the remaining settings to match your organization's requirements and click **Create**.


Note the **bucket name** — you will need it when configuring the integration.

For more details, see [Creating storage buckets](https://cloud.google.com/storage/docs/creating-buckets).

## 2. Create a Service Account

1. In the Google Cloud Console, navigate to **IAM & Admin > Service Accounts**.
2. Click **Create Service Account**.
3. Enter a name (for example, `synqly-sink`) and an optional description. Click **Create and Continue**.
4. Under **Grant this service account access to project**, click **Select a role** and choose **Cloud Storage > Storage Object User**.
5. Click **Add IAM Condition** to scope the role to your target bucket. In the condition builder, set:
  - **Condition type**: Resource — Name
  - **Operator**: Starts with
  - **Value**: `projects/_/buckets/<your-bucket-name>`
This ensures the service account can only write to the specified bucket.
6. Click **Save** on the condition, then click **Continue**.
7. Click **Done** to create the service account.


If you prefer a custom role instead of the built-in Storage Object User role, navigate to **IAM & Admin > Roles**, click **Create Role**, and add only the `storage.objects.create` and `storage.objects.delete` permissions. Then assign that custom role to the service account in step 4 above.

## 3. Create a Service Account Key

1. In the **Service Accounts** list, click the service account you created in step 2.
2. Go to the **Keys** tab and click **Add Key > Create new key**.
3. Select **JSON** as the key type and click **Create**.
4. A JSON key file will download to your machine. Store it securely — this file contains the credentials Synqly will use to authenticate.


The JSON key file is shown only once at download time. If you lose it, you will need to create a new key. Treat this file as a secret and do not commit it to version control.

You will paste the **entire contents** of this JSON key file as the credential secret when configuring the integration.

## Configure the Integration

Create your integration by supplying all configuration values.

| Integration Parameter | Description |
|  --- | --- |
| Credential | Paste the **full contents** of the service account JSON key file downloaded in step 3. This is the entire JSON object, not an individual field from it. |
| Bucket | The name of the GCS bucket created in step 1. |
| Path | A prefix path for event files inside the bucket. |


The **Path** field controls where event files land inside your bucket. Events are written to `{path}/{location}/{YYYY/MM/DD}/{timestamp}.json.gz`. For example, if you set the path to `events/sink`, files will be written to paths like `events/sink/my-location/2026/04/28/2026-04-28T12:00:00.000000000Z.json.gz`. Choose a path that makes it easy to organize and query your event data.

## Additional Resources

- [Creating storage buckets](https://cloud.google.com/storage/docs/creating-buckets)
- [Creating service accounts](https://cloud.google.com/iam/docs/service-accounts-create#creating)
- [Creating service account keys](https://cloud.google.com/iam/docs/keys-create-delete#iam-service-account-keys-create-console)
- [Cloud Storage IAM roles](https://cloud.google.com/storage/docs/access-control/iam-roles)