> For the complete documentation index, see [llms.txt](https://docs.biodock.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biodock.ai/files/google-cloud-storage-integration.md).

# Google Cloud Storage integration

*What you'll get: your Google Cloud Storage buckets connected to Biodock, and images imported from them into a folder in **Files**.*

{% hint style="info" %}
**Available on request.** The Google Cloud Storage integration is turned on per account. If you don't see a **Google Cloud Storage** tab in **Files**, [contact us](https://docs.biodock.ai/about/contact-us.md) to ask for it.
{% endhint %}

Biodock connects through a Google Cloud service account that you create and control. You give it read access to the buckets you choose, then paste its JSON key into Biodock.

## Before you start

You need:

* A Google Cloud project with at least one bucket holding images in a [supported format](https://docs.biodock.ai/files/supported-image-types.md).
* Permission to create a service account and change IAM permissions in that project.

## 1. Set up Google Cloud

The service account needs two permissions: one on the project, to list your buckets, and one on each bucket you want to use, to read its files. The project permission shows bucket names only.

#### Create a service account

1. In the Google Cloud console, open **IAM & Admin** → **Service Accounts**. Check that the right project is selected.
2. Click **Create Service Account**, enter a name such as `biodock-import`, and click **Create and Continue**.
3. Skip the step that grants the service account access to the project, and click **Continue** → **Done**.
4. Copy the service account's email address. It looks like `biodock-import@your-project-id.iam.gserviceaccount.com`.

#### Let it list your buckets

1. Open **IAM & Admin** → **IAM** and click **Grant Access**.
2. Under **New principals**, paste the service account's email.
3. Under **Assign roles**, choose **Storage Bucket Viewer**. (**Storage Legacy Bucket Reader** also works, if your console shows it.)
4. Click **Save**.

#### Let it read a bucket

1. Open **Cloud Storage** → **Buckets** and click your bucket.
2. On its **Permissions** tab, click **Grant Access**.
3. Under **New principals**, paste the same email. Under **Assign roles**, choose **Storage Object Viewer**.
4. Click **Save**.

Repeat this for every bucket you want to use in Biodock. Buckets you skip stay unreadable.

#### Create a JSON key

1. Go back to **IAM & Admin** → **Service Accounts** and click your service account.
2. On its **Keys** tab, choose **Add Key** → **Create new key**, pick **JSON**, and click **Create**.

Google Cloud downloads a `.json` file. Keep it safe: anyone with it can read what the service account can read.

## 2. Connect to Biodock

1. In Biodock, click **Files** in the sidebar and open the **Google Cloud Storage** tab.
2. Open the `.json` file and copy **all** of it, from the opening `{` to the closing `}`.
3. Under **Connect your bucket**, paste it into **Service account JSON key**.
4. Click **Connect**.

The tab now lists the buckets the service account can see.

## 3. Import files

Importing works just like [importing from Amazon S3](https://docs.biodock.ai/files/aws-s3-integration.md):

1. Click a bucket to open it. Open folders as needed. The path above the list, starting at **Home**, takes you back up, and **Search by prefix** finds names that start with what you type.
2. Tick the files you want. Folders can be opened but not ticked, and files in a format Biodock can't read are greyed out.
3. Click **Import to Biodock**.
4. In the **Import from Google Cloud Storage** dialog, choose the folder to import into under **Destination**. Under **Options**, you can tick **Adaptive normalization**.
5. Click **Import here**.

Follow the progress with **Recent uploads** (the upload icon in the top bar). Imports count against your storage and have the same [upload limits](https://docs.biodock.ai/files/uploading-images.md#upload-limits) as uploads.

To import a VSI image, put the `.vsi` file and its folder of `.ets` files in a `.zip` archive, and import the `.zip`.

## Disconnect

Open the **Google Cloud Storage** tab, click **Disconnect** next to **Import to Biodock**, and confirm. Biodock permanently deletes the stored key. To cut access on the Google side as well, remove the service account's permissions, or disable or delete its key, in the Google Cloud console.

## Troubleshooting

| What you see                                                                                                                                      | What to do                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| No buckets appear, or a message that the service account lacks `storage.buckets.list`                                                             | Give the service account **Storage Bucket Viewer** in **IAM & Admin** → **IAM**.                                                |
| **Failed to import images from Google Cloud Storage. Please ensure your service account has read permissions on the selected objects.**           | Give the service account **Storage Object Viewer** on that bucket's **Permissions** tab.                                        |
| **Missing "private\_key" — this must be a GCP service account key.** (or the same for `client_email`), or **That does not look like valid JSON.** | Paste the whole JSON file again, from `{` to `}`.                                                                               |
| Google Cloud says **Email addresses and domains must be associated with an active Google Account**                                                | Copy the service account's real email from **IAM & Admin** → **Service Accounts**. Don't replace parts of it with placeholders. |
| **Storage Legacy Bucket Reader** isn't offered                                                                                                    | Use **Storage Bucket Viewer** instead.                                                                                          |

## Permissions used

| Biodock action           | Google Cloud permission | Granted on            |
| ------------------------ | ----------------------- | --------------------- |
| Show your buckets        | `storage.buckets.list`  | Project               |
| Browse files and folders | `storage.objects.list`  | Each bucket you allow |
| Import a file            | `storage.objects.get`   | Each bucket you allow |

Biodock never needs to create, change or delete anything in your buckets. The JSON key is stored encrypted and is only used to talk to Google Cloud Storage. An imported file is copied into Biodock's storage and processed like any upload.

Need help? [Contact us](https://docs.biodock.ai/about/contact-us.md) with the error message, your Google Cloud project ID and the bucket name. **Never send your JSON key or private key** by email or chat.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.biodock.ai/files/google-cloud-storage-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
