Skip to content

AI-powered GitHub Action that generates PR suggestions to changelog suitable for LLM retrieval, easy engineer onboarding, and sales enablement.

License

Notifications You must be signed in to change notification settings

lukemun/context-ledger

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

37 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Context Ledger

GitHub marketplace GitHub release

A GitHub Action that maintains a source of truth for LLM context across your codebase. Automatically generates meaningful changelog entries using AI by analyzing your pull request commits, file changes, and git history. Features one-click application via GitHub's suggestion system.

Installation: Use lukemun/context-ledger@v1 in your workflows. For the latest features, use @main.

🛠️ Quick Setup

  • Add secret: In GitHub → Settings → Secrets and variables → Actions → New repository secret

    • Name: ANTHROPIC_API_KEY
    • Value: your Anthropic API key
  • Add workflow: Create .github/workflows/changelog.yml

name: Update Changelog

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened, ready_for_review]
    paths-ignore:
      - "**/CHANGELOG.md"
      - "CHANGELOG.md"

permissions:
  contents: write
  pull-requests: write

jobs:
  update-changelog:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate Changelog
        uses: lukemun/context-ledger@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # Optional: changelog_path, target_name, commit_range, version_increment, create_pr_suggestions, auto_commit
  • Create changelog: Add CHANGELOG.md to your repo root
# Changelog

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

## [Unreleased]

<!-- CONTEXT_LEDGER_MARKER -->
  • Open a PR: The action analyzes your changes and suggests entries for CHANGELOG.md.

✨ Features

  • 🤖 AI-Powered Analysis: Uses Claude AI to understand commit patterns and generate meaningful changelog entries
  • 📝 Smart Categorization: Automatically categorizes changes (Added, Changed, Fixed, etc.) based on commit messages
  • 🔄 One-Click Application: Creates GitHub suggestions for instant changelog updates
  • 🚀 Semantic Versioning: Automatically determines appropriate version increments (major, minor, patch)
  • 🔒 Loop Prevention: Intelligent detection to prevent infinite automation loops
  • 📊 Multiple Triggers: Works with pull requests, releases, and manual workflow dispatch
  • 🎯 Flexible Configuration: Supports custom changelog paths, target names, and versioning strategies

📦 Common Use Cases

  • Keep LLMs in sync with your codebase: Maintain a canonical changelog that becomes the model's source of truth for context. Ideal for AI-assisted code review, agents, and RAG pipelines.
  • Automated release notes: Trigger on release: published to generate human‑readable notes for changelogs and GitHub Releases.
  • Monorepo per-package changelogs: Run in a matrix to append entries only to packages that changed.
  • Compliance and audit trails: Preserve an append‑only ledger of changes with PR‑linked provenance and one‑click suggestions.
  • Docs-as-code workflows: Ensure product and API docs stay aligned with actual shipped changes.
  • Faster onboarding for new engineers and contractors (founder benefit): Give an LLM the precise, up‑to‑date context to answer “how does this work?” based on real, recent changes. Reduce ramp‑up time without long knowledge dumps.
  • Sales enablement with up‑to‑date product information: Keep customer‑facing docs, release summaries, and collateral aligned with what actually shipped so sales can speak confidently and accurately.

🧩 In-Depth Setup

Simple Setup (single project)

Add this workflow to .github/workflows/changelog.yml:

name: Update Changelog

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened, ready_for_review]
    paths-ignore:
      - "**/CHANGELOG.md"
      - "CHANGELOG.md"

jobs:
  update-changelog:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate Changelog
        uses: lukemun/context-ledger@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          changelog_path: "CHANGELOG.md"
          target_name: "project"

This is all most repos need. No installation required — the workflow simply references lukemun/context-ledger@v1.

Monorepo Setup (advanced)

Follow these steps to set up Context Ledger for multi-project repositories:

Step 1: Create the Workflow File

Create .github/workflows/changelog.yml in your repository:

