Release Notes Bot

Automated release notes generator supporting GitLab and GitHub APIs.

How It Works

The script analyzes changes between two Git commits and generates human-readable release notes using AI. Here's what happens when you run it:

1. Fetches Git Changes: Connects to the GitLab or GitHub API (based on --platform) to retrieve commits, file changes, and diffs between the specified commit hashes (--before and --after).

2. Detects Context: Identifies whether the changes represent a merge request or a single commit, extracting relevant branch and commit information.

3. Filters & Sanitizes: Removes asset files (images, fonts, etc.) and unnecessary metadata from the diff data to optimize token usage.

4. Estimates Costs: Calculates estimated token usage and API costs before making the LLM call, so you know what to expect.

5. Generates Release Notes: Sends the processed commit data to OpenAI's GPT-4o-mini model, which analyzes the changes and generates formatted release notes with:

   • Summary of changes
   • Categorized features, fixes, and improvements
   • Emojis for visual clarity
   • Markdown formatting

6. Displays Results: Shows the generated release notes in the console, along with actual token usage and costs.

7. Sends to Slack (optional): If Slack credentials are provided, automatically posts the release notes to the specified channel or user, formatted with Slack Block Kit for better readability.

Setup

1. Install dependencies:

pnpm install

2. Build the project:

pnpm build

Usage

Using npx (Recommended - No installation needed)

GitLab Example:

npx -p @litebox-packages/release-notes-bot release-notes-bot --platform gitlab --before <commit-hash-1> --after <commit-hash-2> --projectId <gitlab-project-id> --token <gitlab-token> --openaiToken <openai-token> --slackToken <slack-token> --slackChannelId <slack-channel-id>

GitHub Example:

npx -p @litebox-packages/release-notes-bot release-notes-bot --platform github --before <commit-hash-1> --after <commit-hash-2> --owner <owner> --repo <repo> --token <github-token> --openaiToken <openai-token> --slackToken <slack-token> --slackChannelId <slack-channel-id>

Option 2: Direct npx (may require clearing cache)

npx @litebox-packages/release-notes-bot --platform gitlab --before <commit-hash-1> --after <commit-hash-2> --projectId <gitlab-project-id> --token <gitlab-token> --openaiToken <openai-token> --slackToken <slack-token> --slackChannelId <slack-channel-id>

If Option 2 doesn't work, try clearing npx cache:

rm -rf ~/.npm/_npx

Development Mode (using ts-node)

GitLab:

pnpm dev --platform gitlab --before <commit-hash-1> --after <commit-hash-2> --projectId <gitlab-project-id> --token <gitlab-token> --openaiToken <openai-token> --slackToken <slack-token> --slackChannelId <slack-channel-id>

GitHub:

pnpm dev --platform github --before <commit-hash-1> --after <commit-hash-2> --owner <owner> --repo <repo> --token <github-token> --openaiToken <openai-token> --slackToken <slack-token> --slackChannelId <slack-channel-id>

Production Mode (after building)

GitLab:

pnpm start --platform gitlab --before <commit-hash-1> --after <commit-hash-2> --projectId <gitlab-project-id> --token <gitlab-token> --openaiToken <openai-token> --slackToken <slack-token> --slackChannelId <slack-channel-id>

GitHub:

pnpm start --platform github --before <commit-hash-1> --after <commit-hash-2> --owner <owner> --repo <repo> --token <github-token> --openaiToken <openai-token> --slackToken <slack-token> --slackChannelId <slack-channel-id>

Or directly with node:

node dist/cli.js --platform gitlab --before <commit-hash-1> --after <commit-hash-2> --projectId <gitlab-project-id> --token <gitlab-token> --openaiToken <openai-token> --slackToken <slack-token> --slackChannelId <slack-channel-id>

Getting Required Tokens

GitLab Personal Access Token

To get your GitLab personal access token:

