feat(integrations): Google Cloud connectors (project, folder, organization) and setup script

.env.example

@@ -187,6 +187,11 @@ INGEST_REQUIRE_TLS=false
 # CLOUDFLARE_OAUTH_REVOKE_URL=https://dash.cloudflare.com/oauth2/revoke
 # MAPLE_CLOUDFLARE_API_BASE_URL=https://api.cloudflare.com/client/v4
 
+# Google Cloud integration (the project owner runs a generated gcloud script in Cloud Shell).
+# Logs need no configuration. For metrics, set the email of a Google service account Maple owns;
+# the setup script lets it impersonate a read-only metrics account in the customer's project.
+# MAPLE_GCP_SERVICE_ACCOUNT_EMAIL=
+
 # OpenTelemetry (API self-observability) — read by @maple-dev/effect-sdk
 # MAPLE_ENVIRONMENT=local                  # "local" = no export; any other value enables OTLP
 # MAPLE_ENDPOINT=http://127.0.0.1:3474     # Ingest gateway endpoint (enriches with org_id)

apps/api/src/resources/env.ts

@@ -79,4 +79,5 @@ export const apiConfiguredEnv = (stage: MapleStage, region: MapleRegion, domains
 		optionalSecret("GITHUB_APP_WEBHOOK_SECRET"),
 		cloudflareOAuthEnv,
 		planetScaleOAuthEnv,
+		optionalPlain("MAPLE_GCP_SERVICE_ACCOUNT_EMAIL"),
 	)

apps/api/src/routes/v2/integrations-gcp.http.ts

