https://github.com/elis-salobehaj/code-smith
Agentic Code Reviewer for GitLab merge requests.
https://github.com/elis-salobehaj/code-smith
agentic-ai bullmq bun code-review gitlab hono llm self-hosted typescript zod
Last synced: 16 days ago
JSON representation
Agentic Code Reviewer for GitLab merge requests.
- Host: GitHub
- URL: https://github.com/elis-salobehaj/code-smith
- Owner: elis-salobehaj
- License: apache-2.0
- Created: 2026-03-14T16:41:07.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-29T18:22:44.000Z (3 months ago)
- Last Synced: 2026-03-29T18:23:30.909Z (3 months ago)
- Topics: agentic-ai, bullmq, bun, code-review, gitlab, hono, llm, self-hosted, typescript, zod
- Language: TypeScript
- Homepage:
- Size: 1.97 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# CodeSmith
> AI-assisted, agentic code reviewer for GitLab merge requests.
CodeSmith is a self-hosted review service that listens to GitLab merge request events,
runs an agentic code-review pipeline against the diff and repository context, and posts
high-signal inline comments back to the MR.
It is built for teams that want code review automation without giving up control of their
runtime, provider stack, or deployment model.
---
## Table of Contents
- [Quick Start](#quick-start)
- [Features](#features)
- [Independent Evaluation](#independent-evaluation)
- [Showcase](#showcase)
- [Review Flow](#review-flow)
- [Deployment Modes](#deployment-modes)
- [Tech Stack](#tech-stack)
- [Configuration](#configuration)
- [Local Kubernetes](#local-kubernetes)
- [Webhook Setup](#webhook-setup)
- [Runtime Notes](#runtime-notes)
- [Documentation Hub](#documentation-hub)
- [Development Commands](#development-commands)
---
## Quick Start
```bash
# Configure the app
cp .env.example .env
# Install dependencies
bun install
# Run the webhook server
bun run dev
# Optional: run the worker when QUEUE_ENABLED=true
bun run worker
```
Health check:
```bash
curl http://127.0.0.1:8020/api/v1/health
```
For local Kubernetes validation:
```bash
bun run kind:up
bun run kind:port-forward
bun run kind:down
```
---
## Features
- 🤖 **Agentic review pipeline** — context agent, investigator loop, and reflection agent work together before anything is published.
- 🛠️ **Repo-aware tools** — the investigator can read files, search the codebase, and inspect directory structure inside a sandboxed repo clone.
- 🧩 **Repo-owned review config** — `.codesmith.yaml` supports repo-level exclusions, severity policy, and prompt guidance without redeploying CodeSmith.
- 🧠 **Multi-provider LLM fallback** — AWS Bedrock first, with optional OpenAI and Google Gemini fallback ordering.
- ☸️ **Kubernetes-ready** — raw manifests for webhook, worker, service, config, secrets, and local Valkey validation on KinD.
- 🔎 **Jira enrichment** — optionally pulls linked Jira ticket context from MR title and description.
- 📜 **Structured logging** — LogTape JSON logs with request correlation, pipeline context, and debug-file output.
---
## Independent Evaluation
If you want the honest build-vs-buy view before trying CodeSmith, read the full evaluation:
- [docs/AI-Code-Review-Tool-Evaluation.md](docs/AI-Code-Review-Tool-Evaluation.md)
That document is intentionally not a sales sheet. It compares CodeSmith against GitLab Duo and CodeRabbit, covers where each option is stronger or weaker, and explains why CodeSmith is compelling for teams that care about:
- self-hosted control over the review runtime and provider stack
- stronger data-sovereignty posture than SaaS review platforms
- prompt and workflow customization without vendor dependency
- agentic, repository-aware review instead of diff-only analysis
It also states the current limitations directly: CodeSmith is still pre-production, has no built-in organizational learning yet, and still needs the production-hardening work tracked in the Crown Plan.
If that tradeoff profile fits your team, the evaluation should give you a realistic picture of what CodeSmith already does well and what is still being built.
---
## Showcase
### Review Surface
|---|---|
|  |  |
| Off-by-one breaks TooMuchDataException boundary check and existing test. | Inverted health check condition reports healthy as errored and vice versa. |
```text
GitLab webhook -> router -> queue or inline dispatch -> pipeline -> Jira enrichment -> agents -> GitLab comments
```
1. GitLab sends a `merge_request` event or a `/ai-review` note event.
2. The router verifies `X-Gitlab-Token` and validates the webhook payload with Zod.
3. The request is either queued through BullMQ or run inline, depending on `QUEUE_ENABLED`.
4. The pipeline fetches MR metadata and diffs, then clones or updates the repo cache.
5. Optional Jira enrichment adds linked ticket context.
6. The agent pipeline investigates the change and filters weak or unsupported findings.
7. Verified findings are published back to GitLab as inline discussions and a summary note.
---
## Deployment Modes
| Mode | Use Case | Command / Entry |
|---|---|---|
| **Inline** | simplest local/dev flow | `bun run dev` |
| **Queued** | durable async review execution | `bun run dev` + `bun run worker` |
| **Docker Compose** | containerized local or server deployment | `docker compose up` |
| **KinD / Kubernetes** | local cluster validation and k8s parity | `bun run kind:up` |
When `QUEUE_ENABLED=true`, the webhook returns `202` only after BullMQ accepts the job.
If enqueue fails, the webhook returns `503` instead of silently dropping work.
---
## Tech Stack
| Layer | Technology |
|---|---|
| **Runtime** | Bun |
| **API** | Hono |
| **Language** | TypeScript (strict mode) |
| **Validation** | Zod |
| **Queue** | BullMQ + Valkey |
| **LLMs** | AWS Bedrock, OpenAI, Google Gemini |
| **GitLab Client** | `@gitbeaker/rest` |
| **Logging** | LogTape |
| **Infra** | Docker Compose, KinD, Kubernetes |
---
## Configuration
All configuration lives in the root `.env` file.
```bash
cp .env.example .env
```
### Core
| Variable | Description |
|---|---|
| `GITLAB_URL` | Base URL of the GitLab instance |
| `GITLAB_TOKEN` | Token used for API calls and authenticated clone/fetch operations |
| `GITLAB_WEBHOOK_SECRET` | Shared secret checked against `X-Gitlab-Token` |
| `PORT` | HTTP port, default `8020` |
| `LOG_LEVEL` | `debug`, `info`, `warn`, or `error` |
### Queueing
| Variable | Description |
|---|---|
| `QUEUE_ENABLED` | Enable BullMQ dispatch instead of inline fire-and-forget execution |
| `VALKEY_URL` | Valkey or Redis connection URL |
| `WORKER_CONCURRENCY` | Concurrent review jobs per worker |
| `REVIEW_JOB_TIMEOUT_MS` | Hard timeout per worker attempt |
### LLM Providers
| Variable | Description |
|---|---|
| `LLM_PROVIDER_ORDER` | Ordered provider list, e.g. `bedrock,openai` |
| `LLM_MODEL` | Bedrock model ID |
| `OPENAI_API_KEY` / `OPENAI_MODEL` | OpenAI fallback configuration |
| `GOOGLE_AI_API_KEY` / `GOOGLE_AI_MODEL` | Gemini fallback configuration |
### Jira Enrichment
| Variable | Description |
|---|---|
| `JIRA_ENABLED` | Enables Jira ticket enrichment |
| `JIRA_BASE_URL` | Jira Cloud base URL |
| `JIRA_EMAIL` / `JIRA_API_TOKEN` | Jira API credentials |
| `JIRA_PROJECT_KEYS` | Optional project-key allow-list |
| `JIRA_ACCEPTANCE_CRITERIA_FIELD_ID` | Optional acceptance-criteria custom field |
Full configuration reference: [docs/guides/GETTING_STARTED.md](docs/guides/GETTING_STARTED.md), [docs/context/CONFIGURATION.md](docs/context/CONFIGURATION.md), and [docs/guides/REPO_REVIEW_CONFIG.md](docs/guides/REPO_REVIEW_CONFIG.md)
### Repo-owned review config
CodeSmith now supports repository-level review configuration through `.codesmith.yaml` or `.codesmith.yml` at the repo root.
Current live consumers include:
- diff filtering through `exclude` and `file_rules.skip`
- repo-controlled severity thresholds through `severity.minimum`, `severity.block_on`, and per-rule overrides
- prompt guidance through `review_instructions` and matching `file_rules.instructions`
This repository includes a dogfooding example at [.codesmith.yaml](.codesmith.yaml). For authoring guidance and examples, see [docs/guides/REPO_REVIEW_CONFIG.md](docs/guides/REPO_REVIEW_CONFIG.md).
---
## Local Kubernetes
CodeSmith includes helper scripts for local KinD validation.
What the bootstrap does:
- creates the KinD cluster if it does not exist
- builds the local Docker image and loads it into the cluster
- generates ConfigMap and Secret resources from your local `.env`
- deploys Valkey, webhook, worker, and service manifests
- waits for rollouts to complete
Commands:
```bash
bun run kind:up
bun run kind:port-forward
bun run kind:down
```
The port-forward exposes the webhook service locally at `http://127.0.0.1:8020`.
---
## Webhook Setup
1. In GitLab, go to `Settings -> Webhooks`.
2. Set the webhook URL to `http://:8020/api/v1/webhooks/gitlab`.
3. Set the secret token to `GITLAB_WEBHOOK_SECRET`.
4. Enable merge request events.
5. Enable note/comment events if you want `/ai-review` manual triggers.
If GitLab cannot reach your workstation directly, use an SSH reverse tunnel:
```bash
ssh -N -R 127.0.0.1:8020:localhost:8020 gitlab-user@gitlab.example.com
```
Use `ssh -R`, not `ssh -L`, when the goal is to expose your local CodeSmith process to the remote side.
---
## Runtime Notes
- Webhook schemas are permissive about extra GitLab keys but strict about required fields.
- Provider-specific translation stays isolated behind the internal protocol boundary in `src/agents/llm-client.ts` and `src/agents/providers/`.
- Review jobs use exponential backoff, enforce `REVIEW_JOB_TIMEOUT_MS`, and copy terminal failures into the `review-dead-letter` queue.
- Individual Agent 2 tool failures are returned to the model as error `tool_result` blocks instead of aborting the full review.
- Findings that cannot be anchored to the diff are skipped for inline publication and preserved in the summary verdict flow.
- When `LOG_LEVEL=debug`, logs are also written to `logs/codesmith-dev.log`.
- Jira errors degrade safely: they are logged as warnings and never abort a review.
---
## Documentation Hub
| Guide | Description |
|---|---|
| [docs/AI-Code-Review-Tool-Evaluation.md](docs/AI-Code-Review-Tool-Evaluation.md) | Evidence-backed, non-sales comparison of CodeSmith vs GitLab Duo vs CodeRabbit |
| [docs/README.md](docs/README.md) | Main documentation index and phase status |
| [docs/guides/GETTING_STARTED.md](docs/guides/GETTING_STARTED.md) | Setup, env config, queueing, provider fallback, and KinD bootstrap |
| [docs/guides/DEVELOPMENT.md](docs/guides/DEVELOPMENT.md) | Bun commands, testing strategy, and development workflow |
| [docs/context/ARCHITECTURE.md](docs/context/ARCHITECTURE.md) | Unified architecture walkthrough |
| [docs/guides/REPO_REVIEW_CONFIG.md](docs/guides/REPO_REVIEW_CONFIG.md) | Repo-author guide for `.codesmith.yaml`, including examples and troubleshooting |
| [docs/context/CONFIGURATION.md](docs/context/CONFIGURATION.md) | Environment variables and `.codesmith.yaml` reference |
| [docs/context/WORKFLOWS.md](docs/context/WORKFLOWS.md) | End-to-end operational workflows |
---
## Development Commands
```bash
bun test
bun run typecheck
bun run check
bun run ci
```
## License
Apache 2.0 - see [LICENSE](LICENSE).