# Connect Google Cloud

Google Cloud and Firebase costs come from your billing export in BigQuery. ShipVitals reads it as your workspace's own Google principal, a service account made for this workspace alone, so you grant it read access instead of handing over a key. Usage (Cloud Monitoring) and deploy history (Hosting and Cloud Run) come the same way.

Only the owner and admins can do this (see [Connect a service](connect-a-service.md)). It takes about 3 minutes once the billing export exists.

## Open the setup

In **Connections**, press **Set up Google Cloud** on the first visit, or find **Google Cloud** in **All services**, or press **Connect Google Cloud** in **Suggested**. The page says **Connect Google Cloud** ("Costs, usage and deploys · …") with three numbered steps: **Billing export**, **Grant read access** and **Check access** ("Step 1 of 3").

Your place is saved on every step: the header then says **Saved · continues on any device**.

## Step 1: Billing export

The step asks **Where is your billing export?**

1. In **Billing export dataset**, type the dataset as `project.dataset`, for example `my-project.billing_export` (datasets used before in the workspace are offered as you type). You can also paste what you have: the export table's name as BigQuery shows it (`project.dataset.table`), a BigQuery address from the Cloud Console, or the **Project ID** and **Dataset name** copied from Billing export. ShipVitals reads the dataset from it, and the table when it names one.
2. Leave **Also read usage (Cloud Monitoring)** and **Also read deploy history (Hosting and Cloud Run)** ticked to get those too. Each says which roles it adds.
3. If one dataset holds several billing accounts, open **One dataset holding several billing accounts?** and type the **Export table** to read. A pasted table name fills it for you.
4. Press **Continue** (or `Enter`).

### Find your billing export

**Open Billing export in the Cloud Console**, under the field, opens the page where Google shows it: under the export that is enabled, the **Project ID** and **Dataset name** together are `project.dataset`.

With several billing accounts, or when you aren't sure which project holds it, open **Where do I find it?**. It has a command, **Find my billing exports**, that lists every dataset a billing export writes to, one `project.dataset` a line. Copy it, press **Open Cloud Shell**, run it there, and paste a line into the field.

### No billing export yet

Open **Not set up yet?** and follow its steps:

1. Press **Open Billing export in the Cloud Console** and choose the billing account that pays for your projects.
2. Under **Detailed usage cost**, press **Enable detailed export**. (**Standard usage cost** works too; with both on, ShipVitals reads the account once.)
3. Choose a project to hold it, create a dataset there (`billing_export` is a good name) and save.
4. Come back and write it in the field as that project, a dot, then the dataset.

Google writes the first rows a few hours after you turn the export on. Until then **Check access** says "ShipVitals can read … but there's no billing export table in it yet."; your place is kept, so check again later. Google exports cost only from that day (plus about a month back).

If the dataset isn't in the right shape, the field says "Write it as project.dataset, for example …".

## Step 2: Grant read access

The step shows "Grant read access to …'s own Google principal:" with its address and **Copy the principal**.

1. Choose how to run the grant: **gcloud**, **Terraform** or **Console steps** (numbered clicks in the Cloud Console).
2. Copy the snippet (focus it and press `⌘C` / `Ctrl C`, or press **Copy snippet**). **Open Cloud Shell** opens a Cloud Shell in a new tab to paste it into.
3. Run it. Under the snippet, a note says what it allows and how to take it back.
4. Press **Continue to Check access** (or `Enter`).

The bar at the bottom says "Waiting for access. The hub shows this as “Waiting for access · Google Cloud” until Check access passes." You can leave now and come back later (see [Come back later](#come-back-later)).

### Someone else owns billing

Press **Copy for a colleague**. ShipVitals copies a plain message with the snippet, what it grants and how to remove it: "Copied. Paste it into your own chat or email." ShipVitals sends nothing to them. The message also appears below the button; if copying is blocked ("Copying was blocked. Select the message below and copy it."), select and copy it yourself.

### On a phone

A phone also shows **Email me this snippet**. It's sent to your own address: "Sent to …. Run it on a desktop; Check access works here once it has run." Then run it on a desktop and come back to the phone for step 3.

## Step 3: Check access

1. Press **Check access** (or `⌘Enter` / `Ctrl Enter`, from step 2 or 3).
2. ShipVitals checks each grant one at a time: the dataset, the export table, its newest row, the scan size, the projects, then usage and deploys on each. The checks appear as they finish.
3. The result:
   - When everything passed: "Billing, usage and deploys work for all …." Press **Done** (or `Enter`). You land on **Connected**, with a connection for each part you chose: **Google Cloud billing**, and **Google Cloud usage** and **Firebase Hosting and Cloud Run releases** (deploys) when chosen. On your plan they count as one connection.
   - When only part of it works: billing works, but some projects are missing usage or deploys ("Billing works for all …. Usage is missing on …."). This is normal, and what works is saved. Press **Copy the fix** beside the lines that grant the access still missing to copy just those lines, run them, then press **Check again**. Or press **Done for now** and fix it later from the connection's **Copy the fix** (see [Connection health](connection-health.md)).
   - When it failed: the line says what to do, with the missing lines to copy too. Fix it and press **Check again**.

## Other ways to connect: a JSON key

If you'd rather use a service account you made yourself:

Give the account the same read roles the snippet grants. With a key, ShipVitals' queries run in the account's own project, not in ShipVitals', so it also needs to run BigQuery jobs there: grant it **BigQuery Job User** on its own project (and enable the BigQuery API there). That is the only permission beyond reading the check accepts, and only in that project; the queries are billed to it.


1. On step 3, open **Other ways to connect**.
2. Drop the key on **Choose the JSON key**, or press it and choose the file. It says "… is ready. It's sent once, to check and store it, and never kept in your saved place."
3. Press **Connect with this key** (**Remove the key** lets it go).

ShipVitals accepts the key only if its account can do no more than read:

- **Connected with the key.** Press **Done**.
- "Billing is connected. This key couldn't read usage; grant it and connect again to add them." Billing is saved; grant the rest and connect again.
- Refused because the account can do more: "Remove these permissions, or the roles that hold them:" with the list, and "ShipVitals needs only …." Remove them in Google Cloud and try again, or use the snippet instead.

## Come back later

The wizard keeps its place (the dataset, the options, the snippet format and the step, never a key) for 14 days, for you, on any device.

1. Open **Connections**. The line under the heading says **Waiting for access · Google Cloud** while the wizard waits at step 2 or 3, and **Suggested** shows "Continue Google Cloud · step 2 of 3" under **Resume**.
2. Press either. The wizard opens at the same step, with the same snippet.

## When it doesn't work

| The page says | What to do |
|---|---|
| "Write it as project.dataset, for example …" | Type the dataset as the project, a dot, then the dataset's name. |
| "Use the table's name as BigQuery shows it: letters, digits, _ and -." | Fix the **Export table**, or leave it empty. |
| "The snippet didn't load." | Reload the page. Your place is kept. |
| "The check didn't finish. Try again in a minute." | Wait a minute and press **Check again**. |
| "You've run many checks in the last hour. Try again at …." | Wait until then. |
| "You've emailed this snippet several times in the last hour. Try again later." | Copy it instead, or wait. |
| "Saved, but paused: your plan has no room for another connection. …" | Remove a connection or change plan; it starts syncing then. |
| "Google Cloud can't be connected on this server yet." | This ShipVitals server isn't set up for Google Cloud. Ask its operator. |
