Reads every merge and generates audience-specific plain language notes automatically, committed back to your repo on every push. Works on GitHub Actions, GitLab CI, Bitbucket Pipelines, and any other CI system.
- See It in Action
- The Problem
- What Legibly Does
- How It Works
- Repo layout
- End-to-End Example
- Quick Start
- CI Platforms
- Personas
- Brand Voice
- License
What the engineer committed:
"Resolve race condition in payment processor. Lock TTL extended from 3.0s to 8.0s. Async validation pipeline reduces p99 checkout from 4.1s to 0.8s. Export jobs backgrounded to worker queue."
What Legibly generated for the VP:
"Checkout reliability incident resolved. p99 latency down 80% to under a second. A potential double-charge bug was caught and fixed before customer impact."
What Legibly generated for the customer:
"Checkout is fast now — under a second. Exports no longer block your browser. We fixed a bug that could charge you twice. Nothing you need to do."
What Legibly generated for the technical user:
"Payment lock TTL extended 3s → 8s (resolves race under high concurrency). Async validation pipeline: p99 4.1s → 0.8s. Export jobs moved to worker queue — no longer blocking the request thread. No API or schema changes."
Same commit. Three different notes. Each one says exactly what that audience needs to hear, and nothing they don't. Committed to your repo automatically on every merge.
Engineers are shipping at a pace that didn't exist two years ago. A single agentic session can produce what used to take a sprint. But the communication layer hasn't kept up. Product owners still spend hours manually reading PRs, decoding commit messages, and translating technical changes into language that customers can understand. That's not a scalable job. The result: enormous engineering value that never gets communicated. Customers don't know what changed. Stakeholders can't see the progress.
Legibly closes that gap. It automates the translation from technical work to customer value, so the communication layer moves at the speed of code.
→ The data behind this problem
On every merge or push, Legibly:
- Reads the git diff, commit messages, and PR description
- Pulls linked Jira ticket context (optional, works without Jira)
- Uses AI to extract the value signal: metrics, improvements, fixes, new capabilities
- Generates a separate release note for each configured persona (a named audience like
vp,customer, ortechnical-user, each with its own framing and structure) - Commits the notes to your repo as markdown files automatically, then prunes to keep the most recent files per persona (configurable, default 50)
That's the automatic path. It always runs, no action needed. A second path exists for teams that want to push notes further: once the markdown is committed, an engineer reads it and manually triggers the notification workflow to send to Slack, Teams, Confluence, or a webhook. AI-generated content is never sent automatically.
A third path is the MCP skill, which exposes the same translation pipeline conversationally inside any MCP-compatible client. Useful for on-demand use before a merge, mid-review, or during standup prep.
Note on output quality: Legibly translates what it's given. The quality of generated notes is directly proportional to the quality of PR descriptions and commit messages. See Engineering Process for what to write and why it matters.
The product owner's job shifts from writing to talking to customers. The communication still happens. It just doesn't require a human to produce it.
merge / push to configured branch
↓
CI pipeline fires (GitHub Actions, GitLab CI, Bitbucket, or any CI)
↓
reads: git diff + commits + PR/MR description + Jira tickets (optional)
↓
AI extracts value signals (metrics, changes, fixes, improvements)
↓
generates notes per persona (vp, customer, partner, etc.)
↓
commits markdown files to release-notes/{environment}/ ← always, no action needed
── if notify is configured ──────────────────────────────
↓
engineer reads the committed markdown files
↓
trigger "Send Notifications" manually → pick environment + persona
↓
hooks fire: Slack / Teams / Confluence / webhook
─────────────────────────────────────────────────────────
Content customization happens in two places:
config/voice.md: your brand voice, writing rules, banned phrases. Owned by product.personas/*.md: one file per audience. Add, edit, or remove. No code changes needed.
The automatic path (merge → generate → commit) runs on every push with no action needed. The notification path is always manual: an engineer reads the committed notes first, then decides to send.
| Folder / file | What it is |
|---|---|
docs/ |
Problem overview, setup guide, customization, notifications, and troubleshooting. |
personas/ |
One markdown file per audience. Add, edit, or remove. No code changes needed. |
voices/ |
Pre-built brand voice styles. Copy one to config/voice.md to get started. |
config/ |
Your team-config.yml (deploy points, AI provider) and voice.md (brand voice) live here. |
examples/ |
Sample config and a full end-to-end walkthrough. Start here. |
release-notes/ |
Where Legibly commits generated markdown. Organised by environment. |
action/ |
The CI action source code (TypeScript). Runs on GitHub Actions, GitLab CI, Bitbucket Pipelines, or any CI that can run Node.js. You don't need to touch this. |
prompts/ |
The AI prompt templates Legibly uses internally. |
See examples/e2e-example.md for a complete walkthrough:
- A team picks The Operator voice and copies it to
config/voice.md - They configure deploy points: which branches, which environments, which personas
- An engineer merges three commits to
main - Legibly reads the commits, PR description, and Jira tickets and extracts the value signals
- Three notes are generated and committed, one per configured persona
The final section shows the gap side-by-side: what the engineer wrote vs. what each audience needed to hear. Same facts. Right signal for the right person.
Requirements: Node.js 20+, an AI provider key or GitHub Copilot Enterprise access, and one of: GitHub, GitLab, Bitbucket, or any CI that can run Node.js.
# 1. Fork or clone this repo
# 2. Copy and configure the sample config
cp examples/sample-team-config.yml config/team-config.yml
# 3. Set your team name, AI provider, and deploy points (branches → personas)
# 4. Add your AI provider key to your CI secrets as AI_API_KEY
# Jira secrets are optional. Legibly works without them.
# 5. Test locally before pushing (see Local Development)
# 6. Push to a configured branch. Legibly runs automatically.See the Setup Guide for GitHub Actions setup, or the CI Platforms section below for GitLab, Bitbucket, and other CI systems.
| Platform | Config file | Setup guide |
|---|---|---|
| GitHub Actions | .github/workflows/ (included) |
docs/setup.md |
| GitLab CI | .gitlab-ci.yml (included) |
docs/gitlab-setup.md |
| Bitbucket Pipelines | bitbucket-pipelines.yml (included) |
docs/bitbucket-setup.md |
| Azure DevOps, CircleCI, Jenkins | Run node action/dist/index.js directly |
docs/other-ci-setup.md |
Personas are the core of Legibly. Each persona is a plain markdown file in the personas/ folder that defines a specific audience: who they are, what they care about, how they want to be spoken to, and the exact structure of their release notes.
No code changes are needed to manage personas. Add a file, edit a file, delete a file.
| File | Persona | Who they are | Typical environments |
|---|---|---|---|
vp.md |
The VP | C-suite or VP exec who owns the board and customer narrative. Reads the first bullet; if it doesn't connect to a business outcome, the email closes. No technical terms, ever. | Production |
customer.md |
The Customer | Power user who lives in the product daily. First question when an update lands: did this break what I depend on? Writes to felt experience, not implementation. | Production |
technical-user.md |
The Technical User | Senior engineer or admin keeping their systems working with this product. Scans for Breaking: first, then endpoint names, then metrics. Vague language means an untrustworthy note. |
Staging, Production |
partner.md |
The Partner | Engineer at a company that has built an integration on top of this platform. A breaking change they miss becomes their customer's problem. Needs exact API surfaces and hard deprecation timelines. | Production |
internal.md |
The Internal User | QA lead or PM running the staging sign-off. Reading this to build a test plan. Every change is a test scenario. Needs Jira IDs, setup steps, and edge cases, not customer-facing framing. | Staging / UAT |
Each file includes writing instructions, an exact output template, and a good/bad example. For instructions on adding, editing, or removing personas, see docs/customization.md.
If personas answer who you're writing for, brand voice answers how you sound doing it.
Your brand voice is a single file, config/voice.md, that applies universally to every persona on every run. It's the writing personality layer: tone, rhythm, banned phrases, formatting rules, how to translate technical metrics into plain language. One file controls all of it, across every audience, on every deployment.
Legibly ships with six voices, each tuned for a different brand personality. Pick the one that sounds like you, copy it to config/voice.md, and you're set.
| File | Voice | Style | Best for | Sample line |
|---|---|---|---|---|
the-operator.md |
The Operator | Direct, accountable, metrics-first | Ops-heavy products, reliability platforms | "Checkout errors: was 3.2%. Now 0.1%." |
the-visionary.md |
The Visionary | Minimalist, poetic, human-centered | Consumer products, design-forward platforms | "The wait is gone. Search is instant now." |
the-storyteller.md |
The Storyteller | Warm, authentic, failure-honest | B2C, lifestyle brands, community products | "We broke this last month. Here's what we learned." |
the-customer-champion.md |
The Customer Champion | Principled, clear, customer-obsessed | Enterprise B2B, long-term relationships | "Three enterprise teams flagged this in QBRs. It's resolved." |
the-straight-shooter.md |
The Straight Shooter | Raw, fast, zero corporate | Developer tools, startup products | "Search was broken for queries over 50 chars. Fixed. Go try it." |
the-connector.md |
The Connector | Empathetic, research-grounded, warm | Healthcare, education, HR, community | "A lot of you have been working around this for months. Here's what changed." |
For instructions on building a custom voice from scratch, see docs/customization.md.
- docs/overview.md: Industry context on the gap between engineering velocity and communication capacity
- docs/setup.md: Setup Guide, Engineering Process, Local Development
- docs/customization.md: Personas and Brand Voice customization
- docs/notifications.md: Output, Manual Runs, Notifications (Slack, Teams, Confluence, Webhook)
- docs/mcp.md: MCP Skill, on-demand translation in any MCP-compatible client
- docs/troubleshooting.md: Troubleshooting
MIT