moreserverless.com

Automated Wiki Documentation Pipeline

Date posted: 2026-01-19

Objective: Implement a cross-cloud orchestration pipeline that triggers the documentation service to analyze a repository and automatically publish the generated Markdown to an Azure DevOps Wiki.

1. Orchestration Workflow

• Trigger Layer (azure-pipelines.yaml): An Azure DevOps pipeline acts as the primary orchestrator, managing secure credentials and initiating the hand-off to Google Cloud.
• Compute Layer (Cloud Build): Google Cloud Build serves as the execution engine. It handles the API handshake with the Cloud Run documentation service and manages subsequent Git operations.
• Storage & Publishing: The pipeline concludes by cloning the Azure DevOps Wiki repository, injecting the newly generated ReadMe.md and Architecture.md files, and pushing changes back to the wikiMaster branch.

2. Integration & Security

• Impersonated Authentication: Cloud Build generates an identity token by impersonating a specific service account (ado-terraform@docgen-5ydk.iam.gserviceaccount.com) to securely authenticate requests to the Cloud Run endpoint.
• Secure Token Handling: An Azure DevOps Personal Access Token (PAT) is passed as a sensitive substitution variable (_AZURE_DEVOPS_PAT) from the Azure pipeline to Cloud Build. This ensures the process can clone both private source repositories and the target Wiki.
• JSON Processing: The pipeline utilizes jq within the Cloud Build environment to parse the JSON response from the documentation service and extract raw Markdown content into physical files.

3. Implementation Steps

• GCP Handshake: The Azure pipeline downloads a secure GCP Service Account key and activates it to authorize the gcloud builds submit command.
• Artifact Generation: Cloud Build executes a POST request to the /generate endpoint, sending parameters such as the repository URL, branch (e.g., develop), and requested document types.
• Wiki Sync: The process creates a target directory (defaulting to docgen), copies the AI-generated Markdown files into it, and commits the changes with a unique build number for auditability.

4. Technical Rationale ("The Why")

• Centralized Knowledge: Moving documentation from code repositories to a Wiki ensures high visibility for stakeholders who may not frequently browse source code.
• Parameter-Ready Design: While currently utilizing hardcoded values for the REPO_URL and BRANCH, the architecture is designed for easy conversion into a parameterized pipeline that can document any repository on demand.
• Decoupled Execution: By offloading the "heavy lifting" of AI processing and Git syncing to Google Cloud, the Azure agent remains lightweight and only handles high-level orchestration.
• Automated Audit Trail: Each Wiki update is tagged with a build number, providing a clear link between the documentation version and the pipeline execution that created it.

View Code on Github

This documentation was generated through an iterative AI process, refined by the author for technical accuracy and clarity.