# GCP Integration

Source: https://docs.ops0.com/docs/settings/integrations/gcp

ops0 connects to Google Cloud using project-level access and a service account. You can use the integration for discovery, infrastructure changes, and inventory across the target project.

---

## Adding the Integration

### Navigate to Integrations
Go to **Settings** > **Integrations** > **Add Integration**.

### Select Google Cloud
Choose **Google Cloud** from the provider list.

### Enter Project Details
Provide the target project ID and upload the service account key.

### Connect
Click **Connect** to verify access.

---

## Authentication Methods

ops0 supports two ways to authenticate with GCP:

| Method | Best for |
|--------|----------|
| **Service Account Key (JSON)** | Automated/CI use — stable long-lived credentials |
| **Google OAuth** | Interactive setup — authenticates as your Google account |

### Service Account Key

Upload a JSON key file for a GCP service account. This is the standard method for production integrations.

### Google OAuth

Click **Connect with Google** to authenticate via your Google account. ops0 redirects you to Google's consent screen, you approve access, and ops0 stores the refresh token. Tokens are refreshed automatically before they expire.

**OAuth for personal accounts**

OAuth is convenient for personal GCP projects or quick trials. For shared team integrations, service account keys are more reliable since they don't depend on a personal account's continued access.

---

## Integration Fields

| Field | Required | Description |
|-------|----------|-------------|
| **Name** | Yes | Integration name |
| **Project ID** | Yes | GCP project ID |
| **Service Account Key** | Yes (if using key auth) | JSON key file for the service account |

---

## Scope Configuration

By default the integration scans a single GCP project. To scan across a folder hierarchy or your entire organization, configure the scope:

### Scope Types

| Scope | Description |
|-------|-------------|
| **Project** | Scan resources in a single GCP project (default) |
| **Folder** | Scan all projects under a GCP folder |
| **Organization** | Scan all projects in your GCP organization |

### Additional Fields for Folder and Organization Scope

| Field | When Required | Description |
|-------|---------------|-------------|
| **Organization ID** | Organization scope | Your GCP organization numeric ID |
| **Folder ID** | Folder scope | The folder numeric ID to scan under |
| **Included Projects** | Optional | Limit to specific project IDs |
| **Excluded Projects** | Optional | Skip specific project IDs |

### Additional IAM Roles for Folder/Org Scope

- `roles/resourcemanager.folderViewer` — to enumerate projects under a folder
- `roles/resourcemanager.organizationViewer` — to enumerate all projects in the org
- `roles/cloudasset.viewer` — for Cloud Asset Inventory scanning

**Grant Roles at the Right Level**

For folder and organization scope, the service account must be granted roles at the folder or organization level, not just at the project level. Grant the roles on the folder/org node in IAM.

---

## Creating the Service Account

### Open IAM & Admin
Go to GCP Console and open **IAM & Admin**.

### Create a Service Account
Create a dedicated service account for ops0.

### Grant Required Roles
Assign the roles needed for discovery or deployment based on your use case.

### Download the JSON Key
Generate the key file and upload it in the integration form.

---

## Required GCP Roles

### For IaC Deployments

- `roles/editor` or a custom least-privilege set covering the resources you manage

### For Discovery

- `roles/viewer`
- `roles/compute.viewer`
- `roles/storage.objectViewer`

**Least Privilege**

If you don't want to use `roles/editor`, create a custom role that covers only the services ops0 should read or manage.

---

## Switching GCP Projects

After an integration is connected, you can change which GCP project it targets without re-creating the integration:

1. Open **Settings → Integrations** and click the GCP integration
2. Click **Change Project**
3. Select from the list of GCP projects available to the service account or OAuth user
4. Click **Save**

The integration updates immediately. Future discovery scans and deployments use the newly selected project.

---

## Troubleshooting

- **Permission Denied**: Confirm the service account has the required roles on the project.

- **Invalid JSON Key**: Re-download the key and make sure the uploaded file is a valid service account credential.

- **Wrong Project**: Double-check the project ID in the integration matches the project where resources live.

---

## Related

- [Connect Your Cloud](https://docs.ops0.com/docs/getting-started/connect-cloud#gcp): Quick-start onboarding for GCP and other providers.

- [Integrations Overview](https://docs.ops0.com/docs/settings/integrations): Return to the shared integrations documentation.