The problem I kept ignoring
Every time I opened a merge request, there was this familiar moment of dread. I had just spent hours writing code, and now I had to sit down and summarize it all in a description box. What changed? Why? What should reviewers look at?
Most of the time I'd write something like "fix login bug" and call it a day. My teammates did the same. Reviews were slow because nobody knew what to focus on.
The irony? The git diff already had everything. The AI just needed to read it.
Introducing mergist
mergist is a CLI tool that reads your git diff and generates a structured MR/PR description using AI — automatically in CI, or on-demand from your terminal or browser.
One command to get started:
npx mergist init
How it works
There are two ways to use it:
1. CI mode (recommended for teams)
mergist hooks into your CI pipeline and generates a description every time a MR/PR is opened or a new commit is pushed.
For GitLab:
mergist:
stage: mergist
image: node:20-alpine
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
script:
- npx mergist generate -p gitlab
allow_failure: true
For GitHub Actions, npx mergist init generates the workflow file automatically.
2. Manual mode
# Compare two branches and generate description
npx mergist diff -f feature-branch -t main
# Or update an existing MR/PR
npx mergist diff -u https://gitlab.com/org/repo/-/merge_requests/42
# Launch browser UI
npx mergist ui
What the generated description looks like
You can choose which sections to include during init:
| Section | Filled by | Description |
|---|---|---|
| Summary | AI | Brief overview of what changed and why |
| Changes | AI | Bulleted list with Add / Change / Remove prefixes |
| Review notes | AI | Code analysis: risk / warn / suggestion / good |
| Testing checklist | AI | What to verify before merging |
| Notes | Human | Left blank — never overwritten by AI |
| References | Human | Issue/ticket links — also preserved |
Smart merge — human notes stay untouched
One thing I'm proud of: the autoUpdate feature. When enabled, mergist re-runs on every new commit — but it only rewrites the AI-generated sections. Your manually filled notes and references are never touched. This was critical for team adoption.
Multi-provider support
You're not locked into one AI provider. During setup you can choose:
- OpenAI — GPT-4o, etc.
- Anthropic — Claude
- DeepSeek — very cost-effective
- Groq — fast inference
- Custom — any OpenAI-compatible endpoint
Just set AI_API_KEY in your environment — no code changes needed to switch providers.
Platform support
- GitLab — gitlab.com and self-hosted instances
- GitHub — github.com via GitHub Actions
Output language is also configurable: English (en) or Indonesian (id) via .mergistrc.
Try it out
npx mergist init
It'll walk you through selecting a platform, AI provider, CI config, and which sections to include. Takes about 2 minutes.
I'd love to hear how it fits into your workflow — especially if you're using self-hosted GitLab or a custom AI endpoint. Drop a comment or open an issue!
AI Disclosure
This article was drafted with the assistance of AI and subsequently reviewed, edited, and refined by the author. All technical content, code examples, and implementation details were validated before publication.
Top comments (0)