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
.
-
Add secret: In GitHub → Settings → Secrets and variables → Actions → New repository secret
- Name:
ANTHROPIC_API_KEY
- Value: your Anthropic API key
- Name:
-
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
.
- 🤖 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
- 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.
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
.
Follow these steps to set up Context Ledger for multi-project repositories:
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' }}
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
- Sign up at Anthropic Console
- Create a new API key
- Copy the key (starts with
sk-ant-
)
- Go to your repository on GitHub
- Click Settings → Secrets and variables → Actions
- Click New repository secret
- Name:
ANTHROPIC_API_KEY
- Value: Your API key from Step 3
- Click Add secret
git add .github/workflows/changelog.yml CHANGELOG.md
git commit -m "feat: add Context Ledger for automated changelog generation"
git push origin main
Create a new pull request and watch Context Ledger analyze your changes and suggest changelog entries!
- 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 inworkflow_dispatch
to match your project structure (e.g., service names in a monorepo)
-
Get an Anthropic API Key:
- Visit Anthropic Console
- Create an API key
- Add it to your repository secrets as
ANTHROPIC_API_KEY
-
Configure Repository Permissions:
- Ensure your workflow has
contents: write
andpull-requests: write
permissions - For private repositories, you may need to adjust branch protection rules
- Ensure your workflow has
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 |
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 |
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 }}
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
- 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
- Trigger Detection: Runs on PR events, releases, or manual dispatch
- Loop Prevention: Checks for suggestion commits and changelog-only changes
- Change Analysis: Extracts PR commits, changed files, and git diffs
- AI Processing: Claude AI analyzes changes and generates categorized changelog entries
- Version Management: Automatically determines semantic version increments
- Changelog Updates: Simply appends new entries to the end of your changelog file
- GitHub Integration: Creates suggestions for one-click application in PRs
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
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
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) |
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
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes and test thoroughly
- Commit using conventional commits:
git commit -m 'feat: add amazing feature'
- Push to the branch:
git push origin feature/amazing-feature
- Open a Pull Request
# Install dependencies
npm install
# Run tests (when implemented)
npm test
# Test locally with act
act pull_request -s ANTHROPIC_API_KEY=your_test_key
Context Ledger provides two workflows for maximum flexibility:
-
Production Workflow (
changelog.yml
) - Uses the published version (@v1
)- Stable, tested version
- What your users will experience
- Runs automatically on PRs and releases
-
Local Workflow (
changelog-local.yml
) - Uses the PR's code (./
)- Test changes before merging
- Verify fixes work as expected
- Same functionality, different source
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
- 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
This project is licensed under the MIT License - see the LICENSE file for details.
- 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