Spaces:
Sleeping
Sleeping
| # 🛠️ Technical Specification: GitLab Context Brain | |
| This document outlines the architecture, tech stack, and integration points for building the GitLab Context Brain. | |
| --- | |
| ## 🏗️ High-Level Architecture | |
| The project follows a **Modular Multi-Agent Architecture** running on **GitLab Runners**, coordinated by **LangGraph**. | |
| ### Tech Stack | |
| * **Language**: Python 3.10+ | |
| * **Orchestration**: [LangGraph](https://www.langchain.com/langgraph) (to manage agent state and transitions) | |
| * **AI Engine**: [Gemini 3.1](https://cloud.google.com/vertex-ai) (via Vertex AI SDK) | |
| * **Integrations**: | |
| * **GitLab**: `python-gitlab` (REST/GraphQL) + `glab` CLI | |
| * **GCP**: `google-cloud-*` SDKs (Logging, Error Reporting, Service Usage, Resource Manager) | |
| * **Runtime**: GitLab Duo Agent Platform (Custom Flows on Runners) | |
| --- | |
| ## 🤖 Agent Definitions | |
| ### 1. **GitLab Librarian (Context Agent)** | |
| * **Responsibility**: Gathers all repository-level data. | |
| * **Inputs**: `$AI_FLOW_CONTEXT` (MR Diff, Labels). | |
| * **Actions**: Search for related Issues, fetch previous MRs for the same files, identify `CODEOWNERS`. | |
| ### 2. **Cloud Sentinel (GCP Ops Agent)** | |
| * **Responsibility**: Gathers production health data. | |
| * **Actions**: Query Cloud Logging for error patterns in affected services; check Error Reporting for recurring production crashes linked to the code path. | |
| ### 3. **Gatekeeper (GCP Infra Agent)** | |
| * **Responsibility**: "Shift-Left" infrastructure validation. | |
| * **Actions**: | |
| * Compare code SDK usage with Terraform IAM policies. | |
| * Query GCP Quotas for the target region. | |
| * Run BigQuery `--dry-run` on modified SQL. | |
| ### 4. **The Architect (Synthesis Agent)** | |
| * **Responsibility**: Final reasoning and reporting. | |
| * **Actions**: Combine outputs from all agents into a structured, user-friendly GitLab comment. | |
| --- | |
| ## 🔄 Integration Flow | |
| 1. **Trigger**: Developer opens an MR or @mentions the agent. | |
| 2. **Deployment**: GitLab triggers a **Custom Flow** defined in `.gitlab/ai-agents/context-brain.yml`. | |
| 3. **Runner Activation**: A GitLab Runner starts a Python container. | |
| 4. **Execution**: | |
| * `main.py` initializes the LangGraph state. | |
| * Agents execute their tools in parallel. | |
| * Gemini synthesizes the findings. | |
| 5. **Output**: The agent uses `glab mr note` to post the final Intelligence Report. | |
| --- | |
| ## 📂 Project Structure (Simple) | |
| ```text | |
| . | |
| ├── .gitlab/ | |
| │ └── ai-agents/ | |
| │ └── context-brain.yml # Flow & Trigger config | |
| ├── agents/ | |
| │ ├── librarian.py # GitLab API logic | |
| │ ├── sentinel.py # GCP Ops logic | |
| │ └── gatekeeper.py # GCP Infra logic | |
| ├── main.py # LangGraph Orchestrator | |
| ├── requirements.txt # Python dependencies | |
| └── technical.md # This file | |
| ``` | |
| --- | |
| ## 🔑 Authentication & Security | |
| * **GitLab**: Uses the CI/CD job token (`$CI_JOB_TOKEN`) or a Project Access Token. | |
| * **GCP**: Uses **Workload Identity Federation** (recommended) or a Service Account Key stored in GitLab CI/CD Secrets. | |