Build an AI Agent That Creates Release Notes
Learn to build a practical AI agent that generates release notes from git history using TypeScript, OpenAI, and GitHub Actions.
Before you start
Writing release notes by hand is tedious and error-prone, especially when you ship frequently. You end up with a list of commits that mean nothing to your users, or worse, you forget to mention breaking changes. In this tutorial, you will build an AI agent that reads your git history, summarizes the changes, and generates release notes in a format you choose.
The agent uses a simple loop: it collects commits since the last tag, asks a language model to summarize them, and writes the result to a file. You will run it locally first, then wire it into GitHub Actions so it runs automatically on every push to main. By the end, you will have a reusable script you can adapt to your own repository.
- Node.js 18 or later installed
- An OpenAI API key (or any LLM API you prefer)
- A git repository with at least one tag and a few commits
- Basic familiarity with TypeScript and the command line
Step 1: Set up the project
Create a new directory for the agent and initialize a TypeScript project. You will use the official OpenAI SDK and the simple-git library to interact with your repository.
mkdir release-notes-agent
cd release-notes-agent
npm init -y
npm install typescript tsx @types/node openai simple-git dotenv
npx tsc --init- The tsx package lets you run TypeScript files directly, so you do not need a separate build step during development.
- Store your API key in a .env file and load it with dotenv. Never commit the key to git.
Step 2: Write the agent loop
The core of the agent is a function that collects commits between two tags, sends them to the model, and returns the generated notes. You will use the OpenAI chat completions API with a system prompt that instructs the model to produce a concise changelog.
Create a file called agent.ts with the following code. It defines a function that takes a git repository path and a prompt, and returns the generated text.
import { OpenAI } from 'openai';
import { simpleGit } from 'simple-git';
import dotenv from 'dotenv';
dotenv.config();
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
async function getCommitsBetweenTags(repoPath: string, fromTag: string, toTag: string): Promise<string> {
const git = simpleGit(repoPath);
const log = await git.log({ from: fromTag, to: toTag });
return log.all.map(commit => `- ${commit.message}`).join('\n');
}
export async function generateReleaseNotes(commits: string): Promise<string> {
const systemPrompt = `You are a technical writer. Generate release notes from the given commit messages. Group changes into sections: Features, Bug Fixes, Breaking Changes. Use bullet points. Keep each entry under 20 words.`;
const response = await openai.chat.completions.create({
model: 'gpt-4o-mini',
messages: [
{ role: 'system', content: systemPrompt },
{ role: 'user', content: `Commits:\n${commits}` }
],
temperature: 0.3,
});
return response.choices[0].message.content || '';
}
// Example usage
async function main() {
const commits = await getCommitsBetweenTags('.', 'v1.0.0', 'v1.1.0');
const notes = await generateReleaseNotes(commits);
console.log(notes);
}
if (require.main === module) {
main().catch(console.error);
}- The simple-git log method accepts tag names directly. If you want to compare against the latest tag, you can use git.describe() to find it.
- The system prompt is where you control the style and structure of the output. Adjust it to match your project's conventions.
Step 3: Add a CLI wrapper
You will want to run this agent from the command line with arguments for the repository path and the tag range. Create a file called cli.ts that parses command-line arguments and calls the functions from agent.ts.
import { generateReleaseNotes, getCommitsBetweenTags } from './agent';
const args = process.argv.slice(2);
const repoPath = args[0] || '.';
const fromTag = args[1] || 'v1.0.0';
const toTag = args[2] || 'v1.1.0';
async function main() {
const commits = await getCommitsBetweenTags(repoPath, fromTag, toTag);
if (!commits) {
console.error('No commits found in the given range.');
process.exit(1);
}
const notes = await generateReleaseNotes(commits);
console.log(notes);
}
main().catch(err => {
console.error(err);
process.exit(1);
});- Run it with: npx tsx cli.ts . v1.0.0 v1.1.0
- The script assumes you have a .env file with OPENAI_API_KEY. Create one with: echo OPENAI_API_KEY=your_key_here > .env
Step 4: Test it locally
Before automating, make sure the agent works on your repository. Run the CLI with your actual tags. If you do not have tags, create a lightweight one first.
The output should be a nicely formatted release note. If you get an error, check that your API key is valid and that you have network access to OpenAI.
git tag v1.0.0
npx tsx cli.ts . v1.0.0 HEAD- Use HEAD as the toTag to include all commits since the tag.
- If the output is too long, lower the temperature or adjust the system prompt to be more concise.
Step 5: Automate with GitHub Actions
Now you will create a GitHub Actions workflow that runs the agent whenever a new tag is pushed. The workflow will check out the code, install dependencies, run the script, and commit the generated release notes back to the repository.
Create a file at .github/workflows/release-notes.yml with the following content.
name: Generate Release Notes
on:
push:
tags:
- 'v*'
jobs:
generate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Generate release notes
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: npx tsx cli.ts . ${{ github.ref_name }} HEAD > RELEASE_NOTES.md
- name: Commit and push
run: |
git config user.name github-actions
git config user.email github-actions@github.com
git add RELEASE_NOTES.md
git commit -m "Update release notes for ${{ github.ref_name }}"
git push- You need to add your OpenAI API key as a secret in your GitHub repository settings (Settings > Secrets and variables > Actions).
- The workflow triggers on any tag that starts with v, such as v1.2.0. Adjust the pattern if you use a different convention.
- The generated RELEASE_NOTES.md is committed to the repository. You can then use it in your GitHub release.
Verify it worked
After pushing a new tag, the workflow should run automatically. Check the Actions tab in your repository to see the logs. If the job succeeds, you should see a RELEASE_NOTES.md file at the root with the generated content.
To test without waiting for a tag, you can manually trigger the workflow using the workflow_dispatch event, but the current setup does not include that. Add it if you want.
Troubleshooting
If the workflow fails, here are common issues and fixes.
- Check that the OPENAI_API_KEY secret is set. If not, the script will throw an authentication error.
- Make sure fetch-depth: 0 is set so the workflow has access to all tags and history. Without it, git log may not find the tags.
- If you see 'No commits found', verify the tag names exist in the repository. Use git tag to list them.
- If the commit step fails, ensure the workflow has permission to push. By default, GITHUB_TOKEN has write access to the repository, but you may need to enable it in repository settings.
What I would do
For a production setup, I would add a few improvements. First, I would use a more structured output format, like JSON, so you can programmatically consume the release notes. Second, I would include the list of changed files to give the model more context. Third, I would add a retry mechanism for API calls to handle rate limits.
Here is a minimal enhancement: modify the system prompt to ask for JSON output and parse it in the script. This makes it easier to integrate with your release process.
const systemPrompt = `You are a technical writer. Generate release notes in JSON format with keys: features (array of strings), bugFixes (array of strings), breakingChanges (array of strings). Keep each item under 20 words.`;
// In generateReleaseNotes, parse the response:
const content = response.choices[0].message.content || '{}';
return JSON.parse(content);- You can also use the OpenAI function calling feature to enforce the schema.
- Consider caching the generated notes to avoid regenerating every time you run the agent.
FAQ
Answers to the questions that come up most often on this topic.
- Q: Can I use a different LLM provider? A: Yes, the same pattern works with any provider that has a chat completions API. Just swap the SDK and adjust the endpoint.
- Q: How do I handle very large commit histories? A: The model has a token limit. If you have many commits, you can summarize them in batches or filter out merge commits.
- Q: Can I run this without a tag? A: Yes, you can pass any two git refs, like branch names or commit hashes.
- Q: What if I want the release notes in a different format, like Markdown with tables? A: Change the system prompt to describe the format you want. The model will follow it.
Next action
Run the agent on your repository right now. If you do not have a project, create a test repo with a few commits and a tag, then run the CLI to see the output. Once you have it working locally, add the GitHub Actions workflow and push a new tag to see the automation in action.
Key takeaways
- Apply one concrete change from this post before collecting more reading.
- Prefer browser-side tools when the work involves secrets, tokens, or PII.
- Document the why next to the how so the next reviewer inherits context.
FAQ
- Who is this guide on ai-agent for?
- Working developers who need a practical take on build an ai agent that creates release notes — not a marketing overview. Skim the sections, apply one tip, then come back when you hit an edge case.
- Do I need an account to use the related tools?
- No. code.live tools run in your browser with no signup. Nothing you paste is uploaded to a server for the client-side utilities linked from this post.
- How often is this article updated?
- This post was published November 11, 2026. Fundamentals stay stable; check linked tool pages and official docs when version-specific behavior matters.