Secrets & Configuration Overview

Trovella stores all production secrets in GCP Secret Manager and delivers them to the runtime as environment variables. No secrets are committed to the repository, embedded in Docker images, or stored in GitHub Secrets (with one exception: SENTRY_AUTH_TOKEN for source map uploads).

Design Principles

1. Terraform creates shells, humans fill them. The secret-manager Terraform module creates empty Secret Manager entries. Values are set manually via gcloud or the GCP Console, never written by Terraform. This prevents secret values from appearing in Terraform state.

2. Secrets become env vars at the last moment. On the production VM, the sync-secrets-vm.sh script pulls secrets from Secret Manager and writes them to /opt/trovella/.env immediately before docker compose up. In CI, gcloud secrets versions access reads individual secrets inline.

3. No long-lived credentials in CI. GitHub Actions authenticates to GCP via Workload Identity Federation (OIDC token exchange), not service account key files. See Infrastructure -- Cloud Resources -- Workload Identity for the WIF setup.

4. Local development uses static defaults. The .env.example files contain working defaults for local Docker services (Postgres, Redis, Typesense, Mailpit). Only API keys for external services (Anthropic, Google AI, Google OAuth) need manual setup.

How Secrets Flow

GCP Secret Manager (trovella-prod project)
      |
      |--- CI: gcloud secrets versions access (per-secret, inline)
      |      |--- DATABASE_URL -> migrate-prod job (via Cloud SQL Proxy)
      |      |--- SENTRY_DSN -> build-push job (baked into Docker image as NEXT_PUBLIC_*)
      |
      |--- VM: sync-secrets-vm.sh (all secrets, written to /opt/trovella/.env)
             |--- docker compose reads .env via env_file directive
             |--- DATABASE_URL rewritten to route through cloud-sql-proxy container

Secret Inventory

Trovella manages 14 secrets in GCP Secret Manager, all prefixed with trovella-:

Secret Manager ID	Env Var	Used By
trovella-anthropic-api-key	ANTHROPIC_API_KEY	@repo/ai -- Claude API calls
trovella-google-ai-api-key	GOOGLE_AI_API_KEY	@repo/ai -- Gemini embedding API
trovella-database-url	DATABASE_URL	@repo/db -- PostgreSQL connection
trovella-better-auth-secret	BETTER_AUTH_SECRET	@repo/auth -- session signing
trovella-better-auth-url	BETTER_AUTH_URL	@repo/auth -- base URL for callbacks
trovella-google-oauth-client-id	GOOGLE_CLIENT_ID	@repo/auth -- Google OAuth
trovella-google-oauth-client-secret	GOOGLE_CLIENT_SECRET	@repo/auth -- Google OAuth
trovella-resend-api-key	RESEND_API_KEY	Email delivery (deferred)
trovella-upstash-redis-url	REDIS_URL	@repo/cache -- Redis connection
trovella-upstash-redis-token	UPSTASH_REDIS_TOKEN	@repo/cache -- Upstash auth
trovella-sentry-dsn	SENTRY_DSN	Sentry error tracking
trovella-inngest-event-key	INNGEST_EVENT_KEY	Inngest event authentication
trovella-inngest-signing-key	INNGEST_SIGNING_KEY	Inngest webhook verification
trovella-typesense-api-key	TYPESENSE_API_KEY	@repo/search -- Typesense auth

Pages in This Topic

Secret Manager

How Terraform provisions Secret Manager entries, the naming convention, IAM access control, and how to add a new secret.

Environment Variables

Complete reference for every environment variable, grouped by service. Covers local defaults, CI placeholders, and production values.

VM Secret Sync

The sync-secrets-vm.sh script that pulls secrets from Secret Manager to the production VM, including the DATABASE_URL rewrite for Cloud SQL Auth Proxy.

CI Secret Access

How CI jobs read secrets from Secret Manager using Workload Identity Federation, the one GitHub Secret (SENTRY_AUTH_TOKEN), and build-time variable injection.

Rotation

Procedures for rotating each category of secret, impact assessment, and a rotation checklist.

Cross-Domain References

• Infrastructure -- Cloud Resources -- Secret Provisioning -- Terraform module details and provisioning sequence
• Infrastructure -- Cloud Resources -- Workload Identity -- WIF setup that enables keyless secret access from CI
• Data & Storage -- Migrations -- CI Deployment -- how the migrate-prod job reads DATABASE_URL from Secret Manager
• Delivery -- Pipeline -- full CI/CD pipeline context
• Infrastructure -- Compute -- VM service account and Docker Compose runtime