How to Use Google Cloud Secret Manager in Bruno

Securing credentials is one of the most important and most quietly neglected jobs in software development. As an individual developer, your API keys probably live in an environment file, a scratch note, or pasted directly into a request. It works, until you need to rotate a key, onboard a teammate, or run the same tests in CI without leaking anything.

That is where a secret manager earns its place. This guide walks through integrating Google Cloud Secret Manager with Bruno, end to end: configure the provider, fetch secrets into an environment, reference them in requests and scripts, and run the same collection from the Bruno CLI.

Bruno is an open-source, offline-first, Git-friendly API client. Your collections are plain files on disk which is exactly why pulling secrets from a managed vault at runtime matters: the credentials never land in those files.

Why Secret Manager?

Storing an API key in a local .env file or an environment variable is fine for a weekend project. The cracks appear the moment more than one person, or more than one machine, is involved:

• Rotation is manual. Change the key in GCP and every teammate has to update their local copy. Someone always misses it.
• Onboarding leaks secrets. Sending a .env file over Slack means the credential has escaped the vault before it ever reached the API client.
• No audit trail. When a key leaks, you cannot answer "who read this, and when?"
• No least privilege. Every developer with the file has production access, whether they need it or not.

A secret manager fixes all four. Bruno supports HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, and Google Cloud Secret Manager. This guide covers the last one.

What Is Google Cloud Secret Manager?

Google Cloud Secret Manager is a managed service for storing API keys, passwords, certificates, and other sensitive strings. Each secret has a secret ID (the name) and one or more versions (the values). Access is controlled through IAM, every read is logged in Cloud Audit Logs, and the payload can be anything like a plain string or a JSON blob.

Three concepts carry over into Bruno, so it is worth fixing them now:

Before You Start: Prerequisites

You need four things in place on the Google Cloud side. Skipping any one of them is the most common reason the connection test fails.

If you prefer the terminal, this creates the account and grants both roles:

# enable the API
gcloud services enable secretmanager.googleapis.com --project my-project

# create the service account
gcloud iam service-accounts create bruno-secrets \
  --display-name="Bruno Secret Reader" --project my-project

# grant list + read access
gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:bruno-secrets@my-project.iam.gserviceaccount.com" \
  --role="roles/secretmanager.viewer"

gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:bruno-secrets@my-project.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

# download the key Bruno will use
gcloud iam service-accounts keys create ./bruno-sa-key.json \
  --iam-account=bruno-secrets@my-project.iam.gserviceaccount.com

Step 1: Configure GCP Secret Manager in Bruno

The provider is configured once in Preferences, then reused by any collection environment. You do not repeat this per collection.

The account now appears in the Secrets Manager list and is selectable from any environment.

Step 2: Fetch Secrets Into an Environment

The three-dots menu on the provider lets you Edit account or Remove secret manager from this environment.

Reading from more than one project

One service account, several projects: keep the default project on the first row, then add a second row with a different Project ID. Each row's Name becomes the namespace for that project's secrets, so identical secret IDs in different projects never collide.

Step 3: Use Secrets in Requests

Fetched secrets behave like any other Bruno variable. Use them in the URL, query params, headers, request body, or auth fields. The pattern is row name, dot, secret ID:

{{<row-name>.<secret-id>}}

If the secret payload is JSON, Bruno parses it so you can reach individual keys with one more dot:

{{<row-name>.<secret-id>.<json-key>}}

Concretely, with a row named staging:

A typical Authorization header therefore looks like this:

Authorization: Bearer {{staging.api-key}}

Old syntax vs new syntax

The legacy form still resolves in v4 and is shown with a deprecation underline in the editor. An in-app tool that rewrites every $secrets reference for you ships in v4.2.0.

Step 4: Use Secrets in Scripts

In Pre-request and Post-response scripts, read secrets with bru.getSecretVar(). The argument is the same dotted path you would use in a request field, as a string:

// plain string secret
const apiKey = bru.getSecretVar('staging.api-key');
req.setHeader('Authorization', 'Bearer ' + apiKey);

// sub-key of a JSON secret
const password = bru.getSecretVar('staging.db.password');

This is useful when the credential needs work before it goes on the wire, signing a payload, building a Basic auth header, or exchanging a client secret for a short-lived token:

// build a Basic auth header from two GCP secrets
const user = bru.getSecretVar('staging.db.username');
const pass = bru.getSecretVar('staging.db.password');

const encoded = Buffer.from(`${user}:${pass}`).toString('base64');
req.setHeader('Authorization', `Basic ${encoded}`);

Step 5: Use GCP Secrets in the Bruno CLI

The configuration you just created lives in the environment file, so it travels with your repository. What does not travel — deliberately are the credentials. Those are passed to the CLI at runtime with --secrets-env-file.

Export the credential file from the app

You do not have to write the dotenv file by hand:

The exported file contains three variables:

BRUNO_GCP_SECRETS_MANAGER_PROJECT_ID=my-project
BRUNO_GCP_SECRETS_MANAGER_CLIENT_EMAIL=service-account@my-project.iam.gserviceaccount.com
BRUNO_GCP_SECRETS_MANAGER_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

The PROJECT_ID here is only the account default. The projects actually read from come from the environment rows, so a single credential file works across all of them.

Run the collection

bru run --env Production --secrets-env-file ./secrets.env

• --env: CLI flag to pass environment name 

• --secrets-file-name: Pass exported .env file from the app

Secrets are fetched at runtime, injected into the variable chain, and never written to disk or printed in logs.

Variable precedence

When the same name is defined in more than one place, the highest entry wins:

External secrets                        ← highest
    ↓
Secret env vars (--secrets-env-file)
    ↓
Environment variables (--env)
    ↓
Collection / Workspace / Global env      ← lowest

Troubleshooting

Good to Know & Current Limits

Conclusion

The setup is a one-time cost: add the service account in Preferences, attach it to an environment, click Fetch Secrets. From that point on your collection references credentials by name and Google Cloud Secret Manager remains the single source of truth. Rotating a key becomes a change in one place, onboarding a teammate means granting IAM access rather than sending a file, and CI runs read the same secrets without any of them landing in a log or a commit.

Because Bruno stores collections as plain files in Git, this separation matters more than it would in a cloud-based client: the configuration is versioned and reviewable, while the secrets themselves never enter the repository.