communique

AI-generated release notes for people who read release notes.

communique turns your git history, pull requests, and repository context into polished release notes. It can print notes locally, update CHANGELOG.md, or publish directly to a GitHub Release.

Sponsors

Install

Install with mise:

mise use communique

Or install with Cargo:

cargo install communique

Pre-built binaries for macOS, Linux, and Windows are available on the GitHub releases page.

Agent skill

Packslip releases provide a Communique skill for release ranges, draft review, changelogs, and publishing. Install a release that includes it and link the matching skill into your agent's directory:

mise use packslip:github.com/jdx/communique
mise skills sync --dir .agents/skills

The generated link is local to your installation; keep it out of version control and run sync again after changing tool versions.

Setup

communique needs an LLM API key. Claude models use Anthropic; other models use the OpenAI-compatible provider path.

# Default Claude models
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI-compatible models
export OPENAI_API_KEY="sk-..."

To add custom headers to OpenAI-compatible requests, set OPENAI_CUSTOM_HEADERS to a JSON object with string values. For example, to send the Copilot integration header:

export OPENAI_CUSTOM_HEADERS='{"copilot-integration-id":"copilot-developer-cli"}'

You can also pass repeatable --header flags:

communique generate v1.2.0 --provider openai --model gpt-4.1 \
  --header 'copilot-integration-id: copilot-developer-cli'

CLI headers override OPENAI_CUSTOM_HEADERS values with the same name (case-insensitive); the last repeated header wins. Custom headers override default request headers, including Authorization. An unset or empty value adds no headers; invalid JSON or HTTP headers cause an error before the request is sent. This setting only applies to the OpenAI provider.

For a custom OpenAI-compatible endpoint, set OPENAI_BASE_URL:

export OPENAI_BASE_URL="http://localhost:11434/v1"
communique generate v1.2.0 --model llama3

This sends OpenAI-compatible requests to the local endpoint. --base-url takes precedence over defaults.base_url in communique.toml, which takes precedence over OPENAI_BASE_URL. Empty environment values are ignored, and this variable does not affect the Anthropic provider.

GitHub context and GitHub Release publishing also need a token:

export GITHUB_TOKEN="$(gh auth token)"

Initialize a config file in your repository:

communique init

This creates communique.toml, where you can set the default model, repository, style instructions, and project context.

Generate Release Notes

Generate notes for a tag:

communique generate v1.2.0

communique automatically detects the previous tag. You can provide it explicitly when needed:

communique generate v1.2.0 v1.1.0

Preview without publishing or verifying links:

communique generate v1.2.0 --dry-run

Write the output to a file:

communique generate v1.2.0 --output RELEASE_NOTES.md

Review Before Publishing

Save an editable draft, a coverage report, and an upgrade guide:

communique generate v1.2.0 --draft release.json --review-report review.md --migration-guide upgrade.md
# Edit release.json, then preview and publish the edited content.
communique publish release.json --dry-run
communique publish release.json

Publishing a saved draft does not invoke the model again. Use --preserve-sections when generating to keep hand-written release text outside communiqué's marked section. Configuration covers package scopes, tag patterns, release channels, and editorial label rules.

Update GitHub Releases

Publish generated notes to an existing GitHub Release:

communique generate v1.2.0 --github-release

communique reads commits and pull requests, lets the model inspect relevant files and diffs, verifies links, then replaces the GitHub Release body with the finished notes.

Update CHANGELOG.md

Add or replace the version entry in CHANGELOG.md:

communique generate v1.2.0 --changelog

For release PRs, this keeps the [Unreleased] section in place and inserts the new version entry immediately below it.

Use concise output when you do not want a full release narrative:

communique generate v1.2.0 --concise

You can combine concise output with changelog updates:

communique generate v1.2.0 --concise --changelog

Configuration

communique.toml supports project-level defaults and writing guidance:

context = """
This is a Rust CLI used by platform engineers.
Call out breaking changes and migration steps clearly.
"""

system_extra = """
Write in a direct, practical tone.
Avoid marketing language.
"""

[defaults]
model = "claude-opus-5-5"
repo = "owner/repo"
max_tokens = 16384

CLI flags override config defaults.

GitHub Actions

Use fetch-depth: 0 so communique can compare tags:

name: Release Notes

on:
  push:
    tags:
      - v[0-9]+.*

permissions:
  contents: write

jobs:
  release-notes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: jdx/mise-action@v3
      - run: mise use communique
      - name: Generate release notes
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: communique generate "${{ github.ref_name }}" --github-release

See the GitHub Actions guide for release-plz examples and release PR workflows.

Common Options

communique generate v1.2.0 --repo owner/repo
communique generate v1.2.0 --model claude-opus-5-5
communique generate v1.2.0 --provider openai --base-url https://api.example.com/v1
communique generate v1.2.0 --quiet
communique generate v1.2.0 --verbose

Troubleshooting

If PR details are missing, confirm GITHUB_TOKEN is set and can read the repository.

If generation fails because tags cannot be compared, fetch full history and tags:

git fetch --tags --unshallow

If CHANGELOG.md updates fail, make sure the file has an ## [Unreleased] or ## Unreleased section.

Documentation

• Getting started
• Configuration
• GitHub Actions
• CLI reference