Spaces:
Running
Running
File size: 3,151 Bytes
b301207 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 | # 🛠️ 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.
|