Codeward

Open-source AI agent platform for GitLab Community Edition (self-hosted).

Сodeward is a sidecar service that brings AI-powered code reviews, pipeline debugging, security triage, and conversational assistance to GitLab CE - without requiring GitLab Ultimate or the Duo Agent Platform. Connect any LLM provider via LiteLLM and run agents on your own infrastructure.

Features

• Automated Code Reviews - Inline comments, severity ratings, incremental reviews on push
• Incremental Reviews - Only reviews new changes, auto-resolves addressed threads
• Pipeline Debugging - Diagnoses CI/CD failures with root cause analysis
• Security Triage - Analyzes SAST/DAST/dependency scan results, flags false positives
• Chat Assistant - @mention the bot for questions about MRs, code, and issues
• Multi-Agent Flows - YAML-defined workflows that chain agents and GitLab actions (issue → MR, full review, pipeline fix)
• Custom Agents - Define your own agents via YAML with custom prompts and triggers
• MCP Server - Exposes GitLab tools, resources, and prompts to IDEs / LLM clients at /mcp (optional bearer auth)
• External MCP Clients - Agents can call tools from any external MCP server (streamable-http / SSE) you configure
• Model Flexibility - Route to any provider (OpenRouter, Anthropic, OpenAI, Ollama) via LiteLLM
• Rate Limiting - Per-project, per-user, and global rate limits with cooldowns
• Privacy - Runs on your infrastructure, sensitive data is redacted before LLM calls

How does Codeward compare to GitLab Duo

Feature	Codeward	GitLab Duo
GitLab Edition	CE (free)	Premium / Ultimate + Duo add-on
Hosting	Self-hosted, your infrastructure	SaaS or self-hosted (17.6+)
LLM Provider	Any via LiteLLM (OpenRouter, Anthropic, Ollama, etc.)	Claude / Codex / Gemini; custom via self-hosted
Code Review	Inline comments + summary + severity ratings	Inline comments + MR summary + custom instructions
Pipeline Debug	Root cause analysis, error classification, flaky detection	Root cause analysis, suggested fixes, auto-fix MRs
Security Triage	FP detection + remediation (SAST/DAST/dependency/secret/container)	SAST/secret FP detection (confidence scores), agentic resolution
Chat	@mention with history, slash commands	Duo Chat with history, IDE + web
Multi-Agent Flows	YAML-defined flows (issue-to-MR, full review, pipeline fix)	Duo Flows (Software Development Flow, custom flows)
Custom Agents	YAML + Python extensibility with toolkits	Duo Agent Platform (custom agents, MCP, Flows)
Incremental Reviews	Yes (inter-diff, auto thread resolution)	No
Cost	LLM API costs only (open source, BSD-3)	Premium/Ultimate + Duo add-on ($19/user/mo), credit-based

Quick Start

Codeward is designed to run as a local Python service while its infrastructure dependencies (Redis, LiteLLM, and the Postgres that backs LiteLLM) run in Docker. This matches the make-driven developer workflow in this repository.

Prerequisites: Python 3.14+, uv, Docker + Docker Compose, a running PostgreSQL instance for Codeward (see note below), and a GitLab CE instance with a bot Personal Access Token.

# 1. Clone
git clone https://github.com/Relrin/codeward.git && cd codeward

# 2. Configure
cp .env.example .env
cp litellm-config.example.yaml litellm-config.yaml
# Edit .env -- set GITLAB_URL, GITLAB_TOKEN, GITLAB_WEBHOOK_SECRET,
#              at least one model API key (e.g. OPENROUTER_API_KEY),
#              LITELLM_URL=http://localhost:4000,
#              REDIS_URL=redis://localhost:6379/0,
#              DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/codeward

# 3. Start infrastructure (Redis + LiteLLM + its Postgres)
docker compose up -d

# 4. Install dependencies & run migrations
uv sync
make migrate

# 5. Start the app (and, in another terminal, the flow worker)
make run                # http://localhost:8420 with hot-reload
make worker             # Redis-backed worker for multi-agent flows

# 6. Register the GitLab webhook
make setup              # equivalent to: uv run python scripts/setup_gitlab.py

# 7. Verify
curl http://localhost:8420/health
# -> {"status": "ok", "version": "0.1.0", "database": "ok", "litellm": "ok"}

About the database. Codeward's own data (agent runs, review state, flow state metadata) is stored in the database pointed to by DATABASE_URL. The litellm-db container in docker-compose.yml is dedicated to LiteLLM -- run a separate PostgreSQL instance for Codeward. SQLite (sqlite+aiosqlite:///./data/codeward.db) also works for quick trial runs.

Running everything in Docker (optional)

