Azure DevOps Changelog Generator

A Node.js library for generating professional changelogs from git tags and Azure DevOps work items.

Features

• ✅ Manual Tag Range Selection - Specify exactly which versions to compare
• ✅ Multiple Release Changelogs - Generate individual changelogs for each version increment
• ✅ Smart Pre-Release Detection - Automatically includes pre-releases when needed based on input tags
• ✅ Azure DevOps Integration - Fetches work item titles and details
• ✅ Smart Commit Filtering - Excludes merge commits, version bumps, and "Merged PR" commits
• ✅ Pipeline Links - Includes clickable links to Azure DevOps build results
• ✅ Professional Formatting - Clean markdown output

Installation

npm install azure-devops-changelog-generator

Configuration

Create a .env file in your project root:

# Azure DevOps Configuration
AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
AZURE_DEVOPS_ACCESS_TOKEN=your-personal-access-token-here
AZURE_DEVOPS_PROJECT=your-project-name

# Optional: Project display name for changelog header (defaults to AZURE_DEVOPS_PROJECT if not set)
AZURE_DEVOPS_PROJ_NAME=Internal Front

Azure DevOps Personal Access Token

1. Go to Azure DevOps: https://dev.azure.com/your-organization
2. Click your profile picture → Personal access tokens
3. Click + New Token
4. Set these permissions:
   • Work Items: Read
   • Build: Read (optional, for pipeline URLs)
5. Copy the token and add it to your .env file

Usage

Command Line Interface

# Run the interactive changelog generator
npx generate-changelog

# Or if installed globally
generate-changelog

The CLI will prompt you for:

1. Current/newer version tag (e.g., v1.14.2)
2. Previous/older version tag (e.g., v1.14.0)

Smart Pre-Release Detection: The tool automatically detects if you want pre-releases included:

• If either version tag contains -Number (e.g., v1.14.0-1), pre-releases will be included
• If both versions are regular releases (e.g., v1.14.2, v1.14.0), pre-releases will be excluded

The generator will then create changelogs for all version pairs between your specified range.

Programmatic Usage

const { ChangelogGenerator } = require('azure-devops-changelog-generator');

async function generateChangelog() {
  // Smart detection example
  const currentVersion = 'v1.14.2';
  const previousVersion = 'v1.14.0-1'; // Pre-release
  
  // Automatically detect if pre-releases should be included
  const includePreReleases = ChangelogGenerator.shouldIncludePreReleases(currentVersion, previousVersion);
  console.log('Pre-releases will be included:', includePreReleases); // true
  
  const generator = new ChangelogGenerator(
    'https://dev.azure.com/your-org',
    'your-personal-access-token',
    'your-project-name',
    'Custom Project Display Name', // Optional: project display name for changelog header
    includePreReleases // Or pass true/false to override smart detection
  );

  await generator.initialize();
  
  const changelog = await generator.generateChangelog(currentVersion, previousVersion);
  console.log(changelog);
}

How It Works

1. Tag Range Detection: Finds all git tags between your specified range
2. Pre-Release Filtering: Excludes tags ending with -Number (like v1.14.0-0)
3. Commit Analysis: Gets commits between each consecutive tag pair
4. Work Item Extraction: Finds 5-digit work item IDs in commit messages
5. Azure DevOps Integration: Fetches work item titles and pipeline details
6. Changelog Generation: Creates formatted markdown for each version

Example Output

## Your Project Name Here

**Version**: v1.14.2 [⚙ Pipeline](https://dev.azure.com/your-org/_build/results?buildId=9843)

### Includes

- 25217 - Incident - after clicking on new variants, a white screen appears

---

## Your Project Name Here

**Version**: v1.14.1 [⚙ Pipeline](https://dev.azure.com/your-org/_build/results?buildId=9840)

### Includes

- 24499 - Homepage product updates for July 2025 deployment

Note: The project name in the changelog header is configurable via the AZURE_DEVOPS_PROJ_NAME environment variable or constructor parameter.

Git Tag Format

The library expects git tags in semantic versioning format:

• ✅ v1.14.2 (release)
• ✅ v1.14.1 (release)
• ✅ v1.14.0-0 (pre-release, included only if specified)
• ✅ v1.14.0-1 (pre-release, included only if specified)

Pre-Release Handling

By default, pre-release tags (ending with -Number like v1.14.0-0, v1.14.0-1) are excluded from changelog generation. However, the tool includes smart automatic detection:

Smart Detection Logic:

• ✅ If either version tag is a pre-release (contains -Number), pre-releases are automatically included
• ❌ If both version tags are regular releases, pre-releases are automatically excluded

Examples:

• v1.14.2 → v1.14.0: Excludes pre-releases (both are regular releases)
• v1.14.0-2 → v1.14.0-0: Includes pre-releases (both are pre-releases)
• v1.14.2 → v1.14.0-1: Includes pre-releases (previous is pre-release)
• v1.14.0-3 → v1.13.5: Includes pre-releases (current is pre-release)

Manual Override (Programmatic Usage):

• Pass true/false as the 5th parameter to the constructor to override smart detection
• Use the filterTags() method to manually filter tags

Use Cases for Pre-Releases:

• Creating changelogs between pre-release versions (e.g., v1.14.0-0 to v1.14.0-2)
• Including pre-release work in final release notes
• Tracking changes during development cycles

Work Item Detection

The library automatically detects 5-digit work item IDs in commit messages:

• ✅ 25217 fix display of transition cost value
• ✅ 24499 Updated Products
• ❌ 123 small fix (too short)

Troubleshooting

401 Authentication Error

• Verify your Personal Access Token is correct
• Check that the token has "Work Items (Read)" permissions
• Ensure the token hasn't expired

No Work Items Found

• Check that commit messages contain 5-digit work item IDs
• Verify the work items exist in your Azure DevOps project

No Pipeline URLs

• Add "Build (Read)" permission to your Personal Access Token
• Check that builds exist for the specified tags

API Reference

ChangelogGenerator

Constructor

new ChangelogGenerator(organizationUrl, personalAccessToken, project, projectDisplayName, includePreReleases)

Parameters:

• organizationUrl (string): Your Azure DevOps organization URL
• personalAccessToken (string): Azure DevOps Personal Access Token
• project (string): Azure DevOps project name (used for API calls)
• projectDisplayName (string, optional): Display name for the changelog header (defaults to AZURE_DEVOPS_PROJ_NAME environment variable, then falls back to project)
• includePreReleases (boolean, optional): Whether to include pre-release tags (default: false)

Methods

initialize()

Initializes the Azure DevOps API clients.

filterTags(tags)

Filters tags based on the includePreReleases setting. Returns all tags if pre-releases are included, otherwise filters out pre-release tags.

shouldIncludePreReleases(currentVersion, previousVersion) (static)

Smart detection method that returns true if either version tag is a pre-release, indicating that pre-releases should be included in the changelog.

generateChangelog(version, previousVersion)

Generates a changelog between two versions.

getCommitsBetweenTags(fromTag, toTag)

Gets filtered commits between two git tags.

extractWorkItemIds(commits)

Extracts work item IDs from commit messages.

getWorkItemDetails(workItemIds)

Fetches work item details from Azure DevOps.

getPipelineUrl(version)

Gets the pipeline URL for a specific version tag.

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request