Google Secret Manager

Google Secret Manager is one of the cloud drivers behind secrets. Your app reads provider keys from Secret Manager on the server, and main.yaml refers to them as secret:NAME. Pick it when your app runs on Google Cloud and you want secrets under the same IAM and audit logs as the rest of your project.

secrets:
  driver: gcp-secret-manager

Before you start

1. Enable the Secret Manager API in the Google Cloud project that will hold your secrets.
2. Create a secret for each key, such as RESEND_API_KEY, and add its value as a version. Choose replication locations that fit your data rules. How a secret: name maps to a Secret Manager resource name is not defined yet.
3. Give your app an identity. Prefer workload identity: the service account your Cloud Run service, GKE workload or other compute already runs as, or Workload Identity Federation when the app runs outside Google Cloud. Avoid downloaded service account key files.
4. Grant read access only, such as the Secret Manager secret accessor role, on just the secrets the app needs.

Configure

secrets:
  driver: gcp-secret-manager   # [to be decided] project and other driver settings are not specified yet
email:
  key: secret:RESEND_API_KEY   # suggested name; read from Secret Manager at startup

Keep local in a development overlay and gcp-secret-manager in main.env.prod.yaml. A literal value in a field marked secret fails mainsdk check with MAIN-CONFIG-0004.

Use it

import { secrets } from "mainsdk";   // server only: a client import fails the build

export async function partnerHeaders() {
  const token = await secrets.get("PARTNER_API_TOKEN");
  return { authorization: `Bearer ${token}` };
}

Local development and testing

• No Google Cloud project: use the local driver (.mainsdk/secrets.json, git-ignored) or the env driver.
• Against real Secret Manager: use a development project and your own application default credentials on your machine.
• Tests: createTestApp() from @mainsdk/testing runs secrets on its in-memory fake, and chaos.on("secrets", { outage: true }) simulates Secret Manager being unreachable.

import { it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp, chaos } from "@mainsdk/testing";
import { secrets } from "mainsdk";

it("serves the last good value when Secret Manager is down", async () => {
  createTestApp({ main: "./main.yaml" });
  const first = await secrets.get("PARTNER_API_TOKEN");
  chaos.on("secrets", { outage: true });
  assert.equal(await secrets.get("PARTNER_API_TOKEN"), first);
});

What MainSDK adds on top

• secrets is importable only in server code; values are redacted from logs, errors and telemetry.
• The last good value is served from memory when Secret Manager is unreachable, with MAIN-SECRET-0007; never written to disk.
• A key in code, a committed env file or the browser bundle fails mainsdk check.

See Secrets for the full contract.

Limits and notes

• The driver comes with the config-secrets spec (phase 1).
• When you add a new secret version, the next secrets.get() after the driver's cache TTL returns it, with no restart. The TTL length, and which version the driver reads, are not decided yet.
• secrets.raw() returns the provider's client; each use is logged and listed by mainsdk check.

Swap to or from it

secrets:
  driver: gcp-secret-manager   # was env

FAQ

Do I need a service account key file? No. Use the service account your compute runs as, or Workload Identity Federation outside Google Cloud.

Can secrets live in one region only? Secret Manager lets you choose replication locations per secret. Pick ones that match where your app's data must stay.

Next

• Secrets and Encryption keys
• Google Cloud KMS, AWS Secrets Manager and HashiCorp Vault
• Swap a driver

Open questions