credctl setup gcp

Synopsis

credctl setup gcp [flags]

Description

credctl setup gcp is the all-in-one command for configuring GCP with credctl. It handles:

OIDC hosting — creates a GCS bucket and uploads OIDC discovery documents
Workload Identity Pool — logical container for external identities
OIDC Provider — within the pool, configured with the OIDC issuer URL
Service Account IAM binding — grants roles/iam.workloadIdentityUser from the pool principal to the specified service account
Credential config file — generates ~/.credctl/gcp-credentials.json for use with GCP client libraries and gcloud

Configuration is written to ~/.credctl/config.json.

If an OIDC issuer URL already exists in your config (e.g., from credctl setup aws), the command reuses it and skips GCS bucket creation. This means adding GCP after AWS is just one command — no need to copy-paste issuer URLs.

Requires the gcloud CLI to be installed and authenticated. The service account must already exist with appropriate project-level roles.

Flags

Flag	Type	Default	Description
`--service-account`	string	—	Service account email to impersonate. Required.
`--project`	string	gcloud default	GCP project ID. Defaults to the active gcloud configuration.
`--pool-id`	string	`credctl-pool`	Workload Identity Pool ID.
`--provider-id`	string	`credctl-provider`	Workload Identity Provider ID.
`--issuer-url`	string	auto-detected	OIDC issuer URL. Defaults to any existing issuer URL in your config.

Examples

Basic setup

credctl setup gcp --service-account credctl@my-project.iam.gserviceaccount.com

Using GCP project: my-project
Creating GCS bucket 'credctl-oidc-my-project'...
Uploading OIDC documents...
Creating Workload Identity Pool 'credctl-pool'...
Creating OIDC Provider 'credctl-provider'...
Binding service account 'credctl@my-project.iam.gserviceaccount.com'...
Generating credential config file...

GCP setup complete.
  Issuer URL:       https://storage.googleapis.com/credctl-oidc-my-project
  Credential file:  ~/.credctl/gcp-credentials.json

Test it:
  export GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES=1
  gcloud auth login --cred-file=~/.credctl/gcp-credentials.json

Custom project and pool

credctl setup gcp \
  --service-account credctl@staging-project.iam.gserviceaccount.com \
  --project staging-project \
  --pool-id credctl-staging \
  --provider-id credctl-staging-provider

Adding GCP after AWS

If you already ran credctl setup aws, the OIDC issuer is already configured. Just run:

credctl setup gcp --service-account credctl@my-project.iam.gserviceaccount.com

The command detects the existing issuer URL and reuses it — no GCS bucket creation needed.

Custom issuer URL

credctl setup gcp \
  --service-account credctl@my-project.iam.gserviceaccount.com \
  --issuer-url https://my-custom-oidc-endpoint.example.com

Exit codes

Code	Meaning
0	GCP infrastructure created and configured successfully
1	Error (device not initialised, gcloud not found, permission denied, or other error)