name: Update Changelog

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened, ready_for_review]
    paths-ignore:
      - "docs/**"
      - "**/CHANGELOG.md"
      - "CHANGELOG.md"

  release:
    types: [published]

  workflow_dispatch:
    inputs:
      target_changelog:
        description: "Target changelog to update"
        required: false
        default: "project-wide"
        type: choice
        options:
          - "project-wide"
          - "your-service-name" # Add your service names here
      commit_range:
        description: "Number of recent commits to analyze (default: 10)"
        required: false
        default: "10"
      version_increment:
        description: "Version increment type"
        required: false
        default: "auto"
        type: choice
        options:
          - "auto"
          - "patch"
          - "minor"
          - "major"

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  update-changelog:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.ref }}
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Update Changelog with Context Ledger
        uses: lukemun/context-ledger@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          changelog_path: "CHANGELOG.md"
          target_name: ${{ inputs.target_changelog || 'project-wide' }}
          commit_range: ${{ inputs.commit_range || '10' }}
          version_increment: ${{ inputs.version_increment || 'auto' }}
          auto_commit: ${{ github.event_name != 'pull_request' }}
          create_pr_suggestions: ${{ github.event_name == 'pull_request' }}

Step 2: Create Initial Changelog

Create a CHANGELOG.md file in your repository root:

# 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.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- Initial features and functionality

Step 3: Get Anthropic API Key

  1. Sign up at Anthropic Console
  2. Create a new API key
  3. Copy the key (starts with sk-ant-)

Step 4: Add API Key to Repository Secrets

  1. Go to your repository on GitHub
  2. Click SettingsSecrets and variablesActions
  3. Click New repository secret
  4. Name: ANTHROPIC_API_KEY
  5. Value: Your API key from Step 3
  6. Click Add secret

Step 5: Commit and Push

git add .github/workflows/changelog.yml CHANGELOG.md
git commit -m "feat: add Context Ledger for automated changelog generation"
git push origin main

Step 6: Test It!

Create a new pull request and watch Context Ledger analyze your changes and suggest changelog entries!

⚠️ Important Notes

  • Workflow file must be on main branch: The workflow file needs to exist on your main branch before it will run on PRs
  • API key required: Without ANTHROPIC_API_KEY, Context Ledger will post a helpful comment with setup instructions
  • First run: The action will run starting with your first PR after adding the workflow to main
  • Permissions: Make sure your repository allows Actions to write to PRs (enabled by default)
  • Customize target options: Update the target_changelog options in workflow_dispatch to match your project structure (e.g., service names in a monorepo)

Required Setup

  1. Get an Anthropic API Key:

    • Visit Anthropic Console
    • Create an API key
    • Add it to your repository secrets as ANTHROPIC_API_KEY
  2. Configure Repository Permissions:

    • Ensure your workflow has contents: write and pull-requests: write permissions
    • For private repositories, you may need to adjust branch protection rules

⚙️ Configuration

Inputs

Input Description Required Default
anthropic_api_key Anthropic API key for Claude AI -
changelog_path Path to changelog file CHANGELOG.md
target_name Target name for commit messages project
commit_range Number of commits to analyze (manual triggers) 10
version_increment Version increment type (auto, patch, minor, major) auto
github_token GitHub token for API operations ${{ github.token }}
base_branch Base branch for comparison (auto-detected)
skip_if_no_changes Skip if no relevant changes detected true
create_pr_suggestions Create GitHub PR suggestions true
auto_commit Auto-commit changes (non-PR events only) false

Outputs

Output Description
changelog_updated Whether changelog was updated (true/false)
changelog_content The generated changelog content
status Operation status (UPDATED, NO_UPDATE_NEEDED, ERROR, SKIPPED)
version_generated The version number that was generated
has_changes Whether there are actual changes in the changelog

📋 Advanced Examples

Multi-Project Monorepo

name: Update Changelogs

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened, ready_for_review]

jobs:
  update-changelogs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    strategy:
      matrix:
        project:
          - { name: "frontend", path: "packages/frontend/CHANGELOG.md" }
          - { name: "backend", path: "packages/backend/CHANGELOG.md" }
          - { name: "shared", path: "packages/shared/CHANGELOG.md" }

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.ref }}
          fetch-depth: 0

      - name: Generate Changelog for ${{ matrix.project.name }}
        uses: lukemun/context-ledger@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          changelog_path: ${{ matrix.project.path }}
          target_name: ${{ matrix.project.name }}