If you'd rather not run Codeward via uv, the repository also ships a full Docker profile that additionally starts the codeward app and codeward-worker containers:

docker compose --profile full up --build -d

This is useful for production-style deployments. For day-to-day development, the local uv/make run workflow above is faster and gives you hot-reload.

Agents

Agent	Description	Trigger	Auto?
Code Reviewer	Reviews MR diffs for issues, posts inline comments	MR open/update	Yes
Chat	Answers questions about MRs, code, and issues	@mention	No
Pipeline Debugger	Diagnoses CI/CD pipeline failures	Pipeline failure	Yes
Security Triage	Triages security scanner findings	Security scan job	Optional

Usage

@Mention

@codeward What does this function do?
@codeward Can you explain the changes in this MR?

Slash Commands

@codeward /review     - Request a code review
@codeward /debug      - Diagnose pipeline failure
@codeward /security   - Run security triage
@codeward /explain    - Explain the current diff
@codeward /help       - Show available commands

Multi-Agent Flows

Flows chain multiple agents into end-to-end workflows:

@codeward /implement      - Analyze issue → generate code → self-review → open MR
@codeward /full-review    - Code review + security triage + summary
@codeward /fix-pipeline   - Diagnose pipeline failure → post report

Flows are defined as YAML in agents/flows/ and execute step-by-step via the Redis-backed worker (make worker). Track progress via GET /flows/{flow_id}. See docs/flows.md for details.

Model Context Protocol (MCP)

Codeward integrates with the Model Context Protocol in two ways:

• As an MCP server. A FastMCP server is mounted at /mcp, exposing GitLab-aware tools (list_merge_requests, get_merge_request_diff, post_merge_request_comment, search_code, ...), resources (gitlab://project/{path}/readme, .../merge-requests/open, ...), and prompts (review_merge_request, explain_pipeline_failure, summarize_issue). Optional bearer-token auth via CODEWARD_MCP_KEY. Point Claude Desktop, Cursor, or any MCP client at http://localhost:8420/mcp.
• As an MCP client. Agents can be granted tools from any external MCP server you declare under codeward.mcp_servers in codeward.yml. Supports streamable-http and sse transports, bearer / header / none auth, and ${ENV_VAR} expansion in URLs and tokens.

See docs/mcp.md for the full reference.

Automatic Triggers

Code reviews and pipeline debugging run automatically when MRs are opened/updated or pipelines fail.

Project Configuration (.codeward.yml)

codeward:
  review_rules:
    - "Follow PEP 8 style guidelines"
  skip_paths:
    - "*.lock"
    - "vendor/**"
  disabled_agents:
    - security-triage

Development Setup

The Quick Start above is the development setup. The full set of make targets defined in the Makefile:

Target	Command	Purpose
make run	uv run uvicorn codeward.main:app --factory --reload --host 0.0.0.0 --port 8420	Start the Codeward web app with hot-reload
make worker	uv run python -m codeward.worker	Start the Redis-backed flow worker
make migrate	uv run alembic upgrade head	Apply database migrations
make setup	uv run python scripts/setup_gitlab.py	Register the GitLab webhook for a project
make test	uv run pytest -v	Run the test suite
make lint	uv run ruff check .	Lint with ruff
make fmt	uv run ruff format .	Format with ruff
make docker-up	docker compose up -d	Start Redis + LiteLLM + LiteLLM's Postgres
make docker-down	docker compose down	Stop the infrastructure stack

Connecting GitLab Webhooks

Scenario	Solution
Same machine / LAN	http://192.168.x.x:8420/webhook
Remote / cloud	Use a tunnel: ngrok http 8420
Both in Docker	Same Docker network

Model Routing

The litellm-config.yaml defines model tiers routed via the LiteLLM proxy. The shipped defaults are:

Tier	Default Model	Purpose
fast	openai/gpt-4.1-mini	Quick, low-cost reasoning — triage, mention parsing, short chat replies
strong	anthropic/claude-sonnet-4 via OpenRouter	Complex reasoning — full code reviews, security triage
code	qwen/qwen3.5-35b-a3b via OpenRouter	Code-focused tasks — diff review, code generation in flows

Each model_name in litellm-config.yaml corresponds to a tier alias referenced from codeward.yml (models.fast, models.strong, models.code). The agents pick a tier; LiteLLM resolves the tier to the underlying provider model.

Make sure the corresponding API keys are set in .env:

OPENAI_API_KEY=sk-...           # for fast (gpt-4.1-mini)
OPENROUTER_API_KEY=sk-or-v1-... # for strong + code

See docs/configuration.md for the full configuration reference.

License

The Codeward is published under the BSD 3-Clause license. For details see the LICENSE file.