## Introduction
Generating changelogs manually after every software release can be tedious and error-prone, especially in fast-moving startup environments. Operations teams and automation engineers benefit greatly from automating this process, ensuring that the changelog is always up-to-date, accurate, and available without manual intervention. In this technical tutorial, we will build an end-to-end automation workflow using n8n — an open-source workflow automation tool — to auto-generate changelogs from GitHub repositories whenever new releases or pull requests are merged. This workflow can be triggered automatically and outputs a formatted changelog, which can be published to Slack, emailed to stakeholders, or stored in Google Sheets for record-keeping.
—
## What Problem Does This Solve?
– **Manual effort**: Removes the need for developers or ops teams to collect commit messages or pull request titles for changelog updates.
– **Consistency**: Produces standardized changelogs following semantic versioning and conventional commit messages.
– **Real-time updates**: Generates changelogs immediately on GitHub releases or merges.
– **Transparency**: Shares changelog information automatically with the right teams (QA, product, marketing).
—
## Tools and Services Integrated
– **GitHub**: Source of commit history, releases, pull requests.
– **n8n**: Workflow automation platform to orchestrate data retrieval, transformation, and distribution.
– **Slack** (optional): Notification channel to share the changelog.
– **Google Sheets** (optional): Track changelog history or version notes.
– **Email** (optional): Send formatted changelog to a mailing list.
—
## Prerequisites
– Access to an n8n instance (cloud or self-hosted).
– GitHub personal access token with repo read permissions.
– Slack workspace setup with incoming webhook (if using Slack integration).
– Google Sheets API credentials (if using Google Sheets).
—
## High-Level Workflow
1. **Trigger**: GitHub webhook triggers on either a new release or pull request merge event.
2. **Fetch commits or pull request details** relevant to the release.
3. **Parse commit messages or PR titles** to extract meaningful changelog entries.
4. **Format the changelog** in markdown or text.
5. **Output or distribute** the changelog via Slack, email, or storage.
—
## Step-by-Step Technical Tutorial
### Step 1: Configure GitHub Webhook Trigger in n8n
– In your GitHub repo, navigate to Settings > Webhooks > Add webhook.
– Set the payload URL to your n8n webhook URL (e.g., `https://your-n8n-instance.com/webhook/github-changelog`).
– Select content type ‘application/json’.
– Choose events to trigger on: **Release** and **Pull Request.**
– Save the webhook.
– In n8n, add a **Webhook** node:
– Set the path to match GitHub webhook path.
– Method: POST
– Verify payload via signature secret (optional for security).
### Step 2: Parse Incoming Webhook Data
– Add a **Set** or **Function** node to extract event type from the `X-GitHub-Event` header.
– Use this to conditionalize workflow execution if desired.
### Step 3: Fetch Release or Pull Request Details
– Add a **GitHub** node:
– Operation: Get Release (when triggered by release event)
– Input the release tag name from webhook payload to fetch release details.
– For PR merge events:
– Use GitHub node to get Pull Request details by PR number.
### Step 4: Retrieve Commits Included in Release
– Use GitHub node to list commits between last release and current release tag.
– If PR triggered, get commits associated with the merged PR.
### Step 5: Extract and Filter Commit Messages
– Add a **Function** node to parse commit messages:
– Read commit message titles and descriptions.
– Filter out merge commits and uninformative messages.
– Optionally apply Conventional Commit format parsing to categorize entries (feat, fix, docs, etc).
Example snippet for categorization:
“`js
const commits = items.map(item => item.json);
const changelogEntries = commits.map(c => {
const msg = c.commit.message;
// Extract type from Conventional Commits: ‘feat’, ‘fix’, etc.
const match = msg.match(/^(feat|fix|docs|chore|refactor|test|perf)(\(.+\))?: (.+)/i);
if (match) {
return `- ${match[1]}: ${match[3]}`;
} else {
return `- ${msg.split(‘\n’)[0]}`; // fallback
}
});
return [{ json: { changelog: changelogEntries.join(‘\n’) } }];
“`
### Step 6: Format the Changelog
– Use the output from the function node and prepend release metadata:
– Release version (tag)
– Release date
– Link to GitHub release page
– Example formatted changelog:
“`
# Release v1.2.3 – 2024-06-15
## Changelog
– feat: add user authentication flow
– fix: patch security vulnerability in password reset
– docs: update API usage examples
“`
### Step 7: Output the Changelog
– Option 1: **Slack Notification**
– Add **Slack** node
– Post the changelog markdown to a designated channel
– Option 2: **Email**
– Use n8n SMTP node to email changelog to stakeholders
– Option 3: **Google Sheets**
– Append a new row with release version, date, and changelog text
### Step 8: Error Handling and Robustness
– Validate GitHub tokens and reauthenticate if failures occur.
– Handle rate limits by adding delays or retries.
– Use conditional logic in n8n to handle edge cases, such as missing commits.
– Add detailed logging via **Set** nodes or external monitoring.
### Step 9: Scaling the Workflow
– Modularize workflow by creating subworkflows for commit parsing and output distribution.
– Use environment variables or credentials to support multiple repositories.
– Schedule periodic runs to generate changelogs if webhook misses occur.
—
## Common Errors and Troubleshooting
– **Webhook not triggering**: Check GitHub webhook delivery status and n8n endpoint accessibility.
– **Permission errors**: Ensure GitHub tokens have proper scopes (repo access).
– **Empty changelogs**: Verify commit retrieval queries and filters.
– **Slack message formatting issues**: Confirm Slack supports markdown being sent.
—
## Summary and Bonus Tip
In this guide, we’ve built a comprehensive automation workflow to auto-generate changelogs from GitHub using n8n. This empowers operations teams to maintain consistent, real-time release notes without manual effort. As a bonus tip, consider integrating this workflow with your CI/CD pipeline or deployment tools to publish changelogs automatically on your product website or documentation portals, closing the loop between development and customer communications.
Automated changelogs not only save time but provide accuracy and transparency that help align teams around what exactly has changed with each release.
—
For further customization, explore adding support for multiple repositories, including issue tracking references, or summarizing contributions by author.