Release Automation

name: Release Changelog

on:
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      version_increment:
        description: "Version increment type"
        required: true
        default: "patch"
        type: choice
        options:
          - patch
          - minor
          - major

jobs:
  update-changelog:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate Release Changelog
        uses: lukemun/context-ledger@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          version_increment: ${{ github.event.inputs.version_increment || 'auto' }}
          auto_commit: true

Custom Configuration

- name: Generate Changelog with Custom Settings
  uses: lukemun/context-ledger@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    changelog_path: "docs/CHANGES.md"
    target_name: "api-service"
    commit_range: "20"
    version_increment: "minor"
    base_branch: "develop"
    skip_if_no_changes: false
    create_pr_suggestions: true

🧠 How It Works

  1. Trigger Detection: Runs on PR events, releases, or manual dispatch
  2. Loop Prevention: Checks for suggestion commits and changelog-only changes
  3. Change Analysis: Extracts PR commits, changed files, and git diffs
  4. AI Processing: Claude AI analyzes changes and generates categorized changelog entries
  5. Version Management: Automatically determines semantic version increments
  6. Changelog Updates: Simply appends new entries to the end of your changelog file
  7. GitHub Integration: Creates suggestions for one-click application in PRs

Changelog Generation

The action uses a simple marker-based approach:

  • Looks for the <!-- CONTEXT_LEDGER_MARKER --> marker at the end of your changelog
  • Inserts new entries just before this marker
  • The marker always stays at the bottom of the file
  • This ensures clean insertion points and prevents overwriting content

Commit Analysis

The action intelligently categorizes commits based on conventional commit patterns:

  • feat: → Added section, minor version increment
  • fix: → Fixed section, patch version increment
  • docs: → Changed section, patch version increment
  • BREAKING: → Major version increment
  • chore/style/refactor/test: → Technical Details section, patch increment

Version Strategy

Commit Types Version Increment
Breaking changes Major (1.0.0 → 2.0.0)
New features (feat:) Minor (1.0.0 → 1.1.0)
Bug fixes, docs, chores Patch (1.0.0 → 1.0.1)

🔧 Development

Project Structure

context-ledger/
├── action.yml              # Action definition
├── lib/
│   └── generate-changelog.js  # Core logic
├── package.json            # Dependencies
├── README.md              # Documentation
├── LICENSE                # MIT License
└── .github/
    └── workflows/
        └── test.yml       # CI/CD pipeline

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and test thoroughly
  4. Commit using conventional commits: git commit -m 'feat: add amazing feature'
  5. Push to the branch: git push origin feature/amazing-feature
  6. Open a Pull Request

Testing

# Install dependencies
npm install

# Run tests (when implemented)
npm test

# Test locally with act
act pull_request -s ANTHROPIC_API_KEY=your_test_key

🧪 Testing & Development

Dual Workflow Approach

Context Ledger provides two workflows for maximum flexibility:

  1. Production Workflow (changelog.yml) - Uses the published version (@v1)

    • Stable, tested version
    • What your users will experience
    • Runs automatically on PRs and releases
  2. Local Workflow (changelog-local.yml) - Uses the PR's code (./)

    • Test changes before merging
    • Verify fixes work as expected
    • Same functionality, different source

Release Process

When ready to release a new version:

# 1. Ensure CHANGELOG.md has the new version
# 2. Merge your PR to main
# 3. Run the release script
./scripts/release.sh

This will:

  • Create a new version tag (e.g., v1.0.19)
  • Update the floating major tag (e.g., v1)
  • Push both tags to GitHub

🛡️ Security

  • API Key Security: Store your Anthropic API key in GitHub Secrets, never in code
  • Permissions: Use minimal required permissions (contents: write, pull-requests: write)
  • Token Scope: Action uses the provided GitHub token with repository scope only

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Support

🙏 Acknowledgments

  • Anthropic for the powerful Claude AI API
  • GitHub Actions for the automation platform
  • The open source community for inspiration and feedback

Made with ❤️ by Luke Munro

About

AI-powered GitHub Action that generates PR suggestions to changelog suitable for LLM retrieval, easy engineer onboarding, and sales enablement.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 3

  •  
  •  
  •