AI Changelog Generator

Date: 2026-03-17
Status: ✅ Active
Workflow: .github/workflows/ai-changelog.yml

---

Overview

The AI Changelog Generator automatically creates daily development changelog files in docs/changelogs/dev/ by analyzing git commits using Anthropic Claude. It follows the same AI integration pattern as the AI Issue Triage workflow.

---

What It Does

Trigger Events

• Push to dev branch — runs automatically on every push, analyzing only the commits in that push
• Manual dispatch — allows ad-hoc runs with optional dry-run mode and configurable time window

Process

1. Checks if the triggering actor is a bot (skips to prevent infinite loops)
2. Gets commits from the push event (BEFORE_SHA..AFTER_SHA) or last N hours for manual runs
3. Filters out automated commits (merge commits, version bumps, [skip ci] tags)
4. Sends commit messages to Claude (claude-haiku-4-5-20251001) for analysis
5. Claude returns a structured JSON response with changelog entries grouped by category
6. Generates a markdown file following the Keep a Changelog format
7. If today's file already exists, appends a timestamped update section
8. Commits the file back to dev with [skip ci] to avoid re-triggering

Output Format

Generated files follow the existing naming convention and template:

docs/changelogs/dev/dev-MM.DD.YYYY-v{version}.md

Example output:

# Changelog - Dev - 03.17.2026

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.0.0/).

---

## [Unreleased] - 2026-03-17

### Added

- New venue proximity check for lantern lighting
- Location permission request flow in onboarding

### Fixed

- Resolve race condition in venue cache refresh

---

Configuration

Required Secret

Secret	Description
ANTHROPIC_API_KEY	Anthropic API key for Claude access. See API Key Setup.

If ANTHROPIC_API_KEY is not configured, the workflow skips gracefully without failing.

Optional Secret

Secret	Description
GH_PAT	Personal Access Token for pushing to protected branches. Falls back to GITHUB_TOKEN if not set.

---

Manual Usage

Trigger via GitHub UI

1. Go to Actions → AI Changelog Generator
2. Click Run workflow
3. Configure options:
   • dry_run: true to preview the changelog without committing
   • since_hours: How many hours back to look for commits (default: 24)

Dry Run

Use dry run to preview what the AI would generate before committing:

GitHub Actions → AI Changelog Generator → Run workflow → dry_run: true

---

Behavior

Deduplication

• Multiple pushes on the same day: The first push creates the daily file. Subsequent pushes append a new timestamped ## Update - YYYY-MM-DD HH:MM UTC section.
• Bot-triggered runs: Automatically skipped to prevent infinite loops when the workflow commits a changelog back to dev.

Graceful Degradation

• Missing ANTHROPIC_API_KEY → workflow skips with a notice (no failure)
• API errors → workflow logs the error and skips without failing
• No meaningful commits → workflow skips silently
• All failures are surfaced in the Job Summary for visibility

---

Integration with Existing Workflow

This workflow fits into the existing changelog lifecycle:

Push to dev
    ↓
AI Changelog Generator
    ↓
docs/changelogs/dev/dev-MM.DD.YYYY-v{version}.md created
    ↓ (when ready for prod release)
npm run changelog:consolidate
    ↓
docs/changelogs/prod/prod-MM.DD.YYYY-v{version}.md created

See CHANGELOG_WORKFLOW.md for the full production promotion workflow.

---

AI Model

• Model: claude-haiku-4-5-20251001 (same as AI Issue Triage)
• Temperature: 0.3 (deterministic, consistent output)
• Max tokens: 1000
• Estimated cost: ~$0.001–0.005 per push

---

References

• AI Issue Triage — the original AI workflow this is modeled after
• CHANGELOG_WORKFLOW.md — full changelog process
• Keep a Changelog
• Anthropic API Docs