GCP connection instruction
What you'll need: access to Google Cloud Console with Project Owner permissions on the project you want to connect.
💡 Prefer an automated setup? Instead of manually enabling APIs, creating a service account, and generating a key (Steps 1–3 below), you can run our setup script, which performs these steps for you and outputs the credentials needed for Step 4. Download the GCP setup script.
If you'd rather configure everything manually, follow the steps below.
Step 1. Enable required APIs In Google Cloud Console, go to APIs & Services → Library and enable the following APIs. Click each link below — your current project will be pre-selected automatically:
- Identity and Access Management (IAM) API
- Cloud Resource Manager API
- Compute Engine API
- Cloud Billing API
- Cloud Build API
- Cloud Storage API
- Cloud Monitoring API
For each API: click Enable. If the button says Manage, the API is already enabled — no action needed.
Step 2. Create a dedicated service account Go to IAM & Admin → Service Accounts and click Create service account. Create a new account specifically for emma — do not use the default project service account.
Once created, assign the following roles:
- Compute Admin
- Service Account User
- Service Account Admin
- Role Administrator
- Service Account Key Admin
- Project IAM Admin
Click Done.
Step 3. Create a JSON key In the Service Accounts list, click on the account you just created. Go to the Keys tab → Add Key → Create new key → select JSON → click Create. The key file will download automatically to your machine.
Step 4. Enter credentials in emma In the selected provider's input table, fill in the following fields. All values are found inside the downloaded JSON file:
| emma field | JSON key | Example |
|---|---|---|
| Client ID | client_id | 123456789012345678 |
| Project ID | project_id | my-project-id |
| Client email | client_email | [email protected] |
| Private key ID | private_key_id | a1b2c3d4e5... |
| Private key | private_key | -----BEGIN RSA PRIVATE KEY-----... |
Important: when copying private_key manually, make sure to include the full value including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- headers, and preserve the trailing newline character (\n) at the end. Removing it will cause the connection to fail.
Alternatively, use the Upload JSON file button to populate all fields automatically from the downloaded key file.
Click Connect account. emma will validate the connection. On success, the provider status will change to CONNECTED and the discovery button will become available.
Troubleshooting If the connection fails, the status will remain NOT CONNECTED and an error message will appear.
| Symptom | Likely cause | Fix |
|---|---|---|
| Permission denied error | One or more required roles not assigned | Check Step 2 role list, add any missing roles to the service account |
| API not enabled error | Required API is disabled | Return to Step 1 and enable the flagged API |
| Invalid key error | private_key copied incorrectly | Redownload the JSON file and use the Upload button instead of copying manually |
| Connection fails after upload | Trailing \n stripped by the UI | Copy private_key value manually, ensuring the trailing newline is preserved |
| Project not found | Wrong project selected in Console | Make sure you are in the correct project before creating the service account and key |
Previous entries are not saved — you can re-enter new credentials at any time without restrictions.
Last updated on 14 Jul 2026