Automated Changelog Generation

Overview

The Agent Platform automatically generates changelogs from Conventional Commits, eliminating manual changelog maintenance. Every release includes a human-readable changelog that clearly communicates changes to users and stakeholders.

Keep a Changelog Format

The Agent Platform follows the Keep a Changelog format, which provides a consistent, readable structure.

Standard Structure

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New features that have been added

### Changed
- Changes in existing functionality

### Deprecated
- Soon-to-be removed features

### Removed
- Now removed features

### Fixed
- Any bug fixes

### Security
- Vulnerabilities and security fixes

## [0.3.5] - 2026-01-08

### Added
- OAuth2 authentication support (#106)
- Distributed tracing integration (#108)

### Fixed
- Memory leak in agent runtime (#107)
- Authentication token validation (#109)

## [0.3.4] - 2026-01-07

...

Category Definitions

Conventional Commits to Changelog

Mapping Rules

The Agent Platform uses these rules to map commits to changelog sections:

// Commit analyzer configuration
{
  "types": [
    { "type": "feat", "section": "Added" },
    { "type": "fix", "section": "Fixed" },
    { "type": "perf", "section": "Performance Improvements" },
    { "type": "refactor", "section": "Changed" },
    { "type": "docs", "section": "Documentation" },
    { "type": "test", "section": "Tests", "hidden": true },
    { "type": "chore", "section": "Maintenance", "hidden": true },
    { "type": "style", "section": "Code Style", "hidden": true }
  ]
}

Examples

Example 1: New Feature

Commit:

git commit -m "feat: add OAuth2 authentication support

Implements OAuth2 authentication flow with support for
authorization code and client credentials grants.

Closes #106"

Changelog Entry:

### Added
- OAuth2 authentication support (#106)

Example 2: Bug Fix

Commit:

git commit -m "fix: resolve memory leak in agent runtime

The agent runtime was not properly releasing resources
after task completion, causing memory usage to grow
over time.

Fixes #107"

Changelog Entry:

### Fixed
- Memory leak in agent runtime (#107)

Example 3: Breaking Change

Commit:

git commit -m "feat!: redesign authentication API

BREAKING CHANGE: The /auth endpoint now requires OAuth2
tokens instead of API keys. Update your integration to
use the new OAuth2 flow.

Closes #110"

Changelog Entry:

### Removed
- **BREAKING**: API key authentication (replaced with OAuth2) (#110)

### Added
- OAuth2 authentication API (#110)

Example 4: Security Fix

Commit:

git commit -m "fix: prevent SQL injection in user query

Properly sanitizes user input before constructing
SQL queries to prevent injection attacks.

Security: CVE-2026-1234
Fixes #111"

Changelog Entry:

### Security
- Prevent SQL injection in user query (CVE-2026-1234) (#111)

Automated Generation

Using semantic-release

The Agent Platform uses semantic-release to automatically generate changelogs.

Configuration (.releaserc.json):

{
  "plugins": [
    [
      "@semantic-release/commit-analyzer",
      {
        "preset": "conventionalcommits",
        "releaseRules": [
          { "type": "feat", "release": "patch" },
          { "type": "fix", "release": "patch" },
          { "type": "perf", "release": "patch" },
          { "breaking": true, "release": "patch" }
        ]
      }
    ],
    [
      "@semantic-release/release-notes-generator",
      {
        "preset": "conventionalcommits",
        "presetConfig": {
          "types": [
            { "type": "feat", "section": " Features" },
            { "type": "fix", "section": " Bug Fixes" },
            { "type": "perf", "section": " Performance" },
            { "type": "refactor", "section": " Refactoring" },
            { "type": "docs", "section": " Documentation" },
            { "type": "test", "hidden": true },
            { "type": "chore", "hidden": true }
          ]
        },
        "writerOpts": {
          "commitsSort": ["scope", "subject"]
        }
      }
    ],
    [
      "@semantic-release/changelog",
      {
        "changelogFile": "CHANGELOG.md",
        "changelogTitle": "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)."
      }
    ],
    "@semantic-release/gitlab",
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

CI/CD Pipeline

# .gitlab-ci.yml
generate-changelog:
  stage: release
  image: node:20-alpine
  before_script:
    - npm install -g semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/gitlab
  script:
    - |
      # Generate changelog and release notes
      npx semantic-release --dry-run > /tmp/release-notes.txt

      # Extract version
      NEXT_VERSION=$(grep "next release version is" /tmp/release-notes.txt | awk '{print $NF}')

      # Generate full changelog
      npx semantic-release

      # Commit updated CHANGELOG.md
      git add CHANGELOG.md
      git commit -m "chore(release): update CHANGELOG for $NEXT_VERSION [skip ci]"
      git push origin $CI_COMMIT_REF_NAME
  artifacts:
    paths:
      - CHANGELOG.md
  only:
    - /^release\/v[0-9]+\.[0-9]+\.x$/

GitLab Changelog API

GitLab provides a built-in Changelog API for generating release notes.

Using Changelog Trailers

Add Changelog: trailer to commits:

git commit -m "feat: add OAuth2 authentication

Implements OAuth2 authentication flow.

Changelog: added
Closes #106"

Supported values:

• added † Added section
• fixed † Fixed section
• changed † Changed section
• deprecated † Deprecated section
• removed † Removed section
• security † Security section
• performance † Performance section
• other † Other section

Generating with GitLab CLI

# Generate changelog between versions
glab changelog generate v0.3.4..v0.3.5 \
  --config-file .gitlab/changelog_config.yml \
  --output CHANGELOG.md

# Generate for current release
glab changelog generate HEAD \
  --trailer-regex '(?i)^(?:changelog|change log)\s*:?\s+(.+)' \
  --output CHANGELOG.md

Configuration

.gitlab/changelog_config.yml:

categories:
  " Features":
    - added
  " Bug Fixes":
    - fixed
  " Breaking Changes":
    - removed
  " Security":
    - security
  " Performance":
    - performance
  " Documentation":
    - changed
    - deprecated
    - other

template: |
  ## {{version}} ({{date}})

  {% for category in categories %}
  {% if entries[category] %}
  ### {{category}}

  {% for entry in entries[category] %}
  - {{entry.title}} ({{entry.merge_request}})
  {% endfor %}
  {% endif %}
  {% endfor %}

Manual Changelog Management

Unreleased Section

Maintain an [Unreleased] section for in-progress work:

## [Unreleased]

### Added
- OAuth2 authentication support (WIP)
- Kubernetes operator (in review)

### Fixed
- Memory leak in agent runtime (merged, pending release)

On Release: Move [Unreleased] content to new version section:

## [0.3.5] - 2026-01-08

### Added
- OAuth2 authentication support (#106)

### Fixed
- Memory leak in agent runtime (#107)

## [Unreleased]

<!-- Empty, ready for next changes -->

Manual Entries

For manual changelog maintenance (not recommended):

## [0.3.5] - 2026-01-08

### Added
- OAuth2 authentication with authorization code flow
- OAuth2 client credentials grant support
- Distributed tracing integration with OpenTelemetry

### Changed
- Improved error messages for authentication failures
- Updated API documentation with OAuth2 examples

### Fixed
- Memory leak in agent runtime caused by unclosed resources
- Authentication token validation edge case
- Race condition in concurrent agent execution

### Security
- Fixed SQL injection vulnerability in user query (CVE-2026-1234)

Changelog Best Practices

Writing Guidelines

DO

1. Write for humans, not machines

    Added OAuth2 authentication support
    Added oauth2_auth.py file

2. Link to issues/MRs

    Fixed memory leak in agent runtime (#107)
    Fixed memory leak in agent runtime

3. Group similar changes

   
   ### Added
   - OAuth2 authorization code flow
   - OAuth2 client credentials grant
   
   
   ### Added
   - OAuth2 authorization code flow
   
   ### Added
   - OAuth2 client credentials grant

4. Highlight breaking changes

    **BREAKING**: Removed API key authentication (use OAuth2)
    Removed API key authentication

5. Include dates

    ## [0.3.5] - 2026-01-08
    ## [0.3.5]

DON'T

1. Don't use commit log diffs

    Merge pull request #123 from feature/oauth2
    WIP: add oauth2
    Fix typo

2. Don't include noise

    Updated .gitignore
    Fixed linting errors
    Merged branch 'develop' into 'main'

3. Don't forget security fixes

    Fixed bug in user query
    **SECURITY**: Fixed SQL injection in user query (CVE-2026-1234)

4. Don't use technical jargon

    Refactored AuthStrategy to use Strategy pattern
    Improved authentication system architecture

Content Guidelines

Each changelog entry should:

• Describe the change from user's perspective
• Be concise but informative
• Include issue/MR reference
• Use imperative mood ("Add feature" not "Added feature")
• Start with capital letter
• Not end with period

Examples:

Good:

- Add OAuth2 authentication support (#106)
- Fix memory leak in agent runtime (#107)
- **BREAKING**: Remove API key authentication, use OAuth2 (#110)

Bad:

- added oauth2 auth.
- fixed a bug
- Removed some old code that wasn't being used anymore

Changelog Automation Tools

semantic-release

Pros:

• Fully automated
• Supports multiple formats
• Integrates with GitLab
• Generates release notes

Cons:

• Complex configuration
• Opinionated release rules
• Requires conventional commits

Install:

npm install --save-dev \
  semantic-release \
  @semantic-release/changelog \
  @semantic-release/git \
  @semantic-release/gitlab

standard-version

Pros:

• Simpler than semantic-release
• Focused on versioning and changelog
• Easy to configure
• Less opinionated

Cons:

• Doesn't publish releases
• Manual triggering
• Less feature-rich

Install:

npm install --save-dev standard-version

Usage:

# Bump version and update changelog
npx standard-version

# First release
npx standard-version --first-release

# Pre-release
npx standard-version --prerelease alpha

conventional-changelog-cli

Pros:

• Standalone tool
• No version bumping
• Flexible output
• Multiple presets

Cons:

• Manual integration
• No release automation
• Requires scripting

Install:

npm install --save-dev conventional-changelog-cli

Usage:

# Generate changelog
npx conventional-changelog -p angular -i CHANGELOG.md -s

# Generate for all releases
npx conventional-changelog -p angular -i CHANGELOG.md -s -r 0

git-cliff

Pros:

• Written in Rust (fast)
• Highly customizable
• Beautiful output
• Supports multiple formats

Cons:

• Not Node.js native
• Requires separate installation
• Less GitLab integration

Install:

# Via cargo
cargo install git-cliff

# Via npm
npm install --save-dev git-cliff

Usage:

# Generate changelog
git cliff --output CHANGELOG.md

# For specific range
git cliff --tag v0.3.5 --output CHANGELOG.md

Changelog in CI/CD

Automatic Update on Release

# .gitlab-ci.yml
update-changelog:
  stage: release
  image: node:20-alpine
  before_script:
    - apk add --no-cache git
    - npm install -g semantic-release @semantic-release/changelog @semantic-release/git
  script:
    - |
      # Configure git
      git config user.email "ci@agent-platform.io"
      git config user.name "GitLab CI"

      # Generate changelog
      npx semantic-release

      # Changelog is automatically committed by @semantic-release/git
  artifacts:
    paths:
      - CHANGELOG.md
    expire_in: 1 year
  only:
    - /^release\/v[0-9]+\.[0-9]+\.x$/

Validation

# Ensure all changes are documented
validate-changelog:
  stage: validate
  image: node:20-alpine
  script:
    - |
      # Check if CHANGELOG.md was updated in MR
      git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
      CHANGED_FILES=$(git diff --name-only origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME..HEAD)

      if ! echo "$CHANGED_FILES" | grep -q "CHANGELOG.md"; then
        # Check if commits include Changelog trailer
        COMMITS=$(git log origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME..HEAD --format=%B)
        if ! echo "$COMMITS" | grep -qi "^Changelog:"; then
          echo "WARNING: CHANGELOG.md not updated and no Changelog trailers found"
          echo "Consider adding 'Changelog: added/fixed/changed' to commit messages"
          exit 0  # Warning only, don't fail
        fi
      fi

      echo "Changelog validation passed"
  only:
    - merge_requests

Changelog Distribution

In GitLab Releases

Changelog content is automatically included in GitLab releases:

create-release:
  stage: release
  image: alpine:latest
  before_script:
    - apk add --no-cache git curl
  script:
    - |
      # Extract changelog for this version
      VERSION=$(echo $CI_COMMIT_TAG | sed 's/v//')
      CHANGELOG=$(sed -n "/## \[$VERSION\]/,/## \[/p" CHANGELOG.md | sed '$d')

      # Create GitLab release
      curl --request POST \
        --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
        --header "Content-Type: application/json" \
        --data "{
          \"tag_name\": \"$CI_COMMIT_TAG\",
          \"name\": \"Release $CI_COMMIT_TAG\",
          \"description\": \"$CHANGELOG\"
        }" \
        "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/releases"
  only:
    - tags

In Package Managers

Include changelog in package distribution:

package.json:

{
  "name": "@agent-platform/core",
  "version": "0.4.9",
  "files": [
    "dist/",
    "CHANGELOG.md",
    "README.md"
  ]
}

As Email Notification

notify-changelog:
  stage: notify
  image: alpine:latest
  script:
    - |
      # Extract latest changelog entry
      VERSION=$(echo $CI_COMMIT_TAG | sed 's/v//')
      CHANGELOG=$(sed -n "/## \[$VERSION\]/,/## \[/p" CHANGELOG.md | sed '$d')

      # Send email notification
      curl --request POST \
        --header "Content-Type: application/json" \
        --data "{
          \"to\": \"team@agent-platform.io\",
          \"subject\": \"New Release: $CI_COMMIT_TAG\",
          \"body\": \"$CHANGELOG\"
        }" \
        "$NOTIFICATION_WEBHOOK_URL"
  only:
    - tags

Multi-Project Changelogs

For monorepos with multiple projects:

Per-Project Changelogs

agent-platform/
 CHANGELOG.md           (platform-wide changes)
 packages/
‚    core/
‚   ‚    CHANGELOG.md  (core package changes)
‚    cli/
‚   ‚    CHANGELOG.md  (CLI changes)
‚    sdk/
‚        CHANGELOG.md  (SDK changes)

Aggregated Changelog

Use tags to aggregate changes:

# Changelog

## [0.3.5] - 2026-01-08

### @agent-platform/core

#### Added
- OAuth2 authentication support (#106)

#### Fixed
- Memory leak in agent runtime (#107)

### @agent-platform/cli

#### Added
- New `auth` command for OAuth2 setup (#108)

### @agent-platform/sdk

#### Changed
- Updated authentication API to use OAuth2 (#109)

Automated Aggregation

#!/bin/bash
# aggregate-changelog.sh

VERSION=$1

echo "# Changelog" > CHANGELOG.md
echo "" >> CHANGELOG.md
echo "## [$VERSION] - $(date +%Y-%m-%d)" >> CHANGELOG.md
echo "" >> CHANGELOG.md

for package in packages/*/; do
  PACKAGE_NAME=$(basename $package)
  echo "### @agent-platform/$PACKAGE_NAME" >> CHANGELOG.md
  echo "" >> CHANGELOG.md

  # Extract changelog for this version from package
  sed -n "/## \[$VERSION\]/,/## \[/p" "$package/CHANGELOG.md" | sed '1d;$d' >> CHANGELOG.md
  echo "" >> CHANGELOG.md
done

Troubleshooting

Issue: Changelog Not Generated

Problem: Changelog not updating automatically

Solution:

# Check semantic-release configuration
npx semantic-release --dry-run --debug

# Verify conventional commits
git log --oneline --format="%s" | npx commitlint

Issue: Missing Entries

Problem: Some commits not appearing in changelog

Solution:

# Check commit types
git log --oneline --format="%s" HEAD~10..HEAD

# Ensure commits follow convention
# Example: "feat: add feature" not "add feature"

Issue: Wrong Section

Problem: Commit in wrong changelog section

Solution: Configure commit analyzer in .releaserc.json:

{
  "preset": "conventionalcommits",
  "presetConfig": {
    "types": [
      { "type": "feat", "section": " Features" },
      { "type": "fix", "section": " Bug Fixes" }
    ]
  }
}

Issue: Duplicate Entries

Problem: Changelog has duplicate entries

Solution:

# Clean up duplicate tags
git tag -l | sort | uniq -d | xargs git tag -d

# Regenerate changelog
npx semantic-release --no-ci

Resources

• Keep a Changelog
• Conventional Changelog
• semantic-release Changelog Plugin
• GitLab Changelog API
• Common Changelog

See Also

• Semantic Versioning
• Automated Version Bumping
• Conventional Commits
• GitLab Releases
• Release Branches