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

# Set up a Google Cloud Storage destination

> Create a GCS bucket, service account, and HMAC key so Cometly can write export files to your bucket.

## Overview

A **GCS destination** is a reusable connection to a Google Cloud Storage bucket you own. Like an S3 destination, Cometly writes Parquet files to your bucket and stops — there's no load phase. You load the files into BigQuery, Databricks, or another engine yourself, on your own schedule.

Cometly authenticates with an **HMAC interoperability key**, not a service-account JSON key. You generate one for a service account that has write access to your bucket.

## Prerequisites

* A Google Cloud project with permission to create Cloud Storage buckets, service accounts, and IAM bindings.
* A space administrator role in Cometly.

## Create the bucket and credentials

**1. Create or choose a bucket**

In the Google Cloud Console, create a Cloud Storage bucket (or choose an existing one) for Cometly
exports, and note its **name**.

**2. Create a service account**

Create a dedicated service account (for example, `cometly-exports`) for programmatic access only.

**3. Grant it access to the bucket**

The export only ever **lists the bucket's prefix and writes objects** — it never deletes anything.
Create a [custom role](https://cloud.google.com/iam/docs/creating-custom-roles) with exactly these
permissions:

* `storage.objects.list` — the export lists its output prefix
* `storage.objects.create` — the export writes the Parquet files
* `storage.multipartUploads.create`, `storage.multipartUploads.abort`, and
  `storage.multipartUploads.listParts` — large files upload in parts through the S3-compatible API

Grant the role to the service account **on the bucket** (Bucket → Permissions → Grant access), not
on the project.

Because the role excludes `storage.objects.delete`, the connection check on save can't clean up its
tiny `.cometly-connection-test/…` probe object — that's expected; remove it manually if you like.

**4. Generate an HMAC interoperability key**

In Cloud Storage, go to **Settings → Interoperability**, and create an **HMAC key** for the
service account. Save the **Access key** and **Secret** — the secret is shown only once.

**5. Add the destination in Cometly**

In the dashboard, go to **Integrations → Google Cloud Storage → Add destination** and enter:

**Name** `string` *required*

A label for this destination, for example "Production warehouse".

**Bucket name** `string` *required*

The GCS bucket name from Step 1.

**HMAC access ID** `string` *required*

The access key from the interoperability key you generated, for example `GOOG1E…`.

**HMAC secret** `string` *required*

The secret from the interoperability key. Shown only once when you generate it in Cloud Storage.

Cometly runs a quick, best-effort connection check on save. Because permissions scoped to a prefix
can legitimately deny a whole-bucket check, a failed check is logged but never blocks the create —
if your key and bucket are correct, the destination still works even if the check couldn't confirm it.

> [!NOTE]
>
> Your HMAC secret is encrypted at rest and never shown again. When editing a destination, leave the
> secret blank to keep the existing key.

> [!WARNING]
>
> Scope the service account to only the bucket used for exports. Avoid reusing a broadly privileged
> service account.

## File layout

A GCS destination writes the same Hive-style partitioned Parquet layout as an S3 destination — see
[File layout (S3 and GCS destinations)](https://docs.cometly.com/data-warehouse/create-export.md#file-layout-s3-and-gcs-destinations)
for the path structure, partition columns, and the `_SUCCESS` marker.

## Using with BigQuery

BigQuery can read these files directly from your bucket, without a load step:

* Create an [external table](https://cloud.google.com/bigquery/docs/external-data-cloud-storage) over
  the `…/<dataset>/space_id=<id>/` prefix to query the Parquet files in place.
* Or run a load job to copy the data into a native BigQuery table — Cloud Storage load jobs are free.

Prefer a native load without managing external tables or load jobs yourself? Use a
[BigQuery destination](https://docs.cometly.com/data-warehouse/bigquery-destination.md) instead — Cometly loads directly into a
table in your dataset, the same way the Snowflake destination does, with no file layout to manage.

## Next step

> [card] [Create an export](https://docs.cometly.com/data-warehouse/create-export.md)
>
> Choose this destination, a dataset, and a date range.


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