gcloud secrets versions access: Read a GCP Secret
gcloud secrets versions access prints the raw payload of a Google Secret Manager secret version, usually the latest.
This is the GCP CLI way to read a secret in a pipeline. Reference the latest version by name and authenticate with a service account or Workload Identity from the runner.
What it does
gcloud secrets versions access retrieves the payload of a specific secret version (or latest) and writes the raw bytes to stdout. No decoding is applied, so the output is exactly the stored value.
Common usage
gcloud secrets versions access latest --secret=db-password
gcloud secrets versions access 3 --secret=db-password --project=my-proj
# capture cleanly for a consumer
gcloud secrets versions access latest --secret=api-key > /tmp/keyOptions
| Flag | What it does |
|---|---|
| <version|latest> | Secret version number or the alias latest |
| --secret=<name> | Name of the secret to read |
| --project=<id> | GCP project holding the secret |
| --out-file=<path> | Write the payload to a file instead of stdout |
In CI
Use Workload Identity Federation or a service account key mounted from a CI secret, and grant roles/secretmanager.secretAccessor on the secret. Prefer --out-file into a temp path over echoing the value; mask it and clean up the file.
Common errors in CI
"PERMISSION_DENIED: Permission 'secretmanager.versions.access' denied" means the service account lacks the secretAccessor role. "NOT_FOUND: Secret ... was not found" means a wrong --secret or --project. "You do not currently have an active account selected" means gcloud auth was never configured on the runner.