compose-env-gcp

Google Cloud Secret Manager source adapter for compose-env.

Installation

npm install compose-env-gcp @google-cloud/secret-manager

compose-env must also be installed in your project.

Usage

import { defineConfig, source } from 'compose-env'
import { gcpSecretsSource } from 'compose-env-gcp'

const config = await defineConfig(
  {
    DATABASE_URL: { type: 'url',    required: true, secret: true },
    API_KEY:      { type: 'string', required: true, secret: true },
    PORT:         { type: 'port',   default: 3000 },
  },
  {
    sources: [
      gcpSecretsSource('my-gcp-project'),
      source.env(),
    ],
  },
)

By default, all accessible secrets in the project are loaded at their latest version. Secret names are uppercased to produce env var keys.

Load Specific Secrets Only

To load only the secrets you need (recommended for production):

gcpSecretsSource('my-gcp-project', {
  secrets: ['DATABASE_URL', 'API_KEY'],
})

Pin a Specific Version

gcpSecretsSource('my-gcp-project', {
  secrets: ['DATABASE_URL', 'API_KEY'],
  version: '3',
})

Pinning to a version number is recommended in production for reproducible deployments.

Key Normalization

Secret names are uppercased to produce env var keys:

| Secret name | Resolved key | |---------------|---------------| | DATABASE_URL | DATABASE_URL | | api_key | API_KEY | | redis_ttl | REDIS_TTL |

Binary secret payloads are decoded as UTF-8 strings.

Options

| Option | Type | Default | Description | |-----------|------------|-----------|----------------------------------------------------------------------------------------------| | secrets | string[] | — | Explicit list of secret names to load. If omitted, all accessible secrets are loaded. | | version | string | 'latest' | Secret version to access. Pin to a number (e.g. '3') for production stability. |

Authentication

Authentication uses Application Default Credentials (ADC), tried in this order:

1. GOOGLE_APPLICATION_CREDENTIALS — Path to a service account key JSON file
2. Workload Identity — For GKE pods with Workload Identity enabled
3. Attached service account — For Compute Engine, Cloud Run, App Engine, Cloud Functions
4. gcloud CLI — gcloud auth application-default login for local development

Required IAM Permissions

The service account needs the Secret Manager Secret Accessor role (roles/secretmanager.secretAccessor) on each secret, or on the project to access all secrets:

# Grant access to all secrets in a project
gcloud projects add-iam-policy-binding my-gcp-project \
  --member="serviceAccount:[email protected]" \
  --role="roles/secretmanager.secretAccessor"

Source Priority

Sources are resolved in order. Place gcpSecretsSource before or after source.env() depending on which should take precedence:

// GCP overrides local .env files
sources: [source.env(), gcpSecretsSource('my-gcp-project')]

// Local .env files override GCP (useful for local development)
sources: [gcpSecretsSource('my-gcp-project'), source.env()]