Skip to content

How it works & CI usage

Pipeline

  1. Collect — git log with a delimited format, parsed into commit objects (collectCommits / parseGitLog).
  2. Classify — each subject is parsed as a Conventional Commit (type, scope, !/BREAKING CHANGE), falling back to other.
  3. Group — commits are bucketed by type in a fixed display order, with breaking changes collected separately.
  4. Render — either a deterministic markdown template, or an LLM prompt built from the grouped commits and sent to Ollama.

The grouping happens before the LLM, so the model rewrites a clean, categorized list rather than raw commits — cheaper, more reliable, and it can't hallucinate features.

Use in CI (template mode, no LLM)

# .github/workflows/release.yml (excerpt)
- run: npx gitscribe "${{ github.event.release.tag_name }}"~1.."${{ github.event.release.tag_name }}" \
        --version "${{ github.event.release.tag_name }}" > NOTES.md
- run: gh release edit "${{ github.event.release.tag_name }}" --notes-file NOTES.md

Template mode is deterministic and dependency-free, so it's ideal for CI. Reserve --model for local runs where Ollama is available.

Library API

import { collectCommits, groupCommits, renderMarkdown, generateReleaseNotes } from 'gitscribe';
  • collectCommits(range?) / parseGitLog(raw) — read/parse commits.
  • groupCommits(commits) — { breaking, sections }.
  • renderMarkdown(commits, { version, date }) — offline markdown.
  • generateReleaseNotes(commits, { version, llm }) — template or LLM.