gcloud iam workload-identity-pools create: OIDC
gcloud iam workload-identity-pools create defines a pool that lets external OIDC tokens impersonate a Google service account, keylessly.
Workload Identity Federation is how GitHub Actions authenticates to Google Cloud without a long-lived JSON key. The pool is the first object you create.
What it does
gcloud iam workload-identity-pools create creates a pool that holds OIDC providers. You then add a provider mapping the external issuer (e.g. GitHub Actions) and bind a service account so federated tokens can impersonate it. Pools are always --location=global.
Common usage
gcloud iam workload-identity-pools create github-pool \
--location=global --display-name="GitHub Actions"
gcloud iam workload-identity-pools providers create-oidc gh-provider \
--location=global --workload-identity-pool=github-pool \
--issuer-uri="https://token.actions.githubusercontent.com" \
--attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository"Flags
| Flag | What it does |
|---|---|
| --location=global | Pools and providers live in the global location |
| --display-name <name> | Human-readable pool name |
| providers create-oidc | Subcommand: add an OIDC provider to a pool |
| --issuer-uri <url> | OIDC issuer, e.g. the GitHub Actions token URL |
| --attribute-mapping <map> | Map token claims to Google attributes |
| --attribute-condition <expr> | Restrict which tokens are accepted |
In CI
After creating the pool and provider, bind the service account with gcloud iam service-accounts add-iam-policy-binding using roles/iam.workloadIdentityUser scoped to principalSet for your repo, then use google-github-actions/auth with the provider. This removes JSON keys from the pipeline entirely.
Common errors in CI
"unable to impersonate ... Permission 'iam.serviceAccounts.getAccessToken' denied" means the workloadIdentityUser binding is missing or the principalSet does not match the repo. "Invalid value for ... attribute_mapping" means google.subject is not mapped, which is required. "The condition rejected the request" means your --attribute-condition is too strict for the incoming token.