Connect a GCP Project
Cloud kicks off by binding a Google Cloud project to your GSS setup and confirming the four APIs the rest of Cloud depends on are turned on. Everything downstream (Cloud Run services, the custom-domain mapping, monitoring) lives inside that project, so the bind has to come first.
Nothing is created in GCP here. GSS does not deploy Cloud Run, set up monitoring, or change settings on the project itself — that happens later in Cloud. This page only confirms the project exists, is reachable from your account, and has the right APIs enabled.
Happy path
- Step 1 — click Find projects to populate the picker from Cloud Resource Manager.
- Step 2 — pick a GCP project in the picker and click Save project.
- Step 3 — click Check; all 5 requirement rows turn green.
- Continue to Tagging Services.
Glossary▶
- GCP project
- A Google Cloud project — the scope at which APIs are enabled, billing is attached, and Cloud Run services live. Identified by a project ID like
my-site-sst. - Project ID
- The immutable identifier for a GCP project (not the human-readable name). Used in API calls and resource paths.
- Service / API
- A Google Cloud product (Cloud Run, Cloud Monitoring, Tag Manager, GA4 Admin) that has to be explicitly enabled per project before you can call its API.
- Lifecycle state
- The GCP project's status:
ACTIVEmeans usable;DELETE_REQUESTEDmeans scheduled for deletion. - Discovery
- The Resource Manager call GSS runs (per page) to list the projects your Google account can see. The picker in Step 2 is populated from the most recent discovery.
Not covered on this page: connecting your Google account (Getting Started), creating GCP projects (Cloud Console), or deploying Cloud Run services (Tagging Services).
Before you start
- Connected your Google account in the app (Getting Started).
- Have a GCP project with billing enabled. If you don't, create one and link a billing account first.
- Have at least Editor or Owner role on the project — Viewer is not enough to deploy Cloud Run services later.
Decision record
Once a project is bound the page surfaces a GCP project decision record above the steps with three rows: which project is bound, when requirements were last checked, and the current requirement rollup.
| Field | Where it comes from | What "done" looks like |
|---|---|---|
| GCP project | Set in Step 2 below. Resolves to a project name + project ID (e.g. my-site-sst). |
A project name and ID are shown. |
| Last checked | Timestamp from the most recent Step 3 run. | Shown in your local time. |
| Requirements | Rollup of Step 3. Counts the requirement rows that have passed. | Verified after Step 3's Check button has run all 5 requirements green. |
1 Discover the Google Cloud Projects Available to Your Account
Click Find projects. GSS calls Cloud Resource Manager and lists every project your connected Google account can see. The button changes to Refresh projects after the first run, with a "Last refreshed" timestamp next to it. Discovery is per-page — the list does not refresh automatically, so a project you just created in the Cloud Console shows up the next time you click Refresh.
If a project you expect doesn't appear, your Google account doesn't have at least Viewer on it. Add the right IAM role in the Cloud Console first, then click Refresh projects again.
2 Which GCP Project Should Host Server-Side Tagging?
Step 2 stays locked until Step 1 has run discovery at least once. After that, the picker lists every project discovery returned. Each row shows the project's display name and links its project ID out to the Cloud Console dashboard.
Pick the project where Cloud Run will host the tagging container, then click Save project. Save stays disabled until your selection differs from what is already bound, so it is impossible to accidentally re-save the same project.
No GCP project yet? Create one in the Cloud Console — name it something descriptive like my-site-sst. After it exists, go back to Step 1 and click Refresh projects.
Changing the bound project later
If a project is already bound and you pick a different one, Save shows a warning that saving will clear the Step 3 requirement results. The bind itself does not delete anything in GCP — it just points GSS at a different project. The Cloud Run services and custom-domain bindings made in later Cloud steps are tied to the project you saved here, so you would need to re-do those steps inside the newly bound project.
Saved project missing from a fresh discovery
Discovery is advisory — the saved binding is authoritative. If the saved project no longer appears in the latest discovery results (for example, IAM was revoked), the picker shows a note ("Saved project is not in the latest discovery results") and the decision record falls back to the project name stored at save time. Refresh projects to update the list, or pick a different project to rebind.
3 Can GSS Deploy Server-Side Tagging Into This Project?
Step 3 is locked until a project is saved in Step 2. Once it unlocks, click Check to run the five requirement rows: one that confirms the project is reachable and active, plus one per required Google API. APIs are enabled per project — turning on Cloud Run in some other project does not enable it here. Each failed row links you to the GCP Console page where you can fix it.
GSS only reads the project's enabled-services list — it never enables APIs on your behalf. You keep full control over what is turned on in your GCP project.
GCP requires an active billing account before any of these APIs can be enabled, so a project that is missing billing will show all four API rows failing.
3.1Project access
The bound GCP project must be reachable and in the ACTIVE lifecycle state.
Where to check: Cloud Console → Home. The project should load and not show a "scheduled for deletion" banner.
Fix: If the project was deleted or is scheduled for deletion, restore it (within the 30-day grace period) or pick a different project in Step 2.
Deep dive ▶
What it checks. Cloud Resource Manager returns the project, and its lifecycleState is ACTIVE.
How GSS performs the check. One API call: cloudresourcemanager.v1.projects().get(projectId). Reads the response's lifecycleState field.
What counts as pass. lifecycleState == "ACTIVE". Anything else (including DELETE_REQUESTED) fails.
Why it might fail. Project was deleted in GCP. Project is scheduled for deletion. Your Google account lost access (someone removed your IAM role). Required scopes missing — surfaces as a 403 from Cloud Resource Manager. Network/credential failure during the API call.
How to recover. If the project is gone, pick a different one in Step 2. If it's DELETE_REQUESTED, restore it from the Cloud Console (Manage Resources) within the 30-day grace period. If access was revoked, ask the project owner to restore your IAM role. If credentials failed, reconnect Google access in the app.
3.2Cloud Run Admin API is enabled
Required to deploy and manage the Cloud Run tagging services in the next Cloud step.
Where to check: run.googleapis.com — Open in GCP Console ↗
Fix: Click Enable on the API library page, then click Check again in the app. Enablement is near-instant but can lag a few seconds.
Deep dive ▶
What it checks. run.googleapis.com appears in the project's enabled services list.
How GSS performs the check. One Service Usage API call (shared across 3.2–3.5): serviceusage.v1.services().list(parent="projects/{id}", filter="state:ENABLED", pageSize=200). The response is checked for the API name.
What counts as pass. The API name is in the enabled-services list returned by the call.
Why it might fail. The API is not enabled (most common — GCP doesn't enable any APIs by default on a new project). The Service Usage call itself failed, in which case all four API checks fail with the same error message — they share one underlying call.
How to recover. Enable via the GCP Console link above. If all four API checks failed simultaneously with the same error, the cause is the shared Service Usage call (credentials, network, or Service Usage API itself not enabled — enable that first).
3.3Cloud Monitoring API is enabled
Used to read service health metrics and verify deployed Cloud Run containers are running correctly during Publish and Go Live.
Where to check: monitoring.googleapis.com — Open in GCP Console ↗
Fix: Click Enable on the API library page. Re-run Check.
Deep dive ▶
What it checks. monitoring.googleapis.com in the enabled-services list.
How GSS performs the check. Same shared Service Usage call as 3.2; no separate request.
What counts as pass. The API name is in the enabled set.
Why it might fail. Not enabled. Or shared Service Usage call failed (see 3.2 deep dive).
How to recover. Enable via the link above; re-run Check.
3.4Tag Manager API is enabled
Needed to inspect and configure GTM container workspaces during the rest of the build, plus the Activate step in Tagging Endpoint that writes the server container's tagging-server URL.
Where to check: tagmanager.googleapis.com — Open in GCP Console ↗
Fix: Click Enable on the API library page. Re-run Check.
Deep dive ▶
What it checks. tagmanager.googleapis.com in the enabled-services list.
How GSS performs the check. Same shared Service Usage call as 3.2.
What counts as pass. The API name is in the enabled set.
Why it might fail. Not enabled. Or shared Service Usage call failed.
How to recover. Enable via the link above. Note: this enables the Tag Manager API quota for the GCP project; access to specific GTM containers still depends on your Google account's GTM container roles, set in GTM itself.
3.5Analytics Admin API is enabled
Used to read GA4 property and data stream configurations during the audit, GA Properties setup, and tagging steps.
Where to check: analyticsadmin.googleapis.com — Open in GCP Console ↗
Fix: Click Enable on the API library page. Re-run Check.
Deep dive ▶
What it checks. analyticsadmin.googleapis.com in the enabled-services list.
How GSS performs the check. Same shared Service Usage call as 3.2.
What counts as pass. The API name is in the enabled set.
Why it might fail. Not enabled. Or shared Service Usage call failed.
How to recover. Enable via the link above. Like the Tag Manager API, this enables quota in the GCP project; GA4 property access itself depends on your account's GA4 roles, set in GA4 Admin.
Billing
Google requires an active billing account before any of these APIs can be enabled. If all four API checks pass, billing is implicitly confirmed. To verify or attach billing: Cloud Console → Billing.
Cloud Run's free tier covers ~2 million requests/month — enough for most small and medium sites at no cost. Above the free tier, server-side tagging typically runs $5–50/month depending on traffic.
Common errors & failure modes
Cross-cutting failures on this page. Most are configuration issues in GCP rather than bugs in GSS.
| Symptom | Likely cause | Where to fix |
|---|---|---|
| Discovery and binding | ||
| Project doesn't appear in the picker | Project was created after your last discovery refresh; or your Google account doesn't have a role on the project. | Click Refresh projects in Step 1. If still missing, check IAM & Admin — your account needs at least Viewer. |
| "Could not list GCP projects" on Find / Refresh | Cloud Resource Manager API is not reachable, or your Google credentials expired. | Reconnect Google access in the app. If the error persists, check cloud.google.com/status for incidents. |
| Requirement checks | ||
| Step 3 button is disabled | No GCP project bound yet. Step 3 stays locked until Step 2's Save project has run. | Pick a project in Step 2, click Save project, then Check. |
| 3.2–3.5 all fail with the same error message | Service Usage API itself is not enabled, or credentials failed. The four API rows share a single underlying Service Usage call. | Enable serviceusage.googleapis.com in the GCP Console; reconnect Google access if credentials were the issue; re-run Check. |
| "Validation failed — please try again." next to Check | Network or credential failure during validate. Existing check rows are preserved (HTMX skips the swap on non-2xx responses). | Retry once. If it persists, reconnect Google access. |
| Project changes after binding | ||
| 3.1 fails with "Project DELETE_REQUESTED" | The bound GCP project was scheduled for deletion. There's a 30-day grace period before it's permanently gone. | Manage Resources → restore the project; OR pick a different project in Step 2. |
| Save project is disabled | Either no project is selected, or the selected project matches what is already saved. | Click a different row in the picker. Save enables once your pick differs from the bound project. |
Next step
Once all 5 requirement rows pass, the bottom nav opens Tagging Services — saving the GTM server CONTAINER_CONFIG string and provisioning the preview + tagging Cloud Run services that will run inside this project.