gcloud projects add-iam-policy-binding: Roles & CI Errors

Grant an IAM role to a user, group, or service account at project scope.

gcloud projects add-iam-policy-binding adds a single role binding to a project’s IAM policy. It is how you grant a CI service account exactly the access it needs, one role at a time.

What it does

The command adds (member, role) to the project policy without rewriting the whole policy - safer than set-iam-policy for incremental grants. --member takes a prefixed principal (serviceAccount:, user:, group:) and --role takes a role ID (roles/...). It returns the updated policy.

Common usage

# Grant a service account a role on the project
gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:ci@my-project.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.writer"

# Grant a user the viewer role
gcloud projects add-iam-policy-binding my-project \
  --member="user:dev@example.com" --role="roles/viewer"

Common error in CI: missing member prefix / setIamPolicy denied

The command fails with "INVALID_ARGUMENT ... member must be of the form ..." when --member omits the type prefix (serviceAccount:/user:/group:), or "PERMISSION_DENIED ... resourcemanager.projects.setIamPolicy" when the caller lacks rights to change IAM (needs roles/resourcemanager.projectIamAdmin or Owner). Fix: always prefix the member, use the full roles/<name> ID, and run grants with an identity that can modify project IAM. Grant least-privilege predefined roles rather than Owner/Editor.

Key options

Related guides