From Manual Chores to 90% Time Savings: Automating Release Notes with GitHub Actions and AI

Introduction: Automate Release Notes Efficiently

Imagine this: It's deployment day, and suddenly, you're asked to provide release notes. Panic sets in as you realize a manual approach will consume hours sifting through commit histories and crafting summaries. This is where the power to automate release notes comes into play, saving significant time. Using GitHub Actions combined with AI, you can reduce release note creation time by up to 90%. This method allows you to automate GitHub release notes effortlessly, transforming what was once a labor-intensive task into a quick review session.

This guide shows you how to integrate AI for automating release notes; harvesting commits, generating summaries, and creating pull requests becomes a streamlined process. Say goodbye to missed updates and jargon-filled notes, and hello to consistent, high-quality documentation that truly engages your users.

Benefits of Automating Release Notes

Learn how automating release notes can save time, reduce errors, and ensure consistent documentation:

• Time Savings: Focus on developing code rather than manual documentation.
• Error Reduction: Minimize human error through systematic AI processing.
• Consistency: Standard format improves clarity for end-users.

Why Manual Release Notes Fail—and Why Automation Wins

Manual release notes can become a systemic bottleneck due to their tedious nature. Developers often encode messages for machines, not humans, leading to inconsistencies and errors.

Common challenges include:

• Time sinks: 2-3 hours per release, derailing sprints.
• Inconsistency: Rushed notes skip features or use varying formats.
• Missing coverage: Multi-repo teams overlook changes across projects.
• Procrastination: Documentation becomes an afterthought, leading to user confusion.

Automating release notes flips this script. AI efficiently parses commit messages into user-friendly categories while GitHub Actions does the labor-intensive tasks, leading to timely, accurate documentation.

Requirements and Prerequisites: Get Set Up in Minutes

Set up your environment to automate release notes with minimal tools:

Access and Permissions

• GitHub account with necessary repository permissions.
• GitHub CLI installed and authenticated.
• Administrative access for reading contents and managing pull requests.

Security and Authentication

• GitHub App configured with proper permissions.
• Secure OpenAI API key for generating summaries.
• Store keys as GitHub repository secrets for security.

Technical Environment

• Python 3.x environment set up.
• Basic understanding of GitHub Actions and commit histories.

Pro tip: Opt for GitHub Apps over personal tokens for more secure and granular access.

How to Automate Release Notes: A Flexible Workflow

This workflow is designed for modularity and transparency, allowing you to automate release notes effectively:

• Date-based: Use date-based inputs for weekly summaries.
• Version-specific: Script adapts based on required version inputs.

Core Steps

1. Commit Harvesting: Fetch commit histories using GitHub's API.
2. AI Summarization: Use OpenAI to transform commits into actionable release notes.
3. Content Integration: Integrate results into your existing documentation.
4. PR Creation: Auto-generate pull requests for seamless reviews.

These steps ensure separation of concerns, transparency, and oversight, enhancing debugging and verification.

Choosing the Right Strategy for Your Team

Adapt the strategy to your team's setup for optimal results:

For distributed repos, commit-based analysis allows real-time, cross-repo aggregation.

Strategy	Best For	Tools
Commit-Based (This Guide)	Multi-repo, flexible periods	GitHub CLI + OpenAI
Release-Tagged	Monorepos, semantic versioning	Release Please, Semantic Release
Hybrid	Gaps in formal releases	Commits + manual curation

Start simple; iterate as needed according to your Git workflow.

Implementation: GitHub Actions Workflow

To automate release notes, create the file .github/workflows/release-notes.yml in your repository:

name: Generate Release Notes

on:
  workflow_dispatch:
    inputs:
      since_date:
        description: 'Generate notes since (YYYY-MM-DD)'
        required: false
      repos_json:
        description: 'JSON: {"repo1": "v1.0", "repo2": "v2.0"}'
        required: false

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: pip install openai github-cli
      - name: Run release notes script
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: python generate_release_notes.py "${{ github.event.inputs.since_date || '' }}" "${{ github.event.inputs.repos_json || '' }}"

Trigger this workflow manually or schedule it via cron for regular runs.

Source Code Deep Dive: The Python Engine

The Python script is central to automating release notes. Save it as generate_release_notes.py.

1. Fetch Commit History

This function fetches commits using GitHub CLI:

def fetch_commit_history(
    repos: Union[str, List[str], pathlib.Path],
    timeout_seconds: int = 120,
    since_date: Optional[str] = None,
    from_ref: Optional[str] = None,
    to_ref: Optional[str] = None,
) -> Dict[str, List[Dict[str, Any]]]:
    """
    Fetches commit history from one or multiple GitHub repositories using the GitHub CLI.
    Works with both public and private repositories, provided the authenticated user has access.
    """
    # Check if GitHub CLI is installed
    subprocess.run(
        ["gh", "--version"],
        capture_output=True,
        check=True,
        timeout=timeout_seconds,
    )
    # Process the repos input
    if isinstance(repos, pathlib.Path) or (isinstance(repos, str) and os.path.exists(repos) and repos.endswith(".json")):
        with open(repos, "r") as f:
            repos = json.load(f)
    elif isinstance(repos, str):
        repos = [repo.strip() for repo in repos.split(",")]
    results = {}
    for repo in repos:
        # Get repository info
        default_branch_cmd = subprocess.run(
            ["gh", "api", f"/repos/{repo}"],
            capture_output=True,
            text=True,
            check=True,
            timeout=timeout_seconds,
        )
        repo_info = json.loads(default_branch_cmd.stdout)
        default_branch = repo_info.get("default_branch", "main")
        # Build API query
        api_path = f"/repos/{repo}/commits"
        query_params = ["per_page=100"]
        if since_date:
            query_params.append(f"since={since_date}T00:00:00Z")
        target_ref = to_ref or default_branch
        query_params.append(f"sha={target_ref}")
        api_url = f"{api_path}?{'&'.join(query_params)}"
        # Fetch commits
        result = subprocess.run(
            ["gh", "api", api_url],
            capture_output=True,
            text=True,
            check=True,
            timeout=timeout_seconds,
        )
        commits = json.loads(result.stdout)
        results[repo] = commits
    return results

2. AI Summarization with OpenAI

Generate human-readable summaries using OpenAI:

import openai

def summarize_commits(commits_by_repo: Dict[str, List[Dict]], api_key: str) -> str:
    openai.api_key = api_key
    all_messages = []
    for repo, commits in commits_by_repo.items():
        messages_text = "\n".join([c['commit']['message'] for c in commits])
        all_messages.append(f"Repo {repo}:\n{messages_text}")
    
    prompt = f"""
    Summarize these commit messages into release notes with sections: 
    - Features: New user-facing functionality
    - Improvements: Enhancements, perf, reliability
    - Bug Fixes: Resolved issues
    
    Commits:\n{'\n\n'.join(all_messages)}
    
    Make it user-friendly, concise, and exciting.
    """
    
    response = openai.ChatCompletion.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices.message.content

Customize the prompt: Tailor it to your product’s voice, adding sections like "Breaking Changes" if necessary.

3. Integrate and Create PR

Update your "What's New" documentation with the AI-generated summary and create a pull request:

# Pseudo-code snippet
whats_new_path = "docs/whats-new.md"
with open(whats_new_path, 'r') as f:
    content = f.read()

summary = summarize_commits(commits, os.getenv('OPENAI_API_KEY'))
header = f"## Week of {datetime.now().strftime('%Y-%m-%d')}\n\n{summary}\n\n"
new_content = header + content

with open(whats_new_path, 'w') as f:
    f.write(new_content)

# Commit and PR via gh CLI
subprocess.run(["git", "add", whats_new_path])
subprocess.run(["git", "commit", "-m", "Add AI-generated release notes"])
subprocess.run(["gh", "pr", "create", "--title", "Automated Release Notes", "--body", "Raw commits: [link]"])

Handling Edge Cases and Potential Pitfalls

• Large Histories: Paginate API calls to manage extensive data.
• AI Hallucinations: Always include raw commits in the PR body for verification.
• Multi-Repo Auth: Ensure proper authentication for cross-repo access.
• Rate Limits: Monitor usage and cache responses if needed.
• Private Repos: Utilize CLI with appropriate authentication settings.

Results: Expect 90% Time Savings and More

By automating release notes, development teams can achieve:

• 90% effort reduction: Transform hours of effort into a matter of minutes.
• Weekly cadence: Keep users engaged with regular updates.
• Full coverage: Ensure no significant change is overlooked.
• Consistency: Deliver a standardized format consistently.

For example, a data platform team successfully implemented this approach and turned their release documentation into a true asset.

Best Practices and Extensions

• Review Gates: Implement PR approval requirements to ensure quality.
• SemVer Integration: Use semantic versioning for structured workflows.
• Changelog Tools: Enhance releases with tools like semantic-release.
• Multi-Language: Use AI to generate localized notes as needed.
• Notifications: Enable notifications in Slack or Discord when PRs are created.

Scale this concept to full release automation by including artifact builds and publishes, enhancing your workflow.

FAQ

Get Started Today

Copy the code, configure your GitHub secrets, and launch your first automated run. Customize the process as necessary to fit your team's workflow, and start benefiting from a more efficient and effective release note generation process.