It's Wednesday afternoon, you're about to deploy a major release, and someone asks, "Where are the release notes?" Your heart sinks as you realize you'll be spending the next three hours combing through commit messages, trying to translate technical jargon into user-friendly language, and inevitably missing half the important changes.
At Ascend, we empower data teams to build fast, optimized, and automated data pipelines with AI-integrated workflows. We practice what we preach by applying the same automation principles to our own release notes. After searching for articles on a complete "full-stack" release notes pipeline and coming up empty-handed, I decided to build one myself—and I want to share how you can too.
In this post, you'll learn how to transform your release process from a manual, error-prone chore into a smooth, AI-powered automation that your team will actually love. We'll cover everything from architecture decisions to implementation gotchas, plus the real-world impact on our development workflow.

The Problem: Why Manual Release Notes Fail
Before diving into solutions, let's acknowledge why manual release notes are such a persistent pain point for development teams.
Time sink that derails productivity. Technical writers spend hours per release cycle syncing with developers and hand-writing release notes. This isn't just about the time—it's about context switching at the worst possible moment, right when you're trying to ship.
Procrastination leads to rushed or missing documentation. Release notes often become an afterthought, hastily written during deployment or skipped entirely when deadlines loom. The result? Users discover new features by accident, and support teams field confused questions about undocumented changes.
Multi-repository complexity multiplies the pain. When your product spans multiple repositories with independent release cycles, coordinating release notes becomes a logistical nightmare. Changes get missed, duplicated, or attributed to the wrong release.
Technical commits don't translate to user benefits. Raw commit messages like `fix null pointer exception in data validation
` don't help users understand that their data processing is now more reliable. The translation from technical change to user value requires domain knowledge and communication skills that not every developer possesses.
The result? Inconsistent, incomplete, or entirely missing release notes that frustrate users and waste everyone's time.
Requirements and Prerequisites
To build your own automated release notes pipeline using our framework, you'll need the following setup:
Essential Access and Permissions
- GitHub account with admin access to target repositories
- GitHub CLI authentication configured
- Repository permissions for creating branches, commits, and pull requests
Security and Authentication
- GitHub App with the following permissions on target repositories:
- Contents: Read and Write (for accessing commit history and updating files)
- Pull Requests: Read and Write (for creating automated PRs)
- Metadata: Read (for repository information)
- OpenAI API key with sufficient credits for text generation
- OpenAI API key and GitHub App private key stored as secrets in your target repository
Technical Environment
- Python environment
- Basic familiarity with GitHub Actions workflows
- Understanding of Git commit history and repository structure
Pro tip: Set up the GitHub App first—it provides more secure, granular permissions than personal access tokens and works better in automated environments. The setup takes 10 minutes but saves hours of authentication headaches later.
Architecture Overview: How It All Works Together
Our pipeline follows a simple but powerful workflow designed for flexibility and transparency:

Input Flexibility
The system accepts two types of input to accommodate different release strategies:
- Date-based approach: Specify a "since" date to capture all commits across repositories from that point forward
- Version-specific approach: Provide a JSON string mapping specific repository versions for more granular control
This dual approach means you can generate weekly summaries ("show me everything since last Friday") or targeted release notes ("show me changes in repo A since v2.1.0 and repo B since v1.5.2").
Core Processing Pipeline
1. Commit Harvesting: GitHub Actions trigger Python scripts that fetch repository commit histories from their `main
` branches based on your input specifications.
2. AI Summarization: Leverage the OpenAI API to process raw commit messages and transform them into user-friendly release notes with three key sections:
- Features: Major functionality additions that users will notice
- Improvements: Enhancements to existing features, performance optimizations
- Bug Fixes: Resolved issues and stability improvements
3. Content Integration: The system automatically:
- Extracts the "week of" date for consistent release note headers
- Prepends the AI-generated summary to the existing "What's new" documentation
4. Pull Request Creation: The pipeline creates a well-formatted PR in your documentation repository that includes:
- Updated "What's new" page with the new release notes
- Complete raw commit history in the PR description for team review
- Proper formatting and consistent styling
Why This Architecture Works
- Separation of concerns: Data collection, AI processing, and documentation updates are distinct steps, making debugging and maintenance easier
- Transparency: Raw commit data is preserved alongside the AI summary, so reviewers can verify accuracy
- Review process: PRs allow for human oversight before publication, catching edge cases and hallucinations and ensuring quality
- Flexibility: Supports both scheduled releases and ad-hoc updates without changing the core workflow
Strategy: Choosing the Right Approach for Your Team
Our multi-repository challenge shaped our solution, but your team's structure should drive your approach.
Why We Chose Commit-Based Analysis
At Ascend, we manage several product repositories, each on independent versioning schedules. Traditional release management tools didn't fit our distributed development model, so we opted to analyze commit history directly.
Benefits of our approach:
- Real-time accuracy: Captures all changes as they happen, not just tagged releases
- Cross-repository coordination: Aggregates changes from multiple repos into unified release notes
- Granular control: Can generate release notes for any time period or specific version ranges
- No additional tooling: Works with standard Git workflows without requiring release management overhead
Alternative Strategies to Consider
If your team uses unified release management:
- Look into tools like Release Please, Semantic Release, or Changesets with descriptive release information
- Consider AI-summarizing these structured releases instead of raw commits
This approach works well for monorepos or teams with standardized release processes
Hybrid approaches:
- Combine commit analysis with existing release tools for comprehensive coverage
- Use commit data to fill gaps between formal releases
- Supplement automated generation with manual curation for major releases
Choose based on your team's workflow, repository structure, and existing tooling. There's no one-size-fits-all solution, but the principles we'll cover adapt to most scenarios.
Source Code Deep Dive: The Python Engine
The heart of our pipeline is Python functionality. Here's how the key components work:
Commit Data Collection
Key implementation details:
- GitHub CLI integration: Uses the `gh` command-line tool for authenticated API access to both public and private repositories
- Flexible input handling: Accepts single repos, comma-separated lists, or JSON files containing repository lists
- Robust error handling: Validates GitHub CLI installation and repository access before attempting to fetch commits
- Configurable date filtering: Supports both date-based and ref-based commit filtering
AI-Powered Summarization
Our initial system prompt for consistent categorization:
Prompt engineering:
- Structured categorization: Our prompt enforces specific emoji-categorized sections for consistent output formatting
- User-focused translation: Explicitly instructs the AI to convert technical commits into user-friendly language
- Content filtering: Automatically excludes dependency updates, test changes, and internal technical modifications
- Low temperature setting: Uses 0.1 temperature for consistent, factual output rather than creative interpretation
Content Integration and File Management
File handling considerations:
- Consistent date formatting: Automatically calculates the Monday of the current week for consistent release note headers
- Encoding safety: Properly handles Unicode characters in commit messages from international contributors
- Atomic file operations: Uses temporary files during processing to prevent corruption if the process is interrupted
GitHub Actions: Orchestrating the Automation
Our workflow ties everything together with robust automation that handles the complexities of CI/CD environments.
Workflow Triggers and Inputs
Flexible triggering options:
- Manual dispatch with granular date control: Separate year, month, day inputs for precise date filtering
- Repository-specific filtering: JSON configuration allows different filtering strategies per repository
- Configurable timeouts: Adjustable API timeout settings for different network conditions
Secure Authentication Flow
Security best practices:
- GitHub App with specific repository access: Explicitly lists only the repositories that need access
- Scoped permissions: App configured with minimal necessary permissions for the specific repositories
- Secret management: Private key stored securely in GitHub Secrets
Repository Configuration Processing
Data Processing and File Management
Key implementation lessons:
- Temporary file strategy: We learned the hard way that GitHub Actions environments can lose data between steps. Writing to temporary files solved reliability issues where data would appear blank in subsequent steps.
- Complex JSON handling: Uses `jq` for safe JSON manipulation and temporary files to avoid shell quoting issues with complex JSON strings
- Output parsing: Logic to split AI-generated summaries from raw commit data using delimiter markers
- Robust error handling: `set -euo pipefail` ensures the script fails fast on any error, preventing silent failures
File Integration and Pull Request Creation
File management features:
- Atomic file operations: Uses temporary files and atomic moves to prevent file corruption
- Branch management: Creates date-based branches for organized PR tracking
- Content preservation: Carefully prepends new content while preserving existing documentation structure
Lessons Learned and Best Practices
Building this pipeline taught us valuable lessons about documentation automation that go beyond the technical implementation.
Technical Insights
File persistence matters in CI/CD environments. GitHub Actions environments can be unpredictable—always write important data to files rather than relying on environment variables or memory. We learned this the hard way when release notes would mysteriously appear blank in PRs.
API reliability requires defensive programming. Build retry logic and fallbacks for external API calls (OpenAI, GitHub). Network issues and rate limits are inevitable, especially as your usage scales.
Prompt engineering is crucial for consistent output. Spend time crafting prompts that consistently produce the format and tone you want. Small changes in wording can dramatically affect AI output quality and consistency.
Human review is essential, even with AI generation. Having team members review PRs catches edge cases, ensures quality, and builds confidence in the automated system. The goal isn't to eliminate human oversight—it's to make it more efficient and focused.
Historical tracking and product evolution insights. Automated generation creates a consistent record of product evolution that's valuable for retrospectives, planning, and onboarding new team members.
Results and Impact
The automation has fundamentally transformed our release process and team dynamics:
Quantifiable Improvements
Dramatic time savings: Reduced release note creation from 2-3 hours of writing time to 15 minutes of review time. That's a 90% reduction in effort while improving quality and consistency.
Perfect consistency: Every release now has properly formatted, comprehensive notes. No more missed releases or inconsistent formatting across different team members.
Increased frequency: We can now generate release notes weekly, providing users with more timely updates about product improvements.
Complete coverage: Captures changes across all repositories without manual coordination, eliminating the risk of missing important updates.
Next Steps and Future Enhancements
We're continuously improving the pipeline based on team feedback and evolving needs:
Immediate Roadmap
Slack integration: Building a Slackbot to automatically share release notes with our community channels, extending the reach beyond just documentation updates.
Repository tracing: Categorize the raw commits by repository and add links so it's easy to (literally) double-click into each PR for additional context.
Future Possibilities
Multi-language support: Generating release notes in different languages for global audiences as we expand internationally.
Ready to automate your own release notes? Start with the requirements above and build incrementally. Begin with a single repository, get the basic workflow running, then expand to multiple repos and add advanced features. Your future self (and your team) will thank you for eliminating this manual drudgery and creating a more consistent, professional release process.
The investment in automation pays dividends immediately—not just in time saved, but in the improved quality and consistency of your user communication. In a time where software moves fast, automated release notes ensure your documentation keeps pace.