Overview This page provides practical examples of using HelixCommit in various scenarios. Each example includes complete commands and explanations to help you adapt them to your needs.
Basic examples Generate release notes for unreleased changes The most common use case: see what’s changed since your last release.
helixcommit generate \ --unreleased \ --format markdown \ --out RELEASE_NOTES.md
Works offline with --no-prs flag for faster generation.
Generate release notes for a specific version range:
helixcommit generate \ --since-tag v1.2.0 \ --until-tag v1.2.1 \ --format markdown \ --out release-1.2.1.md
Generate notes for custom commit range Use commit SHAs or any Git refs:
helixcommit generate \ --since abc123def \ --until feature-branch \ --format markdown
Create release notes in Markdown, HTML, and plain text simultaneously:
#!/bin/bash echo "Generating release notes in all formats..." # Markdown for GitHub helixcommit generate \ --unreleased \ --format markdown \ --out RELEASE_NOTES.md # HTML for website helixcommit generate \ --unreleased \ --format html \ --out docs/changelog.html # Text for email helixcommit generate \ --unreleased \ --format text \ --out CHANGES.txt echo "✓ Release notes generated in all formats"
GitHub Releases
Slack/Discord
Email
Website
# Optimized for GitHub releases helixcommit generate \ --since-tag v1.0.0 \ --until-tag v2.0.0 \ --format markdown \ --include-scopes \ --out RELEASE_NOTES.md # Use in GitHub CLI gh release create v2.0.0 \ --title "Version 2.0.0" \ --notes-file RELEASE_NOTES.md
# Plain text for chat platforms helixcommit generate \ --unreleased \ --format text \ --no-prs \ --max-items 20 > release.txt # Post to Slack curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL \ -H 'Content-Type: application/json' \ -d "{ \" text \" : \" $( cat release.txt) \" }"
# HTML for rich email helixcommit generate \ --unreleased \ --format html \ --out email_body.html # Send via email (example with mailx) cat email_body.html | mail -s "Release Notes v2.0" \ -a "Content-Type: text/html" team@example.com
# HTML for embedding in website helixcommit generate \ --since-tag v1.0.0 \ --format html \ --no-merge-commits \ --out public/changelog.html # Deploy with your site npm run build npm run deploy
AI-powered examples Basic AI summarization Generate AI-enhanced release notes with OpenAI:
export OPENAI_API_KEY = sk- ... helixcommit generate \ --unreleased \ --use-llm \ --openai-model gpt-4o-mini \ --format markdown \ --out AI_RELEASE_NOTES.md
Free AI with OpenRouter Use free AI models via OpenRouter:
export OPENROUTER_API_KEY = sk-or- ... helixcommit generate \ --unreleased \ --use-llm \ --llm-provider openrouter \ --openrouter-model x-ai/grok-4.1-fast:free \ --format markdown
OpenRouter’s free tier is perfect for testing AI features without cost.
Advanced AI with custom prompts Customize AI behavior for your domain:
export OPENAI_API_KEY = sk- ... helixcommit generate \ --unreleased \ --use-llm \ --openai-model gpt-4o-mini \ --domain-scope "healthcare technology" \ --expert-role "Product Manager" \ --expert-role "Clinical Engineer" \ --expert-role "Compliance Officer" \ --rag-backend simple \ --format markdown \ --out RELEASE_NOTES.md
GitHub integration examples With full GitHub enrichment Include pull request information and links:
export GITHUB_TOKEN = ghp_ ... helixcommit generate \ --unreleased \ --format markdown \ --include-scopes \ --out RELEASE_NOTES.md
GitHub integration automatically adds PR links, author information, and compare URLs.
Offline mode without GitHub Generate notes without any external API calls:
helixcommit generate \ --unreleased \ --no-prs \ --format markdown \ --out RELEASE_NOTES.md
With caching for repeated runs Enable caching to speed up subsequent runs:
export GITHUB_TOKEN = ghp_ ... export HELIXCOMMIT_GH_CACHE = 1 helixcommit generate \ --unreleased \ --format markdown
Filtering examples Exclude merge commits Create cleaner release notes by excluding merge commits:
helixcommit generate \ --unreleased \ --no-merge-commits \ --format markdown
Limit commit count Process only recent commits for faster generation:
helixcommit generate \ --unreleased \ --max-items 50 \ --format markdown
Hide commit scopes Generate notes without showing commit scopes:
helixcommit generate \ --unreleased \ --no-include-scopes \ --format markdown
Output with scopes: - **api**: Add authentication endpoint
Output without scopes: - Add authentication endpoint
Programmatic usage Python API basic example Use HelixCommit as a Python library:
from datetime import datetime from pathlib import Path from helixcommit.changelog import ChangelogBuilder from helixcommit.formatters.markdown import render_markdown from helixcommit.git_client import CommitRange, GitRepository # Initialize repository repo = GitRepository(Path( "." )) # Define commit range commit_range = CommitRange( since = "v1.0.0" , until = "v2.0.0" , include_merges = False ) # Get commits commits = list (repo.iter_commits(commit_range)) # Build changelog builder = ChangelogBuilder( include_scopes = True ) changelog = builder.build( version = "v2.0.0" , release_date = datetime.now(), commits = commits, commit_prs = {}, pr_index = {} ) # Render to markdown markdown = render_markdown(changelog) print (markdown) # Save to file Path( "RELEASE_NOTES.md" ).write_text(markdown)
With AI summarization Add AI-powered summaries programmatically:
from helixcommit.summarizer import PromptEngineeredSummarizer from pathlib import Path # Configure AI summarizer summarizer = PromptEngineeredSummarizer( api_key = "sk-..." , model = "gpt-4o-mini" , cache_path = Path( ".cache/summaries.json" ), domain_scope = "software release notes" , expert_roles = [ "Product Manager" , "Tech Lead" ], rag_backend = "simple" ) # Use with ChangelogBuilder builder = ChangelogBuilder( summarizer = summarizer, include_scopes = True ) # Build changelog with AI changelog = builder.build( version = "v2.0.0" , release_date = datetime.now(), commits = commits, commit_prs = {}, pr_index = {} )
Create a custom output format:
from helixcommit.models import Changelog def custom_formatter ( changelog : Changelog) -> str : """Custom release notes formatter.""" lines = [ f "# Release { changelog.version } " ] lines.append( f "Date: { changelog.date.strftime( '%Y-%m- %d ' ) if changelog.date else '' } " ) lines.append( "" ) for section in changelog.sections: lines.append( f "## { section.title } " ) for item in section.items: lines.append( f "- { item.title } " ) lines.append( "" ) return " \n " .join(lines) # Use custom formatter output = custom_formatter(changelog) print (output)
CI/CD integration examples GitHub Actions Automated release notes on tag creation:
name : Generate Release Notes on : push : tags : - 'v*' jobs : release-notes : runs-on : ubuntu-latest steps : - uses : actions/checkout@v3 with : fetch-depth : 0 # Full history for tags - name : Set up Python uses : actions/setup-python@v4 with : python-version : '3.11' - name : Install HelixCommit run : pip install helixcommit - name : Generate release notes env : GITHUB_TOKEN : ${{ secrets.GITHUB_TOKEN }} run : | helixcommit generate \ --since-tag $(git describe --tags --abbrev=0 HEAD^) \ --until-tag ${{ github.ref_name }} \ --format markdown \ --out RELEASE_NOTES.md - name : Create GitHub Release uses : softprops/action-gh-release@v1 with : body_path : RELEASE_NOTES.md
GitLab CI generate_release_notes : stage : release image : python:3.11 only : - tags script : - pip install helixcommit - | helixcommit generate \ --since-tag $CI_COMMIT_BEFORE_SHA \ --until-tag $CI_COMMIT_TAG \ --format markdown \ --out RELEASE_NOTES.md artifacts : paths : - RELEASE_NOTES.md
Jenkins pipeline { agent any stages { stage( 'Generate Release Notes' ) { steps { sh ''' pip install helixcommit helixcommit generate \ --unreleased \ --format markdown \ --out RELEASE_NOTES.md ''' } } stage( 'Publish' ) { steps { archiveArtifacts artifacts : 'RELEASE_NOTES.md' } } } }
Shell script examples Complete release script Automated script for creating releases:
#!/bin/bash set -e # Configuration NEW_VERSION = $1 PREVIOUS_TAG = $( git describe --tags --abbrev=0 ) if [ -z " $NEW_VERSION " ]; then echo "Usage: $0 <version>" exit 1 fi echo "Creating release $NEW_VERSION from $PREVIOUS_TAG " # Generate release notes echo "Generating release notes..." helixcommit generate \ --since-tag " $PREVIOUS_TAG " \ --until HEAD \ --format markdown \ --out "releases/ $NEW_VERSION .md" echo "✓ Release notes: releases/ $NEW_VERSION .md" # Create git tag git tag -a " $NEW_VERSION " -m "Release $NEW_VERSION " echo "✓ Created tag $NEW_VERSION " echo "" echo "Next steps:" echo " 1. Review: cat releases/ $NEW_VERSION .md" echo " 2. Push: git push origin $NEW_VERSION "
Weekly changelog script Generate weekly update summaries:
#!/bin/bash # Get changes from last week SINCE_DATE = "7 days ago" OUTPUT_FILE = "weekly-update-$( date +%Y-%m-%d).md" echo "Generating weekly update..." helixcommit generate \ --since " $SINCE_DATE " \ --format markdown \ --no-merge-commits \ --out " $OUTPUT_FILE " echo "✓ Weekly update: $OUTPUT_FILE " # Send to team (example) # cat "$OUTPUT_FILE" | mail -s "Weekly Update" team@example.com
Troubleshooting examples Debug mode Enable verbose output for troubleshooting:
# Add debug information helixcommit --help generate # Check git repository status git status git log --oneline -10 git tag -l # Verify GitHub token echo $GITHUB_TOKEN | cut -c1-10 # Test with minimal options helixcommit generate --format text --max-items 5
Handling edge cases # Empty commits (fail early in CI) helixcommit generate --unreleased --fail-on-empty || echo "No changes" # Very large repositories (limit processing) helixcommit generate --max-items 100 --no-merge-commits # Repositories without tags helixcommit generate --since "30 days ago" --format markdown
Next steps
CI/CD integration Deep dive into CI/CD automation
Python API Complete programmatic API reference
Configuration Advanced configuration options
CLI reference Full command-line reference