🚀 Key Features

• 🎯 Release Confidence - Organizes stories by acceptance status, instantly flagging unapproved features before they ship
• 📊 Rapid Release Visibility - Groups commits by story status and type, making it clear what's ready, what needs attention, and what's incomplete
• ⚡ Zero Friction Setup - Just 2 environment variables to start - designed for CI/CD integration and frequent deployments
• 🤖 GitHub Action Available - Ready-to-use action for updating GitHub releases with generated changelogs

🔧 Prerequisites

• A git-managed repository
• An active Tracker Boot project
• Node.js 22+ (for running the CLI only - your project can use any language)

[!NOTE] This is a standalone CLI tool. You don't need to add it to your project's dependencies.

[!WARNING] The Tracker Boot API used by this tool is not officially documented for external use.
While it works reliably, the API may change without notice. Please report any issues you encounter.

🎯 Quick Start

# Run directly with npx (no installation required)
npx tb-changelog --from v1.0.0

# Copy changelog to clipboard (macOS)
npx tb-changelog --from v1.0.0 | pbcopy

# Save to a file
npx tb-changelog --from v1.0.0 --output CHANGELOG.md

📸 Output Examples & Formats

github (default) - Full format with commit details:

• Good for internal development tracking
• 📄 View complete example
• Live demo on GitHub to experience how commit hashes become clickable links when posted in releases.

github-light - Streamlined format with story titles only:

• Good for quick team updates
• 📄 View complete example

slack-payload - Slack Block Kit JSON format:

• Good for Slack notifications via GitHub Actions
  • Includes placeholders (<your-channel>, <your-color>, <your-title>, <your-release-url>) for dynamic values
• 📄 View complete example

🤖 GitHub Action Integration

A GitHub Action is available to automatically update your releases with generated changelogs.

📖 View GitHub Actions documentation

📚 Usage

Configuration

export TB_API_KEY=your_tracker_boot_api_key
export TB_PROJECT_ID=your_tracker_boot_project_id

Command Line Options

Usage: tb-changelog [options]                                                                                                     

Options:
  --from <tag>                     Start tag/branch/commit (required)
  --to <tag>                       End tag/branch/commit (default: HEAD)
  --tb-project-id <id>             TrackerBoot project ID
                                   Example: 123456789
  --output <file>, -o <file>       Output file path (optional)
  --format <type>, -f <type>       Output format (default: github)
                                   Options: github, github-light, slack-payload
  --no-signature                   Disable signature in output
  --use-cache                      Cache processed data (CI only - no expiration)
                                   For generating multiple formats in same run
  --help, -h                       Show this help message

Environment Variables:
  TB_API_KEY                       TrackerBoot API key (required)
  TB_PROJECT_ID                    TrackerBoot project ID (alternative to --tb-project-id)

Note: CLI arguments take precedence over environment variables when both are provided.

📝 Commit Message Format

This tool recognizes Tracker Boot story IDs in commit messages:

# Basic format - Associates commit with story (no status change)
[#123456] Add user authentication

# Mark story as finished (all keywords work the same)
[Finishes #123456] Complete login feature
[Fixes #123456] Resolve critical bug
[Fix #123456] Quick patch

# Multiple stories (comma-separated)
[#123456, #123457] Update API endpoints for both features

Supported keywords for marking stories as finished:
Finish, Finishes, Finished, Fix, Fixes, Fixed (case-insensitive)

[!NOTE] This format is based on Pivotal Tracker's specifications.
Once Tracker Boot officially publishes their git integration specifications, these conventions may change.

🔑 Getting Your Credentials

Tracker Boot Project ID

Find your project ID in the URL when viewing the project:

https://trackerboot.com/projects/[PROJECT_ID]
                                 ^^^^^^^^^^^^

API Key

1. Navigate to Tracker Boot Settings
2. Copy your existing API key
3. Keep it secure - treat it like a password!