Enforce dedicated service account for Cloud Build triggers

Author: alex-doudou

skills/gcp-cicd-design/references/how_to_create_cloudbuild_trigger.md

@@ -4,24 +4,24 @@ This document outlines the standard, idempotent procedure for creating a Google
 
 ---
 
-## ## Core Principle: Idempotency
+## Core Principle: Idempotency
 
 Every step in this process must be **idempotent**. This means the agent must **always check if a resource already exists** before attempting to create it. This prevents errors and ensures the process can be run multiple times safely.
 
 ---
 
-## ## Prerequisite Checklist
+## Prerequisite Checklist
 
 The following dependencies must be satisfied in order before creating the trigger.
 
-### ### 1. Ensure `cloudbuild.yaml` Exists
+### 1. Ensure `cloudbuild.yaml` Exists
 
 The trigger needs a build configuration file to execute.
 
 * **Action**: Check for a `cloudbuild.yaml` file at the root of the source repository.
 * **If it does not exist**: Generate one by translating the user-approved plan. The steps in the generated YAML must be a direct translation of the components defined in the plan's `stages` object. The specifics of the steps (e.g., using `pytest` vs. `mvn test`) should be informed by discovering the application archetype (e.g., by finding a `pyproject.toml` or `pom.xml`).
 
-### ### 2. Ensure Artifact Registry Repository Exists
+### 2. Ensure Artifact Registry Repository Exists
 
 The `cloudbuild.yaml` file will reference an Artifact Registry repository to push container images. This repository must exist before a build can succeed.
 
@@ -30,7 +30,7 @@ The `cloudbuild.yaml` file will reference an Artifact Registry repository to pus
 * **Check** if this repository already exists in the target GCP project.
 * **If it does not exist**: Create it using the available tools.
 
-### ### 3. Ensure Developer Connect and Repository Link Exist
+### 3. Ensure Developer Connect and Repository Link Exist
 
 Cloud Build triggers connect to source code via Developer Connect. The entire connection and repository link must be in place.
 
@@ -40,8 +40,20 @@ Cloud Build triggers connect to source code via Developer Connect. The entire co
 4.  **Check for Repository Link**: Check if a repository link for that specific URI already exists within the Developer Connect connection.
 5.  **Create Repository Link (if needed)**: If the link does not exist, create it. This link is the resource that the Cloud Build trigger will formally point to.
 
+### 4. Ensure Dedicated Service Account Exists
+
+Cloud Build triggers should **always** use a dedicated, user-managed service account instead of the default Compute Engine service account to follow the principle of least privilege.
+
+1.  **Check for Service Account**: Check if a dedicated service account for Cloud Build (e.g., `cloud-build-runner@<PROJECT_ID>.iam.gserviceaccount.com`) already exists.
+2.  **Create Service Account (if needed)**: If no dedicated service account exists, create one using `gcloud iam service-accounts create`.
+3.  **Grant Necessary Roles**: Ensure the dedicated service account has the following roles at minimum:
+    *   `roles/logging.logWriter`: To write build logs to Cloud Logging.
+    *   `roles/artifactregistry.writer`: To push built images to Artifact Registry.
+    *   `roles/developerconnect.tokenAccessor`: To access source code via Developer Connect.
+    *   *Note*: Additional roles (e.g., `roles/run.admin`, `roles/iam.serviceAccountUser`) may be required depending on the specific deployment steps in the `cloudbuild.yaml`.
+
 ---
 
-## ## Final Step: Creating the Trigger
+## Final Step: Creating the Trigger
 
-Once all prerequisites are met, the agent can create the trigger itself using the available tools.
+Once all prerequisites are met, the agent can create the trigger itself using the `create_build_trigger` tool. **You MUST provide the email of the dedicated service account identified or created in Step 4 to the `service_account` parameter.**