Changesmith
Log inGet Started

Frequently Asked Questions

General

What is Changesmith?

Changesmith is an AI-powered tool that generates changelogs from your git history. Instead of manually writing release notes, Changesmith analyzes your commits, pull requests, and issues to create polished, user-friendly changelogs automatically.

How is this different from git log?

git log shows raw commit messages like "fix: resolve issue #423" — that means nothing to users. Changesmith uses AI to:

  1. Read the actual code changes (diffs)
  2. Understand PR descriptions and linked issues
  3. Translate technical changes into human language
  4. Match your existing changelog style

The result is release notes that sound like you wrote them, without the tedious work.

Do I need to use conventional commits (feat:, fix:, etc.)?

No. While conventional commit prefixes help with categorization, Changesmith's AI analyzes the actual changes — not just message formats. Write "Add dark mode" or "feat: add dark mode" — both work great.

That said, clear commit messages produce better results. "Fix bug" is harder to interpret than "Fix login redirect issue on Safari."

Does Changesmith read my source code?

Changesmith reads commit diffs to understand what changed. It doesn't store your code or use it for training. We only retain the metadata needed to generate changelogs (commit messages, PR descriptions, etc.).

Is there a free tier?

Yes! The free plan includes:

  • Unlimited repositories
  • 3 changelog generations per month
  • All core features (AI generation, editor, GitHub publishing)

No credit card required.

Setup & Integration

Which version control hosts are supported?

Currently: GitHub only.

GitLab and Bitbucket support are on the roadmap.

What GitHub permissions does Changesmith need?

  • Read: Repository contents, commits, issues, pull requests
  • Write: Releases (for publishing)

We never modify your source code, branches, or settings.

Can I use Changesmith with private repositories?

Yes, Changesmith works with both public and private repositories. Your code and commit data remain secure.

Does Changesmith work with monorepos?

Yes, but with some considerations:

  • Each package/app should have its own version tags
  • You can filter commits by path in the web dashboard
  • The CLI supports custom commit ranges

Full monorepo support (per-package changelogs) is coming soon.

Usage

How do I trigger changelog generation?

Web Dashboard:

  • Click "Generate Changelog" for any connected repository
  • Or enable auto-generation on release/tag creation

CLI:

# Via GitHub App (recommended when connected)
changesmith github v1.0.0

# From local git history (no GitHub App needed)
changesmith local v1.0.0

GitHub Webhook (automatic):

  • When you create a release in GitHub
  • When you push a tag (if enabled)

What's the difference between github and local?

The github command uses the Changesmith GitHub App to read commits, PRs, and issues directly from GitHub. It provides the richest context and supports the --release flag to publish GitHub Releases.

The local command reads commits and diffs from your local git repository and sends them to the API. It doesn't require the GitHub App and works with unpushed commits, but has size limits (500 commits, 3 MB diffs) and no PR/issue context.

See the CLI Reference for a full comparison.

Can I edit the generated changelog?

Absolutely. The generated text is a draft. Use the built-in editor in the dashboard to refine it before publishing. You can:

  • Edit text
  • Reorder sections
  • Add or remove items
  • Change formatting

Where does Changesmith publish?

GitHub Releases — One-click publish from the dashboard, or --release flag from the CLI.

CHANGELOG.md — Use -w to prepend to your CHANGELOG.md file directly, or the dashboard's CHANGELOG.md sync feature.

How does style matching work?

If you have an existing CHANGELOG.md, Changesmith analyzes it to learn:

  • Heading format (## vs ###, etc.)
  • Section names (Added, Changed, Fixed, etc.)
  • Writing tone (formal vs casual)
  • Bullet point style
  • How you describe features vs fixes

The more history you have, the better it matches. The local command reads your existing CHANGELOG.md automatically; the github command uses server-side style analysis.

Billing & Pricing

What counts as a "generation"?

Each time the AI generates a changelog draft, that's one generation. Editing and publishing don't count.

Regenerating the same version uses another generation.

What happens if I exceed my monthly limit?

You won't lose access. Instead:

  • Free users: Wait for the next month or upgrade
  • Pro and Business users have unlimited generations

Can I switch plans mid-month?

Yes, changes take effect immediately. When upgrading, you're charged a prorated amount for the remainder of the month.

Do unused generations roll over?

No, generation quotas reset monthly.

CLI

Can I use the CLI in CI/CD?

Yes! Set CHANGESMITH_TOKEN as a secret environment variable:

# GitHub Actions example
- name: Generate Changelog
  env:
    CHANGESMITH_TOKEN: ${{ secrets.CHANGESMITH_TOKEN }}
  run: npx @changesmith/cli github ${{ github.ref_name }} -w --release

For repositories without the GitHub App, use local instead:

run: npx @changesmith/cli local ${{ github.ref_name }} -w

Generate a token from the dashboard.

Can I generate and publish a release in one step?

Yes, use the --release flag with the github command:

changesmith github v1.2.0 --release

This generates the changelog and publishes it as a GitHub Release. Combine with -w to also update CHANGELOG.md:

changesmith github v1.2.0 -w --release

Why can't I use --release with local?

The --release flag creates a GitHub Release through the Changesmith GitHub App. The local command doesn't use the GitHub App, so it has no way to create the release on your behalf. To publish a release from a locally generated changelog, use the web dashboard or create the release manually on GitHub.

Does the CLI work offline?

The init and status commands work offline. Generation requires an internet connection to reach the Changesmith API.

What if my repository isn't connected to the GitHub App?

Use changesmith local instead of changesmith github. It reads commits and diffs from your local git history and sends them to the API for generation. No GitHub App installation required.

Can I use Changesmith on a fork or a repo without tags?

Yes. Use changesmith autotag to create tags from version bumps in the commit history, then generate changelogs as normal:

# See what tags would be created from version bumps
changesmith autotag --dry-run

# Create the tags
changesmith autotag

# Now generate changelogs
changesmith local v1.2.0 -w
changesmith local v1.1.0 -w
changesmith local v1.0.0 -w

The autotag command scans package.json, Cargo.toml, and pyproject.toml for version changes and creates a tag at each version-bump commit.

Can I preview which commits will be included?

Yes, use the --dry-run flag with the local command:

changesmith local v1.2.0 --dry-run

This lists each commit (SHA, date, message) without calling the API or generating anything. It's useful for verifying the commit range is correct before spending a generation.

Privacy & Security

Is my code safe?

Yes. Changesmith:

  • Never stores your source code
  • Reads only commit metadata and diffs
  • Encrypts all data in transit and at rest
  • Never uses your data for AI training

For more details, see the Security Architecture page.

Can I self-host Changesmith?

Not currently. We're focused on the cloud offering, but may consider enterprise self-hosted options in the future.

Still have questions?