convez.ai
MCP ServerDevOps & InfraestruturaAvançado
64johnlee

PipelineGuard

64johnlee/hackathon-pipeline-guard

Diagnóstico IA de pipelines GitLab com análise de root cause e propostas de fix

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server para diagnóstico automatizado de pipelines GitLab CI usando Gemini 2.5 Flash. Captura logs de falhas, identifica a raiz do problema e propõe correções com diffs, comentando automaticamente em merge requests. Inclui também SplunkGuard para investigações de observabilidade.

Instalação

$npx convez-ai 64johnlee/hackathon-pipeline-guard

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
—
Issues abertas
14
Contribuidores
2

Casos de uso

  • Diagnosticar falhas de CI/CD em pipelines GitLab automaticamente
  • Investigar problemas de observabilidade via Splunk com linguagem natural
  • Comentar análises e sugestões de correção em MRs de forma automática

Veredito

Solução completa e verificada em produção para automatizar diagnósticos de pipelines GitLab. Demonstra bem o uso de MCP servers em loops agenticos, mas requer conhecimento profundo de GitLab CI e Vertex AI para deployar e customizar.

README

A tradução para o português deste README ainda está na fila.


title: PipelineGuard emoji: 🔍 colorFrom: blue colorTo: blue sdk: docker app_port: 8080 pinned: false license: mit

PipelineGuard

AI-powered GitLab CI pipeline diagnostics using Gemini 2.5 Flash + a purpose-built MCP server.

PipelineGuard watches your GitLab CI pipelines. When one fails, it:

  1. Fetches job logs via a bundled stdio MCP server (pipelineguard.mcp_server)
  2. Analyzes root cause with Gemini 2.5 Flash (not just "build failed" — the exact reason)
  3. Proposes a targeted fix with a unified diff
  4. Comments the findings on the associated merge request

Verified end-to-end against a real failed gitlab-org/cli pipeline: ~46 seconds, 2 tool calls, correct root cause identified (config error: malformed git ref). The agentic loop terminates well under its 15-iteration safety cap.

Built for the Google Cloud Rapid Agent Hackathon — GitLab track and the UiPath AgentHack 2026 — Maestro Case track.

Try it against your pipeline → curl "https://pipeline-guard-fpgq3ij7ya-uc.a.run.app/demo?project=YOUR_ORG/YOUR_REPO" or open the live demo in your browser — no install, no auth required for public repos.

