Configuration Guide

Changesmith can be configured at the project level via .changesmith.json in your repository root.

Creating a Config File

The easiest way is to run:

changesmith init

This creates a .changesmith.json with sensible defaults.

Config Options

defaultBranch

Type: string Default: "main"

The default branch to use when determining commit ranges.

{
  "defaultBranch": "develop"
}

excludeTypes

Type: string[] Default: ["chore", "style", "ci"]

Conventional commit types to exclude from the changelog.

{
  "excludeTypes": ["chore", "style", "ci", "test", "build"]
}

Available types:

• feat — New features
• fix — Bug fixes
• docs — Documentation changes
• style — Formatting, white-space, etc.
• refactor — Code restructuring
• perf — Performance improvements
• test — Adding/updating tests
• build — Build system changes
• ci — CI/CD changes
• chore — Maintenance tasks
• revert — Reverted commits

Tip: Keep feat and fix — they're usually what users care about.

includeScopes

Type: string[] Default: [] (all scopes included)

Only include commits with these conventional commit scopes. An empty array means all scopes are included.

{
  "includeScopes": ["api", "web", "core"]
}

When set, only commits like feat(api): ... or fix(web): ... will appear in the changelog. Commits without a scope or with a non-matching scope are excluded.

excludeScopes

Type: string[] Default: []

Exclude commits with these conventional commit scopes from the changelog.

{
  "excludeScopes": ["deps", "internal"]
}

Commits like chore(deps): bump lodash or refactor(internal): ... will be excluded. If both includeScopes and excludeScopes are set, includeScopes takes precedence — a commit must match an included scope AND not match an excluded scope.

styleGuide

Type: string Default: ""

A style guide name that influences the tone and format of generated changelogs. When set, the AI uses the named style as a baseline for generation.

{
  "styleGuide": "keep-a-changelog"
}

customPrompt

Type: string Default: undefined

Additional instructions for the AI when generating changelogs.

{
  "customPrompt": "Focus on user-facing changes. Use simple language that non-technical users can understand. Keep each item to one sentence."
}

Example prompts:

For technical audiences:

{
  "customPrompt": "Include technical details. Mention affected APIs and breaking changes prominently."
}

For end users:

{
  "customPrompt": "Write for non-technical users. Focus on benefits and new capabilities, not implementation details."
}

For specific formatting:

{
  "customPrompt": "Use emoji prefixes: 🚀 for features, 🐛 for fixes, ⚡ for performance."
}

Example Configurations

Minimal (Defaults)

{}

Standard Project

{
  "defaultBranch": "main",
  "excludeTypes": ["chore", "style", "ci", "test"]
}

User-Facing Product

{
  "defaultBranch": "main",
  "excludeTypes": ["chore", "style", "ci", "test", "build", "refactor"],
  "customPrompt": "Write for end users, not developers. Focus on what changed in the product experience. Avoid technical jargon."
}

Technical Library

{
  "defaultBranch": "main",
  "excludeTypes": ["style", "ci"],
  "customPrompt": "This is a developer library. Include breaking changes prominently. Mention affected function names and migration steps."
}

Enterprise/Compliance

{
  "defaultBranch": "main",
  "excludeTypes": [],
  "customPrompt": "Include all changes for audit purposes. Note the commit hash and author for each change."
}

Environment Variables

These environment variables affect CLI behavior:

| Variable | Description | | --- | --- | | CHANGESMITH_TOKEN | Auth token (no login needed when set) | | CHANGESMITH_API_URL | API endpoint override |

Environment variables take precedence over stored configuration. Empty or whitespace-only values are ignored.

Web Dashboard Settings

Additional settings are available in the Changesmith web dashboard:

• Auto-generate on release — Trigger generation when a GitHub release is created
• Auto-generate on tag — Trigger generation when a tag is pushed
• Email notifications — Get notified when drafts are ready for review
• Style template — Pre-defined style templates (Keep a Changelog, Semantic, etc.)

These settings sync with your repository but aren't stored in .changesmith.json.