From 38a413fe9e54085e8b98d964a62051f6c403d913 Mon Sep 17 00:00:00 2001
From: Chalindu Kodikara <chalindu@wso2.com>
Date: Fri, 16 Jan 2026 18:56:12 +0530
Subject: [PATCH] Improve ci docs

---
 docs/user-guide/ci/external-container-registry.mdx | 4 ++--
 docs/user-guide/ci/private-repository.mdx          | 9 ++++++---
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/docs/user-guide/ci/external-container-registry.mdx b/docs/user-guide/ci/external-container-registry.mdx
index 2472464..e222c54 100644
--- a/docs/user-guide/ci/external-container-registry.mdx
+++ b/docs/user-guide/ci/external-container-registry.mdx
@@ -8,7 +8,7 @@ sidebar_position: 7
 
 This guide explains how to configure OpenChoreo to use an external container registry instead of the built-in one. External registries like Docker Hub, AWS ECR, Google Container Registry (GCR), or Azure Container Registry (ACR) can be used for storing container images.
 
-:::info Two-Plane Architecture
+:::info Architecture
 OpenChoreo uses separate planes for building and running applications:
 - **Build Plane**: Where images are built and pushed to the registry (requires push credentials)
 - **Data Plane**: Where applications run and pull images from the registry (requires pull credentials)
@@ -50,7 +50,7 @@ global:
     enabled: false
 ```
 
-Then create custom `ClusterWorkflowTemplates` based on the [default templates](https://github.com/openchoreo/openchoreo/tree/main/install/helm/openchoreo-build-plane/templates/workflow-templates) in the OpenChoreo repository.
+Then, create custom `ClusterWorkflowTemplates` based on the [default templates](https://github.com/openchoreo/openchoreo/tree/main/install/helm/openchoreo-build-plane/templates/workflow-templates) in the OpenChoreo repository.
 
 ### Step 3: Add Registry Push Credentials
 
diff --git a/docs/user-guide/ci/private-repository.mdx b/docs/user-guide/ci/private-repository.mdx
index 636e3f4..ef105d6 100644
--- a/docs/user-guide/ci/private-repository.mdx
+++ b/docs/user-guide/ci/private-repository.mdx
@@ -16,13 +16,13 @@ Create a git token with read access to your repositories.
 
 ### Step 2: Switch to Build Plane Context
 
-If your control plane and build plane are in **separate Kubernetes clusters**, switch to the build plane cluster context. This is where workflow execution and git cloning happens.
+Switch to the build plane cluster context. This is where workflow execution and git cloning happens.
 
 ```bash
 kubectl config use-context <build-plane-context>
 ```
 
-### Step 3: Store the Token in OpenChoreo
+### Step 3: Store the Token in the Key Vault
 
 **For Development/Testing (using fake provider):**
 
@@ -49,6 +49,10 @@ kubectl get clustersecretstore default -o yaml
 
 Configure a ClusterSecretStore for your secret manager (AWS Secrets Manager, HashiCorp Vault, etc.) and store your token with key `git-token`.
 
+:::warning
+Do not change the key name `git-token`. This key is referenced by the default ComponentWorkflows during the clone step.
+:::
+
 ### Step 4: Use Private Repository in Your Component
 
 Simply reference your private repository URL in the Component spec:
@@ -88,7 +92,6 @@ When building from a private repository:
 1. **ComponentWorkflow** defines an ExternalSecret resource that fetches your Git token from a secret backend
 2. **ComponentWorkflowRun controller** creates the ExternalSecret in the Build Plane before executing the workflow
 3. **Clone step** reads the token from the mounted secret, constructs an authenticated URL, and clones the repository
-4. Credentials are never exposed in logs or workflow outputs
 
 This architecture separates secret management (control plane) from build execution (build plane) while maintaining security.