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

# ETL: Google Cloud Storage Source

> How to connect to Google Cloud Storage and configure the GCS source component to read files in your Integrate.io ETL pipeline.

The Google Cloud Storage source reads files from a GCS bucket and feeds them into your pipeline. It supports CSV, TSV, JSON, Excel, Parquet, Raw, and compressed formats.

Once your connection is set up, see [File Storage Options](/docs/etl/file-storage-options) for the full set of read options (file formats, schema, and more) shared across every file storage provider.

## Connection Setup

### Create a Service Account and JSON Key

<Steps>
  <Step>
    Open the [Google Cloud Console](https://console.cloud.google.com/#/project) and select your project.
  </Step>

  <Step>
    Go to **IAM & Admin > Service Accounts > Create Service Account**.
  </Step>

  <Step>
    Enter a **Service account name** and click **Done**.

    <Frame>
      <img src="https://mintcdn.com/integrateio/XpeHmuMzUiEmfOEz/images/connectivity-and-security/image-164.webp?fit=max&auto=format&n=XpeHmuMzUiEmfOEz&q=85&s=06b24d4555f85526adacb177a90b0dbf" alt="Google Cloud Console service account creation form" width="1200" height="1149" data-path="images/connectivity-and-security/image-164.webp" />
    </Frame>
  </Step>

  <Step>
    Click the newly created service account and go to the **Keys** tab.
  </Step>

  <Step>
    Click **Add Key > Create New Key**, select **JSON**, and click **Create**. Save the downloaded key file.
  </Step>
</Steps>

### Grant Bucket Access to the Service Account

<Steps>
  <Step>
    Open [Google Cloud Storage](https://console.cloud.google.com/storage) and click the bucket you want to connect.
  </Step>

  <Step>
    Under the **Permissions** tab, click **Grant Access**.
  </Step>

  <Step>
    Enter the service account email in the **New Principals** field.
  </Step>

  <Step>
    Assign the appropriate roles:

    | Access level        | Roles required                                             |
    | :------------------ | :--------------------------------------------------------- |
    | Read-only (source)  | Storage Legacy Bucket Reader, Storage Legacy Object Reader |
    | Write (destination) | Storage Legacy Bucket Writer, Storage Legacy Object Reader |
  </Step>

  <Step>
    Click **Save**.

    <Frame>
      <img src="https://mintcdn.com/integrateio/XpeHmuMzUiEmfOEz/images/connectivity-and-security/image-165.webp?fit=max&auto=format&n=XpeHmuMzUiEmfOEz&q=85&s=8fc77c64d0d8e9c8a45c0a918e73d833" alt="Granting bucket access with Storage Legacy roles" width="1114" height="1468" data-path="images/connectivity-and-security/image-165.webp" />
    </Frame>
  </Step>
</Steps>

### Create the Connection in Integrate.io ETL

<Steps>
  <Step>
    Click the **Connections** icon (lightning bolt) in the top-left menu.
  </Step>

  <Step>
    Click **New connection**.

    <Frame>
      <img src="https://mintcdn.com/integrateio/XpeHmuMzUiEmfOEz/images/connectivity-and-security/image-166.webp?fit=max&auto=format&n=XpeHmuMzUiEmfOEz&q=85&s=267c0e0f3b1196ce34566fcbf7afa722" alt="New connection button in the Connections menu" width="1200" height="829" data-path="images/connectivity-and-security/image-166.webp" />
    </Frame>
  </Step>

  <Step>
    Select **Google Cloud Storage**.

    <Frame>
      <img src="https://mintcdn.com/integrateio/XpeHmuMzUiEmfOEz/images/connectivity-and-security/image-167.webp?fit=max&auto=format&n=XpeHmuMzUiEmfOEz&q=85&s=51003641fef24f550f44e9fda4dcee44" alt="Selecting Google Cloud Storage from the connection type list" width="1200" height="829" data-path="images/connectivity-and-security/image-167.webp" />
    </Frame>
  </Step>

  <Step>
    Name the connection and upload the JSON key file.

    <Frame>
      <img src="https://mintcdn.com/integrateio/XpeHmuMzUiEmfOEz/images/connectivity-and-security/image-168.webp?fit=max&auto=format&n=XpeHmuMzUiEmfOEz&q=85&s=7beb0d935d3b16e727e3012f33317543" alt="Google Cloud Storage connection form with JSON key upload" width="1200" height="829" data-path="images/connectivity-and-security/image-168.webp" />
    </Frame>
  </Step>

  <Step>
    Click **Test Connection** to verify the credentials, then click **Create connection**.

    <Frame>
      <img src="https://mintcdn.com/integrateio/XpeHmuMzUiEmfOEz/images/connectivity-and-security/image-169.webp?fit=max&auto=format&n=XpeHmuMzUiEmfOEz&q=85&s=5705651c2f2f2928ee0cbc6dceaaea00" alt="Test Connection and Create connection buttons" width="1200" height="829" data-path="images/connectivity-and-security/image-169.webp" />
    </Frame>
  </Step>
</Steps>

***

## Source Configuration

### Connection

Select your Google Cloud Storage connection from the dropdown, or create a new one using the steps above.

### Bucket

Enter the name of the GCS bucket that contains your source files.

### Source Path

The path to the input file or pattern within the bucket.

| Example                 | Description                         |
| :---------------------- | :---------------------------------- |
| `sales/2015/01/log.csv` | A single file                       |
| `sales/2015/{01,02}/`   | A pattern matching multiple folders |

<Note>
  GCS does not support folder paths (e.g. `sales/2015/01/`). Use a pattern or a single file path instead. You can use wildcard characters for [pattern globbing](/docs/etl/using-pattern-matching-in-source-component-paths).
</Note>

File and directory names beginning with an underscore (`_`) or a dot (`.`) are ignored.

<Snippet file="snippets/file-storage-source-format.mdx" />

### Source Action

<Note>
  All four source actions are available for Google Cloud Storage. When using **Move processed files**, the **Append string to filename** option is supported.
</Note>

<Snippet file="snippets/file-storage-source-action.mdx" />

<Snippet file="snippets/file-storage-source-tail.mdx" />

***

## FAQ

**What permissions does the service account need for a source-only connection?**

Storage Legacy Bucket Reader and Storage Legacy Object Reader. If you also write to GCS (destination component), add Storage Legacy Bucket Writer.

**Why can't I use a folder path like `sales/2015/01/`?**

GCS does not support folder-based listing in the same way S3 does. Use a pattern such as `sales/2015/01/*` or a specific file path instead.

**Can I connect to a bucket in a different GCP project?**

Yes, as long as the service account has been granted the appropriate roles on that bucket.

***

## Related

<CardGroup cols={2}>
  <Card title="Google Cloud Storage Destination" icon="arrow-right" href="/docs/etl/using-components-google-cloud-storage-destination" horizontal />

  <Card title="File Storage Options" icon="arrow-right" href="/docs/etl/file-storage-options" horizontal />

  <Card title="Pattern Matching in Source Paths" icon="arrow-right" href="/docs/etl/using-pattern-matching-in-source-component-paths" horizontal />

  <Card title="Reading File Storage Data Incrementally" icon="arrow-right" href="/docs/etl/how-do-i-read-data-from-file-storage-incrementally" horizontal />

  <Card title="PGP Keys" icon="arrow-right" href="/docs/etl/pgp-keys-account-level" horizontal />

  <Card title="Selecting File Input Format" icon="arrow-right" href="/docs/etl/how-do-i-select-my-file-input-format" horizontal />
</CardGroup>