1. Go to your GitLab instance (e.g., https://gitlab.com or your self-hosted instance)
2. Click on your profile picture/avatar in the top right corner
3. Select Settings (or Preferences)
4. In the left sidebar, click Access Tokens
5. Give your token a name (e.g., "Release Notes Bot")
6. Set an expiration date (optional)
7. Select the api scope (required)
8. Click Create personal access token
9. Copy the token immediately - you won't be able to see it again!

The token will start with glpat- for GitLab.com or your instance's prefix.

GitHub Personal Access Token

To get your GitHub personal access token:

1. Go to https://github.com/settings/tokens
2. Click Generate new token → Generate new token (classic)
3. Give your token a name (e.g., "Release Notes Bot")
4. Set an expiration date (optional)
5. Select the repo scope (required for private repositories)
   • For public repositories, you can use a token without any scopes, but repo scope is recommended
6. Click Generate token
7. Copy the token immediately - you won't be able to see it again!

The token will be a long alphanumeric string (no specific prefix).

OpenAI API Key

1. Go to https://platform.openai.com/api-keys
2. Sign in or create an account
3. Click Create new secret key
4. Give it a name (e.g., "Release Notes Bot")
5. Copy the key immediately - you won't be able to see it again!

The key will start with sk-.

Slack Bot Token (Optional)

1. Go to https://api.slack.com/apps
2. Create a new app or select an existing one
3. Go to OAuth & Permissions in the left sidebar
4. Under Bot Token Scopes, add chat:write permission
5. Install the app to your workspace
6. Copy the Bot User OAuth Token (starts with xoxb-)

To get the Channel ID:

• Right-click on the channel in Slack → View channel details → Copy the Channel ID (starts with C)
• For DMs, use the user's ID (starts with U)

Arguments

Common Arguments (Required)

• --platform: Platform to use - either gitlab or github (default: gitlab)
• --before: The commit hash to compare from (older commit)
• --after: The commit hash to compare to (newer commit)
• --token: Your Git provider personal access token (GitLab or GitHub)
• --openaiToken: Your OpenAI API key (starts with sk-)

GitLab-Specific Arguments (Required when --platform gitlab)

• --projectId: Your GitLab project ID (can be found in project settings)

GitHub-Specific Arguments (Required when --platform github)

• --owner: Repository owner (username or organization name)
• --repo: Repository name

Optional Arguments

• --slackToken: Your Slack bot token (starts with xoxb-). If provided, --slackChannelId is also required.
• --slackChannelId: Slack channel ID or user DM ID where release notes will be sent. Required if --slackToken is provided. Slack failures are non-fatal and will only log a warning.

Examples

GitLab Example

npx -p @litebox-packages/release-notes-bot release-notes-bot --platform gitlab --before abc123 --after def456 --projectId 12345 --token glpat-xxxxxxxxxxxxx --openaiToken sk-xxxxxxxxxxxxx --slackToken xoxb-xxxxxxxxxxxxx --slackChannelId C09TVLQ33HN

GitHub Example

npx -p @litebox-packages/release-notes-bot release-notes-bot --platform github --before abc123 --after def456 --owner octocat --repo Hello-World --token ghp_xxxxxxxxxxxxx --openaiToken sk-xxxxxxxxxxxxx --slackToken xoxb-xxxxxxxxxxxxx --slackChannelId C09TVLQ33HN

Local Development (GitLab)

pnpm dev --platform gitlab --before abc123 --after def456 --projectId 12345 --token glpat-xxxxxxxxxxxxx --openaiToken sk-xxxxxxxxxxxxx --slackToken xoxb-xxxxxxxxxxxxx --slackChannelId C09TVLQ33HN

Local Development (GitHub)

pnpm dev --platform github --before abc123 --after def456 --owner octocat --repo Hello-World --token ghp_xxxxxxxxxxxxx --openaiToken sk-xxxxxxxxxxxxx --slackToken xoxb-xxxxxxxxxxxxx --slackChannelId C09TVLQ33HN

CI/CD Integration

GitLab CI Integration

In your .gitlab-ci.yml, you can use it like this:

generate-release-notes:
  script:
    - npx -p @litebox-packages/release-notes-bot release-notes-bot --platform gitlab --before "$CI_COMMIT_BEFORE_SHA" --after "$CI_COMMIT_SHA" --projectId "$CI_PROJECT_ID" --token "$GITLAB_TOKEN" --openaiToken "$OPENAI_TOKEN" --slackToken "$SLACK_TOKEN" --slackChannelId "$SLACK_CHANNEL_ID"

GitHub Actions Integration

In your .github/workflows/release-notes.yml, you can use it like this:

name: Generate Release Notes

on:
  push:
    branches:
      - main

jobs:
  generate-release-notes:
    runs-on: ubuntu-latest
    steps:
      - name: Generate Release Notes
        run: |
          npx -p @litebox-packages/release-notes-bot release-notes-bot \
            --platform github \
            --before "${{ github.event.before }}" \
            --after "${{ github.sha }}" \
            --owner "${{ github.repository_owner }}" \
            --repo "${{ github.event.repository.name }}" \
            --token "${{ secrets.GITHUB_TOKEN }}" \
            --openaiToken "${{ secrets.OPENAI_TOKEN }}" \
            --slackToken "${{ secrets.SLACK_TOKEN }}" \
            --slackChannelId "${{ secrets.SLACK_CHANNEL_ID }}"