gcloud secrets create: Create a Secret

gcloud secrets create defines a Secret Manager secret, optionally seeding its first version from a file.

Storing a generated credential for later steps starts with creating the secret. Seeding the first version from a file (not the command line) keeps the value out of process logs.

What it does

gcloud secrets create makes a new secret container with a replication policy. To set its value you add a version with gcloud secrets versions add, reading from --data-file so the secret never appears in the shell history or argv.

Common usage

Terminal

gcloud secrets create db-password \
  --replication-policy=automatic
# add the first version from a file (not the CLI)
printf '%s' "$GENERATED" > /tmp/v
gcloud secrets versions add db-password --data-file=/tmp/v
rm -f /tmp/v

Flags

Flag	What it does
<SECRET>	Name of the secret to create
--replication-policy automatic\|user-managed	How the secret replicates
--locations <regions>	Regions for user-managed replication
--data-file <file>	Seed a version from a file (- for stdin)
--labels KEY=VAL	Attach labels to the secret

In CI

Pass secret values via --data-file (or - for stdin), never as a positional, so the value does not land in argv or job logs. Authenticate keylessly with Workload Identity Federation; the identity needs roles/secretmanager.admin to create and roles/secretmanager.secretVersionAdder to add versions.

Common errors in CI

"Secret [name] already exists" means use gcloud secrets versions add to add a new version instead of recreating. "PERMISSION_DENIED ... secretmanager.secrets.create" means the identity lacks the admin role. "Secret Manager API has not been used in project ..." means enable secretmanager.googleapis.com.