# m13tlabs/ai-agent-for-gitlab architecture

> Architecture diagram of the GitHub repository m13tlabs/ai-agent-for-gitlab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m13tlabs/ai-agent-for-gitlab
- Repository: https://github.com/m13tlabs/ai-agent-for-gitlab

## Overview

The product receives GitLab comment and merge-request events, decides whether to start an agent job, and launches a CI pipeline. The runner prepares the repository and context, invokes OpenCode (with an optional MCP server), then reports results back to GitLab. Separate capabilities include rate limiting, merge-request review suggestions, automated GitLab setup, and Kubernetes deployment. Edges reflect excerpted calls or README-documented behavior; unsampled setup and chart internals are represented only at their supported directory paths.

Main entry points: [`agent-image/scripts/src/runner.ts`](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/runner.ts) (Job orchestration), [`gitlab-app/src/index.ts`](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/index.ts) (Event handling), [`agent-image/scripts/mcp/mcp.ts`](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/mcp/mcp.ts) (MCP server), [`charts/ai-agent-for-gitlab`](https://github.com/m13tlabs/ai-agent-for-gitlab/tree/develop/charts/ai-agent-for-gitlab) (Kubernetes chart)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_webhook["Webhook app"]
  node_webhook_app["Webhook endpoint<br/>[index.ts]"]
  node_event_handling["Event handling<br/>[index.ts]"]
  node_rate_limit["Rate limiting<br/>[limiter.ts]"]
  node_app_gitlab_api["GitLab API client<br/>[gitlab.ts]"]
  node_review_prompt["Review prompting<br/>[index.ts]"]
end

subgraph group_runner["CI agent runner"]
  node_runner_entry["Runner entry<br/>[ai-runner.ts]"]
  node_runner_flow["Job orchestration<br/>[runner.ts]"]
  node_job_context["Job context<br/>[context.ts]"]
  node_repo_git["Repository operations<br/>[git.ts]"]
  node_runner_config["Configuration checks<br/>[config.ts]"]
  node_job_output["Job output<br/>[output.ts]"]
end

subgraph group_integrations["GitLab and AI integrations"]
  node_opencode["OpenCode execution<br/>[opencode.ts]"]
  node_mcp_server["MCP server<br/>[mcp.ts]"]
  node_runner_gitlab_api["Runner GitLab API<br/>[gitlab.ts]"]
  node_suggestions["Code suggestions<br/>[suggestion.ts]"]
end

subgraph group_operations["Deployment and setup"]
  node_gitlab_setup["GitLab setup automation<br/>[setup.ts]"]
  node_helm["Kubernetes chart"]
end

node_gitlab_user(("GitLab user"))
node_gitlab["GitLab"]
node_redis[("Redis rate store")]
node_pipeline["CI pipeline"]

node_gitlab_user -->|"mentions @ai / assigns reviewer"| node_gitlab
node_gitlab -->|"sends event"| node_webhook_app
node_webhook_app -->|"routes event"| node_event_handling
node_event_handling -->|"checks limit"| node_rate_limit
node_rate_limit -->|"tracks requests"| node_redis
node_event_handling -->|"builds review prompt"| node_review_prompt
node_event_handling -->|"requests pipeline and GitLab actions"| node_app_gitlab_api
node_app_gitlab_api -->|"calls API"| node_gitlab
node_event_handling -->|"triggers job"| node_pipeline
node_pipeline -->|"runs agent"| node_runner_entry
node_runner_entry -->|"starts"| node_runner_flow
node_runner_flow -->|"builds context"| node_job_context
node_runner_flow -->|"validates"| node_runner_config
node_runner_flow -->|"prepares checkout"| node_repo_git
node_repo_git -->|"clones, pulls, and pushes repository"| node_gitlab
node_runner_flow -->|"runs agent"| node_opencode
node_opencode -->|"configures MCP command"| node_mcp_server
node_mcp_server -.->|"accesses GitLab"| node_gitlab
node_runner_flow -->|"posts comments"| node_runner_gitlab_api
node_runner_gitlab_api -->|"posts result"| node_gitlab
node_runner_flow -->|"writes status"| node_job_output
node_review_prompt -->|"sets review job variables"| node_pipeline
node_mcp_server -->|"uses suggestion helpers"| node_suggestions
node_suggestions -.->|"posts native suggestions"| node_gitlab
node_gitlab_setup -.->|"configures bot account"| node_gitlab
node_helm -.->|"deploys app"| node_webhook_app
node_helm -.->|"supports Kubernetes deployment"| node_pipeline

click node_webhook_app "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/index.ts"
click node_event_handling "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/index.ts"
click node_rate_limit "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/limiter.ts"
click node_app_gitlab_api "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/gitlab.ts"
click node_runner_entry "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/ai-runner.ts"
click node_runner_flow "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/runner.ts"
click node_job_context "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/context.ts"
click node_repo_git "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/git.ts"
click node_runner_config "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/config.ts"
click node_job_output "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/output.ts"
click node_opencode "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/opencode.ts"
click node_mcp_server "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/mcp/mcp.ts"
click node_runner_gitlab_api "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/gitlab.ts"
click node_suggestions "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/suggestion.ts"
click node_review_prompt "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/index.ts"
click node_gitlab_setup "https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/setup.ts"
click node_helm "https://github.com/m13tlabs/ai-agent-for-gitlab/tree/develop/charts/ai-agent-for-gitlab"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webhook_app,node_event_handling,node_rate_limit,node_app_gitlab_api,node_review_prompt,node_gitlab_user toneBlue
class node_runner_entry,node_runner_flow,node_job_context,node_repo_git,node_runner_config,node_job_output,node_redis toneAmber
class node_opencode,node_mcp_server,node_runner_gitlab_api,node_suggestions toneMint
class node_gitlab_setup,node_helm toneRose
class node_gitlab,node_pipeline toneIndigo
```

## Components

### Webhook app

- [Webhook endpoint](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/index.ts): `gitlab-app/src/index.ts`
- [Event handling](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/index.ts): `gitlab-app/src/index.ts`
- [Rate limiting](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/limiter.ts): `gitlab-app/src/limiter.ts`
- [GitLab API client](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/gitlab.ts): `gitlab-app/src/gitlab.ts`
- [Review prompting](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/index.ts): `gitlab-app/src/index.ts`

### CI agent runner

- [Runner entry](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/ai-runner.ts): `agent-image/scripts/ai-runner.ts`
- [Job orchestration](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/runner.ts): `agent-image/scripts/src/runner.ts`
- [Job context](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/context.ts): `agent-image/scripts/src/context.ts`
- [Repository operations](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/git.ts): `agent-image/scripts/src/git.ts`
- [Configuration checks](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/config.ts): `agent-image/scripts/src/config.ts`
- [Job output](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/output.ts): `agent-image/scripts/src/output.ts`

### GitLab and AI integrations

- [OpenCode execution](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/opencode.ts): `agent-image/scripts/src/opencode.ts`
- [MCP server](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/mcp/mcp.ts): `agent-image/scripts/mcp/mcp.ts`
- [Runner GitLab API](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/gitlab.ts): `agent-image/scripts/src/gitlab.ts`
- [Code suggestions](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/agent-image/scripts/src/suggestion.ts): `agent-image/scripts/src/suggestion.ts`

### Deployment and setup

- [GitLab setup automation](https://github.com/m13tlabs/ai-agent-for-gitlab/blob/develop/gitlab-app/src/setup.ts): `gitlab-app/src/setup.ts`
- [Kubernetes chart](https://github.com/m13tlabs/ai-agent-for-gitlab/tree/develop/charts/ai-agent-for-gitlab): `charts/ai-agent-for-gitlab`

### Other components

- **GitLab user**
- **GitLab**
- **Redis rate store**
- **CI pipeline**

## Connections

- GitLab user → GitLab: mentions @ai / assigns reviewer (evidence: `README.md`)
- GitLab → Webhook endpoint: sends event (evidence: `README.md`)
- Webhook endpoint → Event handling: routes event (evidence: `gitlab-app/src/index.ts`)
- Event handling → Rate limiting: checks limit (evidence: `gitlab-app/src/index.ts`)
- Rate limiting → Redis rate store: tracks requests (evidence: `gitlab-app/src/limiter.ts`)
- Event handling → Review prompting: builds review prompt (evidence: `gitlab-app/src/index.ts`)
- Event handling → GitLab API client: requests pipeline and GitLab actions (evidence: `gitlab-app/src/index.ts`)
- GitLab API client → GitLab: calls API (evidence: `gitlab-app/src/gitlab.ts`)
- Event handling → CI pipeline: triggers job (evidence: `gitlab-app/src/index.ts`)
- CI pipeline → Runner entry: runs agent (evidence: `README.md`)
- Runner entry → Job orchestration: starts (evidence: `agent-image/scripts/ai-runner.ts`)
- Job orchestration → Job context: builds context (evidence: `agent-image/scripts/src/runner.ts`)
- Job orchestration → Configuration checks: validates (evidence: `agent-image/scripts/src/runner.ts`)
- Job orchestration → Repository operations: prepares checkout (evidence: `agent-image/scripts/src/runner.ts`)
- Repository operations → GitLab: clones, pulls, and pushes repository (evidence: `agent-image/scripts/src/git.ts`)
- Job orchestration → OpenCode execution: runs agent (evidence: `agent-image/scripts/src/runner.ts`)
- OpenCode execution → MCP server: configures MCP command (evidence: `agent-image/scripts/src/opencode.ts`)
- MCP server → GitLab: accesses GitLab
- Job orchestration → Runner GitLab API: posts comments (evidence: `agent-image/scripts/src/runner.ts`)
- Runner GitLab API → GitLab: posts result (evidence: `agent-image/scripts/src/gitlab.ts`)
- Job orchestration → Job output: writes status (evidence: `agent-image/scripts/src/runner.ts`)
- Review prompting → CI pipeline: sets review job variables (evidence: `README.md`)
- MCP server → Code suggestions: uses suggestion helpers (evidence: `agent-image/scripts/mcp/mcp.ts`)
- Code suggestions → GitLab: posts native suggestions
- GitLab setup automation → GitLab: configures bot account (evidence: `README.md`)
- Kubernetes chart → Webhook endpoint: deploys app (evidence: `README.md`)
- Kubernetes chart → CI pipeline: supports Kubernetes deployment (evidence: `README.md`)
