gcloud iam roles create: Custom IAM Roles

gcloud iam roles create defines a custom role granting exactly the permissions you list, for least-privilege CI identities.

Predefined roles are often too broad for a deploy service account. A custom role lets you grant only the permissions a pipeline actually needs.

What it does

gcloud iam roles create creates a custom IAM role at the project or organization level, containing the permissions you pass with --permissions or a YAML --file. The role can then be bound to a service account.

Common usage

Terminal

gcloud iam roles create ciDeployer --project=my-proj \
  --title="CI Deployer" \
  --permissions=run.services.update,run.services.get \
  --stage=GA
# from a YAML definition
gcloud iam roles create ciDeployer --project=my-proj \
  --file=role.yaml

Flags

Flag	What it does
<ROLE_ID>	Identifier for the new role
--project / --organization	Scope the role to a project or org
--permissions <list>	Comma-separated permissions to include
--title <text>	Display title for the role
--stage <stage>	Launch stage: ALPHA, BETA, GA, DISABLED
--file <yaml>	Define the role from a YAML file

In CI

Build least-privilege roles for the service account that your Workload Identity Federation provider impersonates, so a leaked or misused token can do as little as possible. Iterate role updates with gcloud iam roles update.

Common errors in CI

"INVALID_ARGUMENT: Permission ... is not valid" means a typo or a permission not grantable in custom roles. "You can't create a role with stage [GA] ... testing permission" appears when a listed permission is still in TESTING; set --stage=ALPHA or drop it. "Role already exists" means reuse the update verb instead.