GitHub integration

Enrich release notes with GitHub pull request data and links

Overview

HelixCommit integrates with GitHub’s API to enrich your release notes with pull request information, author details, and comparison links. This integration is optional but highly recommended for repositories hosted on GitHub.

GitHub integration works with both public and private repositories. For private repos, you’ll need to provide a GitHub token with appropriate permissions.

Benefits of GitHub integration

Pull request links

Automatically link commits to their associated pull requests for better traceability

Author attribution

Show who contributed each change, recognizing team members and external contributors

Compare URLs

Generate comparison links between versions to see all changes in GitHub’s UI

Rich metadata

Include PR descriptions, labels, and review information in your release notes

Quick start

Enable GitHub integration

Simply set your GitHub token and HelixCommit will automatically fetch PR data:

export GITHUB_TOKEN=ghp_your_token_here

helixcommit generate --unreleased --format markdown

That’s it! HelixCommit automatically detects GitHub repositories and enriches the output.

Disable GitHub integration

Work offline or skip PR lookups:

helixcommit generate --unreleased --no-prs --format markdown

Authentication

Creating a GitHub token

1. Navigate to GitHub settings

   Go to github.com/settings/tokens and click Generate new token.

   Choose between:

   • Classic token - Traditional personal access tokens
   • Fine-grained token - More granular permissions (recommended)
2. Select permissions

   Public repositories

   No special permissions needed

   Unauthenticated requests work but have lower rate limits (60 requests/hour).

   With a token (even without special scopes):

   • Rate limit: 5,000 requests/hour
   • Better reliability

   Private repositories

   Classic token: Select repo scope

   Fine-grained token: Select:

   • Repository access: Choose your repositories
   • Permissions:
     • Contents: Read-only
     • Pull requests: Read-only
     • Metadata: Read-only
3. Set the token

   Environment variable (recommended)

   export GITHUB_TOKEN=ghp_your_token_here
   
   # Add to your shell profile for persistence
   echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.bashrc
   

   Never commit tokens to version control. Use environment variables or secret management tools.

What gets enriched

Pull request resolution

HelixCommit automatically finds PRs associated with commits:

Before GitHub integration

### Features
- Add user authentication (abc123)
- Implement dark mode (def456)

After GitHub integration

