Generic AI-powered release notes generator using the Vercel AI SDK.
Transform your git changelog into clean, business-readable release notes — with support for OpenAI, Anthropic, Mistral, Google, Ollama, and more. Usable as a CLI or as a library.
- generate — write the notes for a version range, in Markdown and/or HTML, in one or several languages.
- promote — carry a reviewed note to the next environment, word for word.
- prompt — ask about, revise, or merge notes already written, in your own words.
Fully customizable via configuration: language, instructions, output format, templates, and context files.
Security-first: API keys are never stored in config files. Only the key for your chosen provider is required via environment variable.
npm install -g ai-release-notesnpm install ai-release-notesAPI keys are never stored in config files. Only the key for the active provider is read from environment variables at runtime.
| Provider | CLI alias | Environment variable | Default models | Setup guide |
|---|---|---|---|---|
| OpenAI | gpt4, gpt, or default |
OPENAI_API_KEY |
GPT-4o, GPT-4o-mini | Get an OpenAI key |
| Anthropic | claude |
ANTHROPIC_API_KEY |
Claude 3.5 Sonnet, Claude 3 Opus | Get an Anthropic key |
| Mistral | mistral |
MISTRAL_API_KEY |
Mistral Large, Mistral Medium | Get a Mistral key |
gemini |
GOOGLE_API_KEY |
Gemini 1.5 Pro, Gemini 1.5 Flash | Get a Google key | |
| Azure OpenAI | azure |
AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT |
GPT-4o via Azure | Get Azure credentials |
| Ollama | ollama |
None for local use; optional OLLAMA_API_KEY for Ollama Cloud |
Local models, including Llama and Mistral | Set up Ollama |
→ Setting environment variables on macOS, Linux, Windows, or from a .env file.
npx ai-release-notes initThis creates .ai-release-notes/.ai-release-notes.yml. No API keys are stored in this file.
A bare .ai-release-notes.yml at the project root, from before this was the
default, is still found.
# The full Git history through v1.1.0, with the configured provider
npx ai-release-notes generate --to v1.1.0 --env PROD
# One range, with Anthropic — needs ANTHROPIC_API_KEY
npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env PROD --with claude
# Print to the terminal instead of writing release files and indexes
npx ai-release-notes generate --to v1.1.0 --env PROD --stdoutFiles are saved where your configuration says, and the run reports the paths it updated together with the tokens it spent.
→ Generating release notes — CLI options, --dry-run, release dates, context files.
A note written for QUA has already been read and agreed on. Promoting it to PROD reuses those files instead of asking a model to write them again — no prompt is built, no provider is called, no API key is needed:
# Everything PROD is missing, in one command
npx ai-release-notes promote --from-env QUA --to-env PROD
# Or one explicit range
npx ai-release-notes promote --from-env QUA --to-env PROD --from v1.0.0 --to v1.1.0When several releases cover the range they are merged section by section, and a model is asked for one thing only: the single opening that covers them all.
→ Promoting a release — CLI options, merge rules, environment folders.
A generated note is rarely wrong so much as not yet right. Regenerating loses
every correction already made to it, so prompt opens an environment as a
release-note assistant:
npx ai-release-notes prompt --env PROD💬 What would you like to know or change?
› compare the intended audience of the last two notes
› combine those releases and simplify the introduction
› save
Ask arbitrary questions grounded in the open release files, target a particular
version or language, revise text, or merge a contiguous range into one note.
Answers are read-only. Every revision, created or deleted file, and release-index
update stays staged until you ask to save; undo, reset, and dry-run cover merges
as well. In CI, pass requests as --ask instead of answering them.
→ Talking to your release notes — questions, merging, CLI options, CI mode, HTML pages.
import { generate } from "ai-release-notes";
const result = await generate({
fromVersion: "v1.0.0",
toVersion: "v1.1.0",
environment: "PROD",
provider: "claude", // only ANTHROPIC_API_KEY is needed
format: "html",
toDir: "./docs/releases",
context: ["./specs/api-v2.md", "./docs/models/"],
});
console.log(result.markdown, result.html);promote(options) returns the files a promotion would write without writing
them, and PromptSession answers questions or stages revisions and merges
against notes already on disk, saving only when you say so.
→ Programmatic API — generate, promote, PromptSession, and the steps they are built from.
| Guide | What it covers |
|---|---|
| API keys | A key per provider, and where to put it |
| Generating release notes | generate, CLI options, dates, context files |
| Promoting a release | promote, merging a range, environment folders |
| Talking to your release notes | prompt, questions, revisions, merges, CI mode |
| Configuration | .ai-release-notes.yml, output paths, indexes, templates |
| Instructions | What the model is told to write |
| Programmatic API | Using the package as a library |
| CI/CD integration | GitHub Actions, secrets, non-interactive runs |
The example configuration is annotated, and the examples guide walks through a first run.
Commit messages come from anyone who can land a commit, and a config file travels
with the repository. Both are treated as untrusted: a scope guard no
configuration key removes opens every system prompt, the changelog and context
reach the model in labelled blocks, model-written markup is escaped and its link
targets restricted, and git.maxCommits caps what one run can spend.
A release note is still model output written from unreviewed input. Review one before publishing it. Full details and reporting instructions are in security.md.
If you find any issues or have suggestions for improvement, feel free to open an issue or submit a pull request. Contributions are welcome!
Before getting started, please read our Contribution Guidelines.
This project is governed by the Code of Conduct; security issues should follow the Security Policy.
Love ai-release-notes? Give our repo a star ⭐ ⬆️.
This project is licensed under the MIT License - see the LICENSE file for details.