Retrack

a release intelligence system that converts commit history into formatted changelogs, migration guides, and analytics dashboards, deployed automatically on every analysis run.

Comment

Inspiration

Git tags are timestamps with no memory.

A tag marks the moment a release happened. It doesn't explain what changed, why it mattered, who it affected, or what breaks if you upgrade. That context lives in commit messages written under pressure, in PR descriptions that reference tickets that reference Slack threads that no longer exist. Six months later, none of it is findable.

The insight behind ReTrack is that the information needed to produce complete release documentation already exists in every repository — it's just never been assembled. Commit ranges, diff content, conventional prefixes, MR links, tag dates — it's all there. The problem isn't missing data. It's that no one has time to connect it.

ReTrack started as a question: what if an AI agent could read a repository's entire version history the way a senior engineer would — understanding what changed, classifying it, detecting what breaks, and writing the documentation — and then commit that documentation back to the repo as a permanent record?

The answer is Trace.

What It Does

ReTrack is a GitLab Duo AI agent that analyzes a repository's version history and generates comprehensive release documentation as static files committed directly to the repo, with automatic deployment to a public hosted site on every run.

Core Capabilities:

Version parsing — Reads all Git tags and parses semantic versions in any format. Classifies each release as major, minor, or patch. Flags pre-releases (alpha, beta, rc). Maps the commit range between every consecutive tag pair, establishing the exact scope of each release.

Changelog generation — For each version range, analyzes every commit and categorizes it: Added, Changed, Fixed, Removed, Deprecated, Security.

Customer-facing release notes — Transforms technical changelog data into plain-language release summaries. Written to be scanned, not read.

Breaking change detection — Scans commit diffs for API signature changes, removed endpoints, renamed fields, and interface modifications. Generates step-by-step migration instructions per breaking change.

Release analytics — Calculates release frequency and intervals across the full version history. Identifies velocity trends (accelerating or decelerating). Produces a predicted next release date using moving averages across recent release intervals.

Numbered run history — Every documentation run is stored in its own numbered subfolder. Trace checks the repository state before writing.

Static documentation build — Generates a complete set of static HTML files per core run: interactive dashboard, release timeline, version comparison tool, per-release detail pages, breaking changes, migration guides, and a full data layer (releases.json, analytics.json). All committed to the repository in a single package commit.

Automatic hosting — On every commit to docs/retrack/, the CI pipeline automatically deploys to GitLab Pages and optionally to Firebase Hosting if configured. The public URL is reported by Trace at the end of every run.

Trace — the assistant persona — The agent's conversational interface is named Trace. Trace introduces itself at the start of every conversation, presents all analysis in structured formatted responses — tables, code blocks, headers — and always asks for confirmation before committing files. It never overwrites existing files without explicit user approval.

How It Was Built

ReTrack is a GitLab Duo custom agent and flow built on the GitLab AI Agent Platform.

Agent layer — Defined in agents/agent.yml as a GitLab Duo custom agent. The system prompt defines Trace's persona, analysis capabilities, run-numbered output structure and other core attributes. The agent uses Web UI-compatible tools only: list_repository_tree, list_commits, get_commit, get_commit_diff, get_repository_file, get_project, create_commit, grep, gitlab_commit_search, and gitlab_blob_search.

Flow layer — Defined in flows/flow.yml as a GitLab Duo custom flow with four sequential AgentComponent steps: version parser → changelog generator → release notes generator → documentation builder. Each step receives the output of the previous step via context:<component>.final_answer inputs. Toolset items use plain strings as required by the ai-catalog JSON schema. The flow can be triggered by assigning @ai-retrack-release-flow to any issue or MR.

CLI layer — A Python CLI (retrack_agent/cli.py) built with GitPython, python-gitlab, and Jinja2. Provides retrack scan and retrack init commands for local and CI use. Accepts --repo, --output, --since, and --run flags. Renders six Jinja2 HTML templates into the output directory.

Template layer — Six Jinja2 templates produce the static site: index.html.j2 (dashboard with Chart.js analytics), timeline.html.j2 (interactive release timeline), compare.html.j2 (version diff tool), release_detail.html.j2 (per-release pages), breaking_changes.html.j2, and migration_guides.html.j2. All templates share a consistent design system.

CI/CD layer — .gitlab-ci.yml handles three deployment paths: GitLab Pages (always on, via a mirror pipeline on a secondary repo), Firebase Hosting (optional, activated by setting FIREBASE_TOKEN and FIREBASE_PROJECT CI variables), and a manual CLI-based generation job on tag push.

What It Solves

The gap between a Git tag and a changelog is too wide — Pushing a tag creates a release marker but produces no documentation. A developer has to manually review commits, categorize changes, write notes, and update multiple files. For teams shipping frequently, this overhead compounds quickly. ReTrack closes this gap entirely — a tag push triggers a full documentation run with no manual steps.

Breaking changes are discovered by users, not teams — Without systematic diff analysis, breaking changes often reach users undocumented. ReTrack scans every commit diff for API and interface changes, generates migration guides automatically, and flags semver violations before they become support tickets.

Release analytics are invisible — Most teams have no visibility into their release velocity, feature-to-fix ratios, or release frequency trends. ReTrack surfaces this data automatically from the existing tag history, making release health a visible metric rather than an afterthought.

Documentation lives in someone's head — When the person who shipped a release leaves the team, the context for that release goes with them. ReTrack commits all documentation as static files to the repository, making release history a permanent, searchable, version-controlled record.

Each analysis run is ephemeral with no audit trail — Most AI interactions produce output that disappears when the session ends. ReTrack treats every run as a permanent record: numbered, dated, committed to the repo, and deployed to a public URL. Every analysis Trace performs is preserved and linkable.

Use Cases

Post-sprint release documentation A team ships v2.4.0 at the end of a two-week sprint. Instead of writing release notes manually, the lead opens the GitLab Duo sidebar and asks Trace to generate a changelog for v2.4.0. Trace analyzes the commit range, categorizes 23 commits, identifies one breaking API change, and presents a formatted changelog. The lead confirms, and Trace commits the documentation to docs/retrack/runs/4/ and reports the public URL — total time: under two minutes.

Breaking change audit before a major release A team is preparing v3.0.0 and needs to document all breaking changes since v2.0.0. They ask Trace to scan for breaking changes across the full v2.x range. Trace scans every commit diff, identifies six API signature changes and two removed endpoints, and generates a migration guide for each. The team reviews the output, confirms, and Trace commits breaking-changes.html and migration-guides.html as run 7 — permanently accessible at the run URL.

Customer announcement copy A product manager needs to write a customer-facing announcement for v4.1.0. They ask Trace for customer-facing release notes. Trace generates plain-language summaries of the most impactful changes, groups them by theme, and includes upgrade instructions for the one breaking change. The PM uses the output as the first draft of the announcement email.

What's Next

Diff-level change summaries — Instead of commit-level categorization, analyze the actual file diffs to produce function-level and API-level change descriptions, independent of commit message quality.

Slack and email delivery — Post release notes directly to a Slack channel or email list on every tag push, using the generated content as the message body.

Custom changelog templates — Allow teams to define their own changelog format and section structure via a .retrack.yml config file, replacing the default Keep a Changelog output.

Built With

Share this project:

Updates