### Features
- Add user authentication (#42) - @johndoe
  Implements OAuth2 authentication with JWT tokens
- Implement dark mode (#45) - @janedoe
  Adds system-wide theme support with user preferences

Compare URLs

Automatic comparison links between versions:

## Release v2.0.0
_Released on 2025-11-13_

### Features
- ...

[View full changelog](https://github.com/owner/repo/compare/v1.0.0...v2.0.0)

Commit-to-PR mapping

HelixCommit uses multiple strategies to find related PRs:

1. PR number in commit message: feat: Add feature (#123)
2. Merge commit pattern: Merge pull request #123
3. GitHub API lookup: Search by commit SHA

Using Conventional Commits with PR numbers in messages improves accuracy and reduces API calls.

Rate limiting

Understanding GitHub rate limits

Authentication	Rate limit	Resets
Unauthenticated	60 requests/hour	Every hour
Authenticated	5,000 requests/hour	Every hour
GitHub Actions	Higher limits	Variable

How HelixCommit handles rate limits

HelixCommit automatically manages rate limits:

1. Respects rate limit headers

   Reads X-RateLimit-Remaining and stops before hitting the limit.

2. Exponential backoff

   Retries failed requests with increasing delays.

   # Configure retry behavior
   export HELIXCOMMIT_GH_MAX_RETRIES=5
   export HELIXCOMMIT_GH_BACKOFF_BASE_SEC=1.0
   export HELIXCOMMIT_GH_BACKOFF_CAP_SEC=16
   
3. Smart caching

   Caches API responses to reduce duplicate requests.

   # Enable persistent caching
   export HELIXCOMMIT_GH_CACHE=1
   export HELIXCOMMIT_GH_CACHE_TTL_MINUTES=30
   

Monitoring rate limit usage

Check your current rate limit status:

# Using curl
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit

# Or using GitHub CLI
gh api rate_limit

Enable caching in CI/CD environments to maximize efficiency and avoid rate limit issues.

Caching

Enable GitHub API caching

Reduce API calls and improve performance:

# Enable caching
export HELIXCOMMIT_GH_CACHE=1

# Customize cache location
export HELIXCOMMIT_GH_CACHE_DIR=.cache/github

# Set cache lifetime (default: 10 minutes)
export HELIXCOMMIT_GH_CACHE_TTL_MINUTES=30

# Generate with caching
helixcommit generate --unreleased

Cache structure

Cached data is stored as JSON files:

.helixcommit-cache/
└── github/
    ├── pr_123.json      # Pull request #123
    ├── pr_124.json      # Pull request #124
    └── commit_abc123.json  # Commit lookups

Cache management

Clear cache

# Remove all cached data
rm -rf .helixcommit-cache/github/

# Regenerate with fresh data
helixcommit generate --unreleased

View cache size

du -sh .helixcommit-cache/github/

Inspect cached PR

cat .helixcommit-cache/github/pr_123.json | python -m json.tool

Configuration options

Environment variables

GITHUB_TOKEN · string · required

GitHub personal access token for API authentication.

export GITHUB_TOKEN=ghp_...

HELIXCOMMIT_GH_MAX_RETRIES · integer · default: "3"

Maximum number of retry attempts for failed API requests.

export HELIXCOMMIT_GH_MAX_RETRIES=5

HELIXCOMMIT_GH_BACKOFF_BASE_SEC · float · default: "0.5"

Initial delay in seconds for exponential backoff.

export HELIXCOMMIT_GH_BACKOFF_BASE_SEC=1.0

HELIXCOMMIT_GH_BACKOFF_CAP_SEC · float · default: "8"

Maximum delay in seconds between retries.

export HELIXCOMMIT_GH_BACKOFF_CAP_SEC=16

HELIXCOMMIT_GH_CACHE · boolean · default: "false"

Enable persistent caching of GitHub API responses.

export HELIXCOMMIT_GH_CACHE=1

Valid values: 1, true, yes, on

HELIXCOMMIT_GH_CACHE_DIR · path · default: ".helixcommit-cache/github"

Directory for storing cached GitHub API responses.

export HELIXCOMMIT_GH_CACHE_DIR=.cache/gh-api

HELIXCOMMIT_GH_CACHE_TTL_MINUTES · integer · default: "10"

Cache time-to-live in minutes.

export HELIXCOMMIT_GH_CACHE_TTL_MINUTES=30

CLI flags

--github-token · string

Provide GitHub token via command line.

helixcommit generate --github-token ghp_...

Prefer environment variables over command-line flags to avoid exposing tokens in shell history.

--no-prs · boolean

Disable GitHub PR lookups entirely.

helixcommit generate --no-prs

Useful for:

• Offline work
• Non-GitHub repositories
• Faster generation when PR data isn’t needed

Troubleshooting

API rate limit exceeded

If you hit rate limits:

1. Use authentication:

   export GITHUB_TOKEN=ghp_...
   

2. Enable caching:

   export HELIXCOMMIT_GH_CACHE=1

3. Reduce API calls:

   # Use --no-prs for testing
   gitreleasegen generate --no-prs
   

4. Wait for reset:

   # Check when limit resets
   gh api rate_limit | jq '.rate.reset'
   

Permission denied errors

Verify your token has correct permissions:

1. Go to github.com/settings/tokens
2. Check token has repo scope (for private repos)
3. Verify token isn’t expired
4. Test token:
   curl -H "Authorization: token $GITHUB_TOKEN" \
     https://api.github.com/user
   

Pull requests not found

If PRs aren’t being linked:

1. Check commit messages:

   git log --oneline -10
   

   Ensure PR numbers are mentioned: feat: Add feature (#123)

2. Verify GitHub token:

   echo $GITHUB_TOKEN | cut -c1-10
   

3. Test without caching:

   rm -rf .gitreleasegen-cache/
   gitreleasegen generate --unreleased
   

4. Check repository slug:

   git remote get-url origin
   

Slow generation

To speed up generation:

1. Enable caching:

   export HELIXCOMMIT_GH_CACHE=1

2. Limit commits:

   gitreleasegen generate --max-items 50
   

3. Skip merges:

   gitreleasegen generate --no-merge-commits
   

4. Use offline mode for testing:

   gitreleasegen generate --no-prs
   

Best practices

Use consistent commit message format

Include PR numbers in commit messages:

# Good
git commit -m "feat: Add authentication (#123)"
git commit -m "fix: Resolve rate limiting (#124)"

# Avoid (PR won't be auto-linked)
git commit -m "Add authentication"

Enable caching in CI/CD

# GitHub Actions example
- name: Cache HelixCommit data
  uses: actions/cache@v3
  with:
    path: .helixcommit-cache
    key: helixcommit-${{ github.sha }}
    restore-keys: helixcommit-

- name: Generate release notes
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    HELIXCOMMIT_GH_CACHE: 1
  run: |
    helixcommit generate --unreleased --out RELEASE_NOTES.md

Use GitHub Actions token

GitHub Actions provides GITHUB_TOKEN automatically:

- name: Generate release notes
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    helixcommit generate --unreleased --out RELEASE_NOTES.md

No need to create a separate token!

Test without GitHub first

Verify basic functionality before enabling GitHub integration:

# Test offline
helixcommit generate --unreleased --no-prs

# Then enable GitHub
export GITHUB_TOKEN=ghp_...
helixcommit generate --unreleased

Next steps

Configuration

Configure GitHub integration settings

Examples

See GitHub integration in action

CI/CD integration

Automate release notes in GitHub Actions

Conventional Commits

Learn about commit message format