Looking for the Splunk side? This repo also ships SplunkGuard — a Gemini agent driven by the official Splunk MCP Server (Splunkbase App #7931) for natural-language observability investigations. See SPLUNK.md (submitted to the Splunk Agentic Ops Hackathon — Observability track).


Architecture

User / CI Webhook
        │
        ▼
┌───────────────────────────────────────────────────────────────────┐
│  PipelineGuardAgent  (pipelineguard/agent.py)                     │
│                                                                   │
│  ┌──────────────────┐    ┌─────────────────────────────────────┐  │
│  │  Gemini 2.5 Flash│◄──►│  Tool Call Loop   (≤15 iterations)  │  │
│  │  (Vertex AI /    │    │  Routes by tool name prefix:        │  │
│  │   AI Studio)     │    │    gl_*  →  Official GitLab MCP     │  │
│  └──────────────────┘    │    rest  →  PipelineGuard MCP       │  │
│                           └────────────┬──────────┬────────────┘  │
└────────────────────────────────────────┼──────────┼───────────────┘
                                         │          │
               ┌─────────────────────────┘          └────────────────────────┐
               │ StreamableHTTP (HTTPS)                   stdio (subprocess)  │
               ▼                                          ▼
┌──────────────────────────────────┐   ┌──────────────────────────────────────┐
│  Official GitLab MCP Server      │   │  pipelineguard.mcp_server (bundled)  │
│  gitlab.com/api/v4/mcp           │   │                                      │
│  Auth: Bearer <PAT>              │   │  list_pipelines                      │
│  Tool prefix: gl_                │   │  get_pipeline_jobs                   │
│                                  │   │  get_job_log                         │
│  gl_list_projects                │   │  find_merge_request_by_sha           │
│  gl_get_project                  │   │  create_merge_request_note           │
│  gl_list_merge_requests          │   └──────────────────────────────────────┘
│  gl_list_pipelines  …            │                     │
└──────────────────────────────────┘                     │
               │                                         │
               └────────────────────┬────────────────────┘
                                    ▼
                            GitLab API (HTTPS)

Dual MCP architecture: Gemini receives tools from both MCP servers simultaneously. The official GitLab MCP server (partner-required for the hackathon track) provides general project, MR, and pipeline context. PipelineGuard's bundled pipeline MCP server adds deep diagnosis tooling not yet in the official server — job log retrieval, structured failure categorisation, and MR note posting. Tool calls are routed by name prefix: gl_* goes to the official server, everything else to the bundled one. If the official server is unreachable, diagnosis continues uninterrupted with the bundled server.

Fallback mode (--direct): skips both MCP servers and uses python-gitlab directly in-process — single Gemini call instead of an agentic loop. Useful when MCP stdio subprocesses aren't allowed by the host (e.g. some sandboxed CI runners).


Quick Start

1. Install

git clone https://github.com/64johnlee/hackathon-pipeline-guard
cd hackathon-pipeline-guard
pip install -e .

No external services to install — the MCP server is a Python module that ships with the package. pip install is all you need (Python ≥ 3.10).

2. Configure

cp .env.example .env
# Edit .env — choose one auth mode:
#   AI Studio:  GEMINI_API_KEY  — https://aistudio.google.com/
#   Vertex AI:  GCP_PROJECT + GCP_LOCATION (see "Agent Builder" section below)
#
#   GITLAB_TOKEN  — GitLab PAT with api + read_repository scopes
#                   (also exported as GITLAB_PERSONAL_ACCESS_TOKEN to the MCP server)

3. Diagnose a failed pipeline

# Latest failed pipeline in a project
pipelineguard diagnose myorg/myrepo

# Specific pipeline ID
pipelineguard diagnose myorg/myrepo --pipeline 42

# Also post a comment on the MR
pipelineguard diagnose myorg/myrepo --comment

# Skip MCP server (direct API mode)
pipelineguard diagnose myorg/myrepo --direct

4. Watch mode (continuous monitoring)

# Poll every 60s, auto-comment on new failures
pipelineguard watch myorg/myrepo --interval 60 --comment

5. Webhook server (fully automated)

Run PipelineGuard as a persistent service that receives GitLab pipeline events:

# Install web extras
pip install 'pipelineguard[web]'

# Start the server
pipelineguard serve --port 8765 --comment

Then in GitLab: Settings → Webhooks → add http://your-host:8765/webhook/gitlab with the Pipeline events trigger. Every failed pipeline is diagnosed automatically and the result is posted as an MR comment — zero manual intervention.

Optional: set WEBHOOK_SECRET env var + the same token in GitLab for request validation.

# Test with the included example payload
curl -X POST http://localhost:8765/webhook/gitlab \
  -H "Content-Type: application/json" \
  -d @demo/webhook_payload_example.json
# → {"status":"diagnosed","root_cause":"Missing REDIS_URL...","category":"env_var_missing"}

Deploy to Cloud Run (hosted URL)

The fastest way to get a live, public endpoint for the hackathon submission:

export GCP_PROJECT=my-gcp-project
export GITLAB_TOKEN=glpat-...
# optional: export GEMINI_API_KEY=... (uses AI Studio; omit to use Vertex AI)
# optional: export WEBHOOK_SECRET=my-secret

bash deploy_cloudrun.sh

The script:

  1. Creates an Artifact Registry repo
  2. Builds the container with Cloud Build
  3. Stores secrets in Secret Manager
  4. Deploys to Cloud Run (min 0 → scales to 0 when idle, free tier friendly)
  5. Prints the live URL
======================================================
  PipelineGuard deployed!
  URL:      https://pipeline-guard-xxxx-uc.a.run.app
  Webhook:  https://pipeline-guard-xxxx-uc.a.run.app/webhook/gitlab
  Health:   https://pipeline-guard-xxxx-uc.a.run.app/health
======================================================

Then in GitLab: Settings → Webhooks → paste the webhook URL, enable Pipeline events.


Google Cloud Agent Builder (Vertex AI)

PipelineGuard runs natively on Vertex AI Agent Engine (Reasoning Engine), the managed serving platform in Google Cloud Agent Builder. This gives you a scalable, serverless deployment without managing containers.

Run locally with Vertex AI backend

Instead of an API key, authenticate with your GCP project:

gcloud auth application-default login

# Set env vars
export GCP_PROJECT=my-gcp-project
export GCP_LOCATION=us-central1
export GITLAB_TOKEN=glpat-...

# Same CLI — just add --vertex
pipelineguard diagnose myorg/myrepo --vertex
pipelineguard serve --vertex --port 8765

Deploy to Agent Engine

pip install 'pipelineguard[vertex]'

pipelineguard deploy \
  --gcp-project my-gcp-project \
  --gcp-location us-central1 \
  --gitlab-token glpat-...

This packages PipelineGuard as a Reasoning Engine resource in your project. Once deployed you can query it from any Google Cloud environment — Cloud Run, Cloud Functions, other agents — without shipping your own container:

import vertexai
from vertexai.preview import reasoning_engines

vertexai.init(project="my-gcp-project", location="us-central1")
app = reasoning_engines.ReasoningEngine("projects/.../reasoningEngines/...")
result = app.query(project="myorg/myrepo")
print(result["root_cause"])

Or use the Python API directly to deploy programmatically:

from pipelineguard.vertex_agent import PipelineGuardVertexApp

app = PipelineGuardVertexApp(gitlab_token="glpat-...", gcp_project="my-project")
app.set_up()
result = app.query(project="myorg/myrepo")

Example Output

See demo/sample_output.txt for a full annotated terminal session.

╭─ PipelineGuard · project myorg/backend · latest failed ─╮
│ mode: MCP                                                │
╰──────────────────────────────────────────────────────────╯
  → list_pipelines({"project_id": "myorg/backend"})
  → get_pipeline_jobs({"pipeline_id": 12847})
  → get_job_log({"job_id": 98231})

╭─ Diagnosis ─────────────────────────────────────────────╮
│ Root cause: ModuleNotFoundError: No module named         │
│ 'pydantic_v1'. pydantic v2 removed the v1 shim;         │
│ pin pydantic<2.0 or add pydantic[v1] to requirements.   │
│ Category: missing_dependency                             │
│ Affected jobs: test, integration-test                    │
╰──────────────────────────────────────────────────────────╯

Proposed fix for requirements.txt (high confidence):
  Pin pydantic to <2.0 or add pydantic[v1] shim

diff:
-pydantic>=1.9
+pydantic>=1.9,<2.0

How It Works

  1. MCP mode (primary): PipelineGuard spawns pipelineguard.mcp_server as a stdio subprocess (python -m pipelineguard.mcp_server). The server exposes 5 GitLab pipeline tools — list_pipelines, get_pipeline_jobs, get_job_log, find_merge_request_by_sha, create_merge_request_note — implemented on top of python-gitlab. Gemini 2.5 Flash receives those tools as FunctionDeclaration objects and autonomously decides which to call until it has enough context to diagnose the failure. In our benchmark against gitlab-org/cli pipeline #2552952663, the loop terminated in 2 tool calls.

  2. Structured output: The system prompt instructs Gemini to produce a natural-language explanation followed by a machine-readable JSON block, parsed into a typed DiagnosisReport with FixProposal objects. A regex extractor handles the occasional case where the model wraps the JSON in stray prose.

  3. Direct mode (--direct): All pipeline data is fetched upfront with python-gitlab in-process and packed into a single Gemini call — no MCP subprocess, no agentic loop. Same diagnostic quality, ~7s faster, but loses the per-tool granularity that MCP provides for tracing and reuse.

  4. Why a bundled MCP server? GitLab does not yet ship an official MCP server with pipeline-introspection tools. Rather than depend on third-party packages with mismatched tool surfaces, PipelineGuard ships its own — minimal, purpose-built for the agent that consumes it, and reusable from any MCP-compatible client (Claude Desktop, Cursor, etc.).


Failure Categories

CategoryExample
missing_dependencyModuleNotFoundError, apt-get: not found
env_var_missingKeyError: 'DATABASE_URL', secret not injected
config_errorInvalid .gitlab-ci.yml, bad Docker image tag
flaky_testNetwork timeout, random seed, timing assertion
logic_bugAssertionError, wrong expected value
infrastructureOOM kill, disk full, runner unavailable
permissionsEACCES, HTTP 403, cannot write to path

UiPath Maestro Integration

PipelineGuard integrates with UiPath Automation Cloud for the UiPath AgentHack 2026 — Maestro Case track.

Every pipeline failure becomes a Maestro Case with a full audit lifecycle:

GitLab failure → UiPath Orchestrator trigger → Main.xaml
  ├─ DiagnoseWithAI.xaml  → POST /api/diagnose       (Gemini 2.5 Flash)
  ├─ CreateMaestroCase.xaml → Orchestrator /odata/Cases
  ├─ HumanReview.xaml     → Action Center task (engineer approves/rejects)
  └─ PostApprovedFix.xaml → POST /api/uipath/callback → GitLab MR comment

Setup: see uipath/SETUP.md — takes ~20 minutes on free-tier Automation Cloud.

New API endpoints (for UiPath workflows):

  • POST /api/diagnose — structured diagnosis, called by DiagnoseWithAI.xaml
  • POST /api/uipath/callback — called by PostApprovedFix.xaml on engineer approval

Built with Claude Code

This project was developed using Claude Code (Anthropic's AI coding CLI) throughout the entire development cycle, qualifying for the +2 bonus points in the UiPath AgentHack judging rubric.

How Claude Code was used:

TaskClaude Code contribution
UiPath XAML workflowsGenerated all 5 .xaml files with correct WF activity bindings
Python endpoint designDesigned and implemented /api/diagnose + /api/uipath/callback
Dual-MCP architectureDesigned the gl_* prefix routing between official + bundled MCP servers
Presentation deckDrafted all 12 slides with benchmarks and judge-targeted framing
SETUP guideWrote step-by-step Automation Cloud configuration walkthrough
Devpost submission copyWrote all submission sections (inspiration, tech, accomplishments)
DebuggingDiagnosed and fixed MCP transport errors, Gemini structured-output quirks
Demo scenario libraryImplemented 5 realistic canned scenarios for the /demo endpoint

Evidence: this repository's entire uipath/ directory and the presentation/ directory were created in a single Claude Code session. The session transcript is preserved at: ~/.claude/projects/-mnt-c-WINDOWS-system32/464ad3d7-b05e-486b-bb90-ce098f44e565.jsonl

Bonus point documentation (per judging rubric):

"2 points: Clear documentation with verifiable evidence (prompts, screenshots, README section)"

This section, the commit history on feat/uipath-maestro-integration, and the session file above constitute that verifiable evidence.


Tech Stack

ComponentLibrary
LLMGemini 2.5 Flash via google-genai (AI Studio or Vertex AI)
Cloud deploymentCloud Run + Artifact Registry; Vertex AI Agent Engine for hosted agent
UiPath integrationStudio Web + Maestro Case + Action Center + Orchestrator REST
MCP serverpipelineguard.mcp_server (bundled, FastMCP / Python SDK)
MCP clientmcp (official Python SDK)
GitLab APIpython-gitlab (used by both MCP server and --direct fallback)
CLIclick + rich
Webhook serverFastAPI + uvicorn

License

MIT

Ver o original no GitHub

Bom para

Relacionados