> ## Documentation Index
> Fetch the complete documentation index at: https://lunr-f6858e75.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  GitHub integration works with both public and private repositories. For private repos, you'll need to provide a GitHub token with appropriate permissions.
</Info>

## Benefits of GitHub integration

<CardGroup cols={2}>
  <Card title="Pull request links" icon="code-pull-request">
    Automatically link commits to their associated pull requests for better traceability
  </Card>

  <Card title="Author attribution" icon="user">
    Show who contributed each change, recognizing team members and external contributors
  </Card>

  <Card title="Compare URLs" icon="link">
    Generate comparison links between versions to see all changes in GitHub's UI
  </Card>

  <Card title="Rich metadata" icon="database">
    Include PR descriptions, labels, and review information in your release notes
  </Card>
</CardGroup>

## Quick start

### Enable GitHub integration

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

```bash theme={}
export GITHUB_TOKEN=ghp_your_token_here

helixcommit generate --unreleased --format markdown
```

<Check>
  That's it! HelixCommit automatically detects GitHub repositories and enriches the output.
</Check>

### Disable GitHub integration

Work offline or skip PR lookups:

```bash theme={}
helixcommit generate --unreleased --no-prs --format markdown
```

## Authentication

### Creating a GitHub token

<Steps>
  <Step title="Navigate to GitHub settings">
    Go to [github.com/settings/tokens](https://github.com/settings/tokens) and click **Generate new token**.

    Choose between:

    * **Classic token** - Traditional personal access tokens
    * **Fine-grained token** - More granular permissions (recommended)
  </Step>

  <Step title="Select permissions">
    <Tabs>
      <Tab title="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
      </Tab>

      <Tab title="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
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set the token">
    <CodeGroup>
      ```bash Environment variable (recommended) theme={}
      export GITHUB_TOKEN=ghp_your_token_here

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

      ```bash Command-line flag theme={}
      helixcommit generate \
        --unreleased \
        --github-token ghp_your_token_here \
        --format markdown
      ```

      ```yaml CI/CD (GitHub Actions) theme={}
      - name: Generate release notes
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          helixcommit generate --unreleased --out RELEASE_NOTES.md
      ```
    </CodeGroup>

    <Warning>
      Never commit tokens to version control. Use environment variables or secret management tools.
    </Warning>
  </Step>
</Steps>

## What gets enriched

### Pull request resolution

HelixCommit automatically finds PRs associated with commits:

<Tabs>
  <Tab title="Before GitHub integration">
    ```markdown theme={}
    ### Features
    - Add user authentication (abc123)
    - Implement dark mode (def456)
    ```
  </Tab>

  <Tab title="After GitHub integration">
    ```markdown theme={}
    ### 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
    ```
  </Tab>
</Tabs>

### Compare URLs

Automatic comparison links between versions:

```markdown theme={}
## 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

<Info>
  Using Conventional Commits with PR numbers in messages improves accuracy and reduces API calls.
</Info>

## 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:

<Steps>
  <Step title="Respects rate limit headers">
    Reads `X-RateLimit-Remaining` and stops before hitting the limit.
  </Step>

  <Step title="Exponential backoff">
    Retries failed requests with increasing delays.

    ```bash theme={}
    # Configure retry behavior
    export HELIXCOMMIT_GH_MAX_RETRIES=5
    export HELIXCOMMIT_GH_BACKOFF_BASE_SEC=1.0
    export HELIXCOMMIT_GH_BACKOFF_CAP_SEC=16
    ```
  </Step>

  <Step title="Smart caching">
    Caches API responses to reduce duplicate requests.

    ```bash theme={}
    # Enable persistent caching
    export HELIXCOMMIT_GH_CACHE=1
    export HELIXCOMMIT_GH_CACHE_TTL_MINUTES=30
    ```
  </Step>
</Steps>

### Monitoring rate limit usage

Check your current rate limit status:

```bash theme={}
# Using curl
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit

# Or using GitHub CLI
gh api rate_limit
```

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

## Caching

### Enable GitHub API caching

Reduce API calls and improve performance:

```bash theme={}
# 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

<AccordionGroup>
  <Accordion title="Clear cache">
    ```bash theme={}
    # Remove all cached data
    rm -rf .helixcommit-cache/github/

    # Regenerate with fresh data
    helixcommit generate --unreleased
    ```
  </Accordion>

  <Accordion title="View cache size">
    ```bash theme={}
    du -sh .helixcommit-cache/github/
    ```
  </Accordion>

  <Accordion title="Inspect cached PR">
    ```bash theme={}
    cat .helixcommit-cache/github/pr_123.json | python -m json.tool
    ```
  </Accordion>
</AccordionGroup>

## Configuration options

### Environment variables

<ResponseField name="GITHUB_TOKEN" type="string" required>
  GitHub personal access token for API authentication.

  ```bash theme={}
  export GITHUB_TOKEN=ghp_...
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_GH_MAX_RETRIES" type="integer" default="3">
  Maximum number of retry attempts for failed API requests.

  ```bash theme={}
  export HELIXCOMMIT_GH_MAX_RETRIES=5
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_GH_BACKOFF_BASE_SEC" type="float" default="0.5">
  Initial delay in seconds for exponential backoff.

  ```bash theme={}
  export HELIXCOMMIT_GH_BACKOFF_BASE_SEC=1.0
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_GH_BACKOFF_CAP_SEC" type="float" default="8">
  Maximum delay in seconds between retries.

  ```bash theme={}
  export HELIXCOMMIT_GH_BACKOFF_CAP_SEC=16
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_GH_CACHE" type="boolean" default="false">
  Enable persistent caching of GitHub API responses.

  ```bash theme={}
  export HELIXCOMMIT_GH_CACHE=1
  ```

  Valid values: `1`, `true`, `yes`, `on`
</ResponseField>

<ResponseField name="HELIXCOMMIT_GH_CACHE_DIR" type="path" default=".helixcommit-cache/github">
  Directory for storing cached GitHub API responses.

  ```bash theme={}
  export HELIXCOMMIT_GH_CACHE_DIR=.cache/gh-api
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_GH_CACHE_TTL_MINUTES" type="integer" default="10">
  Cache time-to-live in minutes.

  ```bash theme={}
  export HELIXCOMMIT_GH_CACHE_TTL_MINUTES=30
  ```
</ResponseField>

### CLI flags

<ParamField query="--github-token" type="string">
  Provide GitHub token via command line.

  ```bash theme={}
  helixcommit generate --github-token ghp_...
  ```

  <Warning>
    Prefer environment variables over command-line flags to avoid exposing tokens in shell history.
  </Warning>
</ParamField>

<ParamField query="--no-prs" type="boolean">
  Disable GitHub PR lookups entirely.

  ```bash theme={}
  helixcommit generate --no-prs
  ```

  Useful for:

  * Offline work
  * Non-GitHub repositories
  * Faster generation when PR data isn't needed
</ParamField>

## Troubleshooting

<AccordionGroup>
  <Accordion title="API rate limit exceeded">
    If you hit rate limits:

    1. **Use authentication:**
       ```bash theme={}
       export GITHUB_TOKEN=ghp_...
       ```

    2. **Enable caching:**

    ```bash theme={}
       export HELIXCOMMIT_GH_CACHE=1
    ```

    3. **Reduce API calls:**
       ```bash theme={}
       # Use --no-prs for testing
       gitreleasegen generate --no-prs
       ```

    4. **Wait for reset:**
       ```bash theme={}
       # Check when limit resets
       gh api rate_limit | jq '.rate.reset'
       ```
  </Accordion>

  <Accordion title="Permission denied errors">
    Verify your token has correct permissions:

    1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
    2. Check token has `repo` scope (for private repos)
    3. Verify token isn't expired
    4. Test token:
       ```bash theme={}
       curl -H "Authorization: token $GITHUB_TOKEN" \
         https://api.github.com/user
       ```
  </Accordion>

  <Accordion title="Pull requests not found">
    If PRs aren't being linked:

    1. **Check commit messages:**
       ```bash theme={}
       git log --oneline -10
       ```
       Ensure PR numbers are mentioned: `feat: Add feature (#123)`

    2. **Verify GitHub token:**
       ```bash theme={}
       echo $GITHUB_TOKEN | cut -c1-10
       ```

    3. **Test without caching:**
       ```bash theme={}
       rm -rf .gitreleasegen-cache/
       gitreleasegen generate --unreleased
       ```

    4. **Check repository slug:**
       ```bash theme={}
       git remote get-url origin
       ```
  </Accordion>

  <Accordion title="Slow generation">
    To speed up generation:

    1. **Enable caching:**

    ```bash theme={}
       export HELIXCOMMIT_GH_CACHE=1
    ```

    2. **Limit commits:**
       ```bash theme={}
       gitreleasegen generate --max-items 50
       ```

    3. **Skip merges:**
       ```bash theme={}
       gitreleasegen generate --no-merge-commits
       ```

    4. **Use offline mode for testing:**
       ```bash theme={}
       gitreleasegen generate --no-prs
       ```
  </Accordion>
</AccordionGroup>

## Best practices

<AccordionGroup>
  <Accordion title="Use consistent commit message format">
    Include PR numbers in commit messages:

    ```bash theme={}
    # 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"
    ```
  </Accordion>

  <Accordion title="Enable caching in CI/CD">
    ```yaml theme={}
    # 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
    ```
  </Accordion>

  <Accordion title="Use GitHub Actions token">
    GitHub Actions provides `GITHUB_TOKEN` automatically:

    ```yaml theme={}
    - 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!
  </Accordion>

  <Accordion title="Test without GitHub first">
    Verify basic functionality before enabling GitHub integration:

    ```bash theme={}
    # Test offline
    helixcommit generate --unreleased --no-prs

    # Then enable GitHub
    export GITHUB_TOKEN=ghp_...
    helixcommit generate --unreleased
    ```
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration" color="#F6A02D">
    Configure GitHub integration settings
  </Card>

  <Card title="Examples" icon="code" href="/examples" color="#0A6ACB">
    See GitHub integration in action
  </Card>

  <Card title="CI/CD integration" icon="rotate" href="/cicd-integration" color="#F26419">
    Automate release notes in GitHub Actions
  </Card>

  <Card title="Conventional Commits" icon="code-commit" href="/conventional-commits" color="#0A6ACB">
    Learn about commit message format
  </Card>
</CardGroup>