@@ -0,0 +1,129 @@
+import { HttpApiBuilder } from "effect/http-api"
+import { CurrentTenant } from "@maple/domain/http"
+import type { V2GcpConnector } from "@maple/domain/http/v2"
+import {
+	MapleApiV2,
+	isoTimestamp,
+	isoTimestampOrNull,
+	V2InsufficientPermissions,
+} from "@maple/domain/http/v2"
+import { Effect } from "effect"
+import { recordHttpAudit } from "@maple/backend/services/audit/AuditLogService"
+import { requireAdmin } from "@maple/backend/services/auth/auth"
+import {
+	GcpConnectorService,
+	type GcpConnector,
+} from "@maple/backend/services/integrations/GcpConnectorService"
+
+// Reading the status is open to every member. Everything else is admin-only: a connector decides
+// what may write logs into the org and what Maple reads, and its setup script carries the push
+// secret.
+const adminOnly = () => V2InsufficientPermissions.make("Only org admins can manage Google Cloud connectors")
+
+const toV2Connector = (connector: GcpConnector): V2GcpConnector => ({
+	id: connector.id,
+	object: "gcp_connector",
+	scope_type: connector.scopeType,
+	scope_id: connector.scopeId,
+	project_id: connector.projectId,
+	logs_enabled: connector.logsEnabled,
+	metrics_enabled: connector.metricsEnabled,
+	created_at: isoTimestamp(connector.createdAt),
+	last_log_received_at: isoTimestampOrNull(connector.lastLogReceivedAt),
+	last_log_error: connector.lastLogError,
+	applied_logs_enabled: connector.appliedLogsEnabled,
+	applied_metrics_enabled: connector.appliedMetricsEnabled,
+	setup_reported_at: isoTimestampOrNull(connector.setupReportedAt),
+})
+
+const auditMetadata = (connector: GcpConnector) => ({
+	scope_type: connector.scopeType,
+	scope_id: connector.scopeId,
+	project_id: connector.projectId,
+	logs_enabled: connector.logsEnabled,
+	metrics_enabled: connector.metricsEnabled,
+})
+
+export const HttpV2GcpIntegrationsLive = HttpApiBuilder.group(MapleApiV2, "gcpIntegration", (handlers) =>
+	Effect.gen(function* () {
+		const gcp = yield* GcpConnectorService
+
+		return handlers
+			.handle("status", () =>
+				Effect.gen(function* () {
+					const tenant = yield* CurrentTenant.Context
+					const status = yield* gcp.status(tenant.orgId)
+					return {
+						object: "gcp_integration" as const,
+						metrics_available: status.metricsAvailable,
+						connectors: status.connectors.map(toV2Connector),
+					}
+				}),
+			)
+			.handle("createConnector", ({ payload }) =>
+				Effect.gen(function* () {
+					const tenant = yield* CurrentTenant.Context
+					yield* requireAdmin(tenant.roles, adminOnly)
+					const connector = yield* gcp.create(tenant.orgId, tenant.userId, {
+						scopeType: payload.scope_type,
+						scopeId: payload.scope_id,
+						// A project hosts its own resources; the contract rejects any other value.
+						projectId: payload.scope_type === "project" ? payload.scope_id : payload.project_id,
+						logsEnabled: payload.logs_enabled ?? true,
+						metricsEnabled: payload.metrics_enabled ?? false,
+					})
+					yield* recordHttpAudit("gcp_connector.created", {
+						resourceId: connector.id,
+						metadata: auditMetadata(connector),
+					})
+					return toV2Connector(connector)
+				}),
+			)
+			.handle("updateConnector", ({ params, payload }) =>
+				Effect.gen(function* () {
+					const tenant = yield* CurrentTenant.Context
+					yield* requireAdmin(tenant.roles, adminOnly)
+					const connector = yield* gcp.update(tenant.orgId, params.id, {
+						logsEnabled: payload.logs_enabled,
+						metricsEnabled: payload.metrics_enabled,
+					})
+					yield* recordHttpAudit("gcp_connector.updated", {
+						resourceId: connector.id,
+						metadata: auditMetadata(connector),
+					})
+					return toV2Connector(connector)
+				}),
+			)
+			.handle("setupScripts", ({ params, payload }) =>
+				Effect.gen(function* () {
+					const tenant = yield* CurrentTenant.Context
+					yield* requireAdmin(tenant.roles, adminOnly)
+					const scripts = yield* gcp.scripts(tenant.orgId, params.id, {
+						logFilter: payload.log_filter ?? "keep",
+					})
+					return {
+						object: "gcp_connector.setup_scripts" as const,
+						setup_script: scripts.setupScript,
+						cleanup_script: scripts.cleanupScript,
+					}
+				}),
+			)
+			.handle("deleteConnector", ({ params }) =>
+				Effect.gen(function* () {
+					const tenant = yield* CurrentTenant.Context
+					yield* requireAdmin(tenant.roles, adminOnly)
+					const deleted = yield* gcp.delete(tenant.orgId, params.id)
+					yield* recordHttpAudit("gcp_connector.deleted", {
+						resourceId: params.id,
+						metadata: auditMetadata(deleted.connector),
+					})
+					return {
+						id: params.id,
+						object: "gcp_connector" as const,
+						deleted: true as const,
+						cleanup_script: deleted.cleanupScript,
+					}
+				}),
+			)
+	}),
+)

apps/api/src/routes/v2/v2-test-support.ts

@@ -42,7 +42,9 @@ import { HttpV2AttributeMappingsLive } from "./attribute-mappings.http"
 import { HttpV2DashboardsLive } from "./dashboards.http"
 import { HttpV2IngestKeysLive } from "./ingest-keys.http"
 import { HttpV2ChatIntegrationsLive } from "./integrations-chat.http"
+import { HttpV2GcpIntegrationsLive } from "./integrations-gcp.http"
 import { HttpV2PlanetScaleIntegrationsLive } from "./integrations.http"
+import { GcpConnectorService } from "@maple/backend/services/integrations/GcpConnectorService"
 import { HttpV2ErrorIssuesLive } from "./error-issues.http"
 import { HttpV2AnomaliesLive } from "./anomalies.http"
 import { HttpV2InvestigationsLive } from "./investigations.http"
@@ -155,6 +157,8 @@ const v2GroupLayersExceptOnboardingChecklist = (chatWorkspace: Layer.Layer<ChatW
 			Layer.provide(Layer.mergeAll(MobileDevicesService.layer, LiveActivitiesService.layer)),
 		),
 		HttpV2AgentFeedbackLive.pipe(Layer.provide(AgentFeedbackService.layer)),
+		// Same, plus the Env every harness provides as well.
+		HttpV2GcpIntegrationsLive.pipe(Layer.provide(GcpConnectorService.layer)),
 		// Real reads over whichever `WarehouseQueryService` stub the test provides.
 		HttpV2SessionReplaysLive.pipe(
 			Layer.provide(

apps/api/src/runtime/http-graph.ts

@@ -49,6 +49,7 @@ import { V2TransportErrorBoundaryLive } from "@/routes/v2/error-envelope"
 import { HttpV2ErrorIssuesLive } from "@/routes/v2/error-issues.http"
 import { HttpV2IngestKeysLive } from "@/routes/v2/ingest-keys.http"
 import { HttpV2ChatIntegrationsLive } from "@/routes/v2/integrations-chat.http"
+import { HttpV2GcpIntegrationsLive } from "@/routes/v2/integrations-gcp.http"
 import { HttpV2PlanetScaleIntegrationsLive } from "@/routes/v2/integrations.http"
 import { HttpV2InvestigationsLive } from "@/routes/v2/investigations.http"
 import { HttpV2AgentFeedbackLive } from "@/routes/v2/agent-feedback.http"
@@ -163,6 +164,7 @@ const ApiV2Routes = HttpApiBuilder.layer(MapleApiV2).pipe(
 			HttpV2IngestKeysLive,
 			HttpV2ChatIntegrationsLive,
 			HttpV2PlanetScaleIntegrationsLive,
+			HttpV2GcpIntegrationsLive,
 			HttpV2ErrorIssuesLive,
 			HttpV2AttributeMappingsLive,
 			HttpV2AuditLogLive,

apps/api/src/runtime/service-graph.ts

@@ -36,6 +36,7 @@ import { IncidentClassifier } from "@maple/backend/services/errors/IncidentClass
 import { InvestigationService } from "@maple/backend/services/errors/InvestigationService"
 import { RecommendationIssueService } from "@maple/backend/services/errors/RecommendationIssueService"
 import { CloudflareAnalyticsService } from "@maple/backend/services/integrations/CloudflareAnalyticsService"
+import { GcpConnectorService } from "@maple/backend/services/integrations/GcpConnectorService"
 import { PlanetScaleConnectionService } from "@maple/backend/services/integrations/PlanetScaleConnectionService"
 import { PlanetScaleDiscoveryService } from "@maple/backend/services/integrations/PlanetScaleDiscoveryService"
 import { PlanetScaleService } from "@maple/backend/services/integrations/PlanetScaleService"
@@ -113,6 +114,7 @@ export const HttpServicesLive = Layer.mergeAll(
 	DailySpendService.layer,
 	CloudflareAnalyticsService.layer,
 	RailwayMetricsService.layer,
+	GcpConnectorService.layer,
 	OrgOpenRouterKeyService.layer,
 	AuditLogService.layer,
 	WarehouseQueryService.layer,

apps/ios/Packages/MapleAPI/Sources/MapleAPI/openapi.json

@@ -7777,6 +7777,10 @@
       "description": "Connect PlanetScale to your organization and manage what Maple collects from it: connection status, organization binding, the metrics service token that enables branch-metrics scraping, the database inventory, webhook setup, query insights, and the lifecycle event timeline.",
       "name": "PlanetScale Integration"
     },
+    {
+      "description": "Connect Google Cloud projects, folders or organizations: register a connector, choose whether it forwards logs and whether Maple may read metrics and resources, fetch the `gcloud` scripts that set it up, and see whether logs are arriving.",
+      "name": "Google Cloud Integration"
+    },
     {
       "description": "Deduplicated errors and alert-backed issues tracked through Maple's triage workflow.",
       "name": "Error Issues"