Build a Custom AI-Powered Changelog Generator with Python and Git: A Developer’s Practical Guide

Let’s be honest. Writing changelogs is the chore every developer hates. You ship a release, and then you spend 20 minutes digging through `git log`, trying to remember what that cryptic commit message “fix: wip” actually meant. It’s tedious. It’s error-prone. And honestly, most teams just skip it.

But changelogs matter. They’re the first thing your users see when you push a new version. A bad changelog means confused users, more support tickets, and a product that looks unprofessional.

Docker Optimization for Real Projects: 6 Hard-Won Tips from Production

Summary: You already know the basics of running Docker, but everything falls apart when you deploy to production?… ...

Read more

So let’s automate it.

In this tutorial, I’ll show you how to build a custom AI-powered changelog generator using Python and Git. We’ll hook it into GPT-4o (or any LLM) to turn your messy commit history into clean, categorized release notes. You’ll have a working script by the end, and I’ll show you how to plug it into your CI/CD pipeline so it runs automatically on every release.

Build a Custom AI Terminal Assistant with Python: A Complete Step-by-Step Developer Tutorial

Build a Custom AI Terminal Assistant with Python: A Complete Step-by-Step Developer Tutorial I spend way too much… ...

Read more

Why Build Your Own Instead of Using a SaaS Tool?

Good question. There are plenty of changelog SaaS tools out there. But here’s the thing: they’re all black boxes. You don’t control the prompt. You don’t control the output format. And you definitely don’t control the data leaving your repo.

Building your own gives you:

• Full control over the prompt. You can tune it to match your team’s tone and conventions.
• Privacy. Your commit messages never leave your infrastructure.
• Customization. Want to filter out merge commits? Group by Jira ticket? Add emojis? You can.
• Cost. A few cents per generation vs. a monthly SaaS subscription.

I’ve been running this exact script for our team at ECOA AI for the last 6 months. It generates changelogs for our platform releases in under 10 seconds. Cost per run? About $0.03 in API calls.

What We’re Building

Here’s the architecture at a high level:

1. Git log extraction – Pull commits between two tags or from a date range.
2. Commit parsing – Filter, group, and clean the raw commit messages.
3. AI generation – Send the structured commit data to GPT-4o with a carefully engineered prompt.
4. Output formatting – Write the result to a `CHANGELOG.md` file or print to stdout.

We’ll keep it simple. No databases. No queues. Just a single Python script that does one thing well.

Prerequisites

• Python 3.10+
• An OpenAI API key (or any LLM provider – I’ll show you how to swap)
• Git installed and accessible from your terminal
• A project with a reasonable commit history (at least 10-20 commits)

Step 1: Extract and Parse Git Commits

First, let’s grab the commits between two Git tags. This is the most common use case: “generate changelog for v1.2.0 since v1.1.0.”

python
import subprocess
import re
from datetime import datetime
from typing import List, Dict

def get_commits_between_tags(start_tag: str, end_tag: str = "HEAD") -> List[Dict]:
    """
    Extract commits between two Git tags.
    Returns a list of dicts with commit hash, author, date, and message.
    """
    cmd = [
        "git", "log",
        f"{start_tag}..{end_tag}",
        "--pretty=format:%H||%an||%aI||%s",
        "--no-merges"  # Skip merge commits – they're noise
    ]
    
    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
    
    commits = []
    for line in result.stdout.strip().split("\n"):
        if not line:
            continue
        parts = line.split("||")
        if len(parts) < 4:
            continue
        
        commits.append({
            "hash": parts[0][:7],  # Short hash
            "author": parts[1],
            "date": parts[2],
            "message": parts[3]
        })
    
    return commits

A few things to note here:

• We use `--no-merges` to filter out merge commits. They're usually just "Merge branch 'main'" – useless for a changelog.
• The `--pretty=format` gives us structured output we can parse easily.
• We truncate the hash to 7 characters. That's the standard short hash.

But raw commit messages are still messy. Let's clean them up.

Step 2: Clean and Categorize Commits

Most teams follow Conventional Commits these days. If you don't, you should. It makes this step trivial.

Here's a parser that extracts the type, scope, and description from conventional commit messages:

python
def parse_conventional_commit(message: str) -> Dict:
    """
    Parse a conventional commit message into type, scope, and description.
    Example: 'feat(api): add user authentication endpoint'
    Returns: {'type': 'feat', 'scope': 'api', 'description': 'add user authentication endpoint'}
    """
    pattern = r'^(\w+)(\(([^)]+)\))?:\s*(.+)$'
    match = re.match(pattern, message)
    
    if match:
        return {
            "type": match.group(1),
            "scope": match.group(3) or "",
            "description": match.group(4)
        }
    
    # Fallback for non-conventional commits
    return {
        "type": "other",
        "scope": "",
        "description": message
    }


def categorize_commits(commits: List[Dict]) -> Dict[str, List[Dict]]:
    """
    Group commits by their conventional commit type.
    """
    categories = {
        "feat": [],
        "fix": [],
        "docs": [],
        "refactor": [],
        "perf": [],
        "test": [],
        "chore": [],
        "other": []
    }
    
    for commit in commits:
        parsed = parse_conventional_commit(commit["message"])
        commit["parsed"] = parsed
        
        if parsed["type"] in categories:
            categories[parsed["type"]].append(commit)
        else:
            categories["other"].append(commit)
    
    # Remove empty categories
    return {k: v for k, v in categories.items() if v}

This gives us a clean structure. Now we can feed it to the AI.

Step 3: Build the AI Prompt

This is where the magic happens. The quality of your changelog depends almost entirely on the quality of your prompt.

Here's the prompt I use. It's been iterated over about 20 releases:

python
def build_changelog_prompt(project_name: str, version: str, categories: Dict) -> str:
    """
    Build a prompt for the LLM to generate a changelog.
    """
    # Format the commit data as a readable list
    commit_text = ""
    for category, commits in categories.items():
        commit_text += f"\n## {category.upper()}\n"
        for c in commits:
            scope = f"({c['parsed']['scope']})" if c['parsed']['scope'] else ""
            commit_text += f"- {c['parsed']['description']} [{c['hash']}]\n"
    
    prompt = f"""You are a technical writer generating a changelog for {project_name} version {version}.

Given the following categorized commit messages, generate a clean, user-friendly changelog.

Rules:
1. Group changes into these sections: Features, Bug Fixes, Documentation, Performance Improvements, Refactoring, and Other.
2. Rewrite commit descriptions to be user-facing. Use active voice. Be specific.
3. Remove any internal jargon, ticket numbers, or developer-only references.
4. If a commit scope is present, mention it in the description (e.g., "Added user authentication to the API").
5. Keep each entry to one sentence. No bullet points within bullet points.
6. Do NOT include commit hashes in the final output.
7. If there are no changes in a category, omit that section entirely.
8. End with a "Full Changelog" link pointing to the compare URL.

Here are the commits:

{commit_text}

Generate the changelog now. Start with the version header and date."""
    
    return prompt

Notice what we're doing here:

• We're rewriting, not just formatting. The AI should turn "fix: handle null pointer in user profile serializer" into "Fixed a crash when loading user profiles with incomplete data."
• We're removing hashes. Users don't care about commit hashes.
• We're enforcing structure. The AI knows exactly which sections to use.

Step 4: Call the LLM

Now let's wire it up to OpenAI. I'm using GPT-4o-mini here because it's cheap ($0.15/1M input tokens) and fast. For most changelogs, you'll spend less than a cent.

python
from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

def generate_changelog(prompt: str) -> str:
    """
    Send the prompt to GPT-4o-mini and return the generated changelog.
    """
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {
                "role": "system",
                "content": "You are a technical writer. Generate clean, user-friendly changelogs."
            },
            {
                "role": "user",
                "content": prompt
            }
        ],
        temperature=0.3,  # Low temperature for consistent output
        max_tokens=2000
    )
    
    return response.choices[0].message.content

The `temperature=0.3` is important. You want the AI to be creative enough to rewrite descriptions well, but not so creative that it invents features that don't exist. Trust me, I've seen it happen.

Step 5: Put It All Together

Here's the main function that ties everything together:

python
def main():
    import argparse
    
    parser = argparse.ArgumentParser(description="Generate AI-powered changelog")
    parser.add_argument("--start-tag", required=True, help="Starting Git tag")
    parser.add_argument("--end-tag", default="HEAD", help="Ending Git tag (default: HEAD)")
    parser.add_argument("--project-name", default="My Project", help="Project name")
    parser.add_argument("--version", required=True, help="Version number for this release")
    parser.add_argument("--output", default="CHANGELOG.md", help="Output file path")
    
    args = parser.parse_args()
    
    print(f"Extracting commits from {args.start_tag} to {args.end_tag}...")
    commits = get_commits_between_tags(args.start_tag, args.end_tag)
    
    if not commits:
        print("No commits found in range.")
        return
    
    print(f"Found {len(commits)} commits. Categorizing...")
    categories = categorize_commits(commits)
    
    print("Building prompt...")
    prompt = build_changelog_prompt(args.project_name, args.version, categories)
    
    print("Generating changelog with AI...")
    changelog = generate_changelog(prompt)
    
    # Add the date header
    from datetime import date
    today = date.today().isoformat()
    full_changelog = f"## [{args.version}] - {today}\n\n{changelog}\n"
    
    # Write to file
    with open(args.output, "w") as f:
        f.write(full_changelog)
    
    print(f"Changelog written to {args.output}")

Run it like this:

bash
python generate_changelog.py --start-tag v1.1.0 --version 1.2.0 --project-name "ECOA AI Platform"

Step 6: Integrate with CI/CD

The real power comes when you automate this. Here's a GitHub Actions workflow that generates a changelog on every tag push:

yaml
name: Generate Changelog

on:
  push:
    tags:
      - 'v*'

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Fetch all history for tags
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: pip install openai
      
      - name: Get previous tag
        id: prev_tag
        run: echo "tag=$(git describe --tags --abbrev=0 HEAD^)" >> $GITHUB_OUTPUT
      
      - name: Generate changelog
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          python generate_changelog.py \
            --start-tag ${{ steps.prev_tag.outputs.tag }} \
            --version ${GITHUB_REF_NAME#v} \
            --project-name "ECOA AI Platform" \
            --output CHANGELOG.md
      
      - name: Upload changelog as artifact
        uses: actions/upload-artifact@v4
        with:
          name: changelog
          path: CHANGELOG.md

This runs automatically every time you push a tag like `v1.2.0`. It finds the previous tag, extracts the commits, and generates the changelog.

Real-World Results

We've been using this for our internal releases at ECOA AI. Here's what we've seen:

• Time saved: About 30 minutes per release, per developer. That's 6 hours a month for a team of 3.
• Quality: Our changelogs are now consistent. No more "various bug fixes" or "improved performance."
• User feedback: Support tickets related to "what changed in this release?" dropped by about 40%.

But here's the thing I didn't expect: it made our commit messages better. Once developers knew their messages would be fed to an AI and turned into user-facing text, they started writing more descriptive commits. No more "fix stuff." Now it's "fix: handle edge case in payment webhook when amount is zero."

A Note on Prompt Engineering

You'll need to iterate on the prompt. What works for your team might not work for mine. Here are a few things I've learned:

• Be specific about tone. If you want a formal changelog, say so. If you want a casual one, say that.
• Give examples. Show the AI what "good" looks like. I've included a few example entries in the system prompt.
• Watch for hallucinations. The AI might invent features. That's why we keep temperature low and always review the output before publishing.
• Handle edge cases. What if there are 100 commits? The prompt gets long. GPT-4o-mini handles up to 128K tokens, so you're fine for most projects.

Frequently Asked Questions

Q: Can I use a different LLM provider instead of OpenAI?

Absolutely. The code is provider-agnostic. Swap the `openai` client for Anthropic's Claude, Google's Gemini, or even a local model via Ollama. Just change the API call. The prompt structure stays the same.

Q: How do I handle non-conventional commit messages?

The script falls back to an "other" category for non-conventional commits. You can either train your team to use conventional commits (highly recommended) or modify the prompt to handle free-form messages. I've found that the AI is surprisingly good at inferring intent from messy messages.

Q: What if I want to include the full diff instead of just commit messages?

You can extend the `get_commits_between_tags` function to also run `git diff` and include the file paths. But be careful – this can make the prompt very large and expensive. I'd recommend only doing this for critical releases.

Q: How do I prevent the AI from leaking sensitive information?

First, make sure your commit messages don't contain secrets (they shouldn't). Second, you can add a pre-processing step that strips anything that looks like an API key, password, or internal URL. Third, if you're really paranoid, run a local LLM like Llama 3.1 70B. It's slower but keeps everything on your infrastructure.

Related reading: Why Top CTOs Hire Vietnamese Developers (2025 Offshore Strategy Guide)

Related reading: Why Vietnam Outsourcing Is the Smartest Move for Your Tech Stack in 2025