gcloud secrets versions access: Usage & Common CI Errors

Read a secret value from Google Cloud Secret Manager.

gcloud secrets versions access fetches the payload of a specific secret version from Secret Manager. In CI you typically access the "latest" version and capture it into an environment variable.

What it does

gcloud secrets versions access <version> --secret=<name> prints the secret payload for that version. The version can be a number or the alias "latest". The output is the raw secret bytes, so you redirect or capture it directly - no extra JSON unwrapping needed.

Common usage

# Read the latest version of a secret
gcloud secrets versions access latest --secret=db-password

# Capture into an env var
DB_PASS=$(gcloud secrets versions access latest --secret=db-password)

# Access a specific numbered version
gcloud secrets versions access 3 --secret=db-password

Common error in CI: PERMISSION_DENIED / API not enabled / no version

Access fails with "PERMISSION_DENIED ... secretmanager.versions.access" when the service account lacks the role, "Secret Manager API has not been enabled", or "NOT_FOUND" when the secret/version does not exist. Fix: enable the API (gcloud services enable secretmanager.googleapis.com) and grant roles/secretmanager.secretAccessor on the secret to the CI service account (least privilege - accessor, not admin). Confirm the secret name and project; use "latest" unless you must pin a version.

Key options

Related guides