Configuration - HelixCommit

Overview

HelixCommit offers flexible configuration through configuration files, command-line flags, and environment variables. You can customize how commits are processed, what gets included in release notes, and how output is formatted.

Configuration methods

Configuration files

Store project defaults in .helixcommit.toml or .helixcommit.yaml. Best for team-wide settings.

Command-line flags

Pass options directly when running commands. Best for one-off customizations and testing.

Environment variables

Set variables in your shell or CI/CD environment. Ideal for credentials and secrets.

Configuration precedence

When the same option is set in multiple places, HelixCommit uses this precedence (highest to lowest):

Command-line flags - Always take priority
Configuration file - Project defaults from .helixcommit.toml or .helixcommit.yaml
Built-in defaults - Fallback values

Configuration files

HelixCommit looks for configuration files in your repository root in this order:

.helixcommit.toml (TOML format)
.helixcommit.yaml (YAML format)

The first file found is used. Configuration files are optional - HelixCommit works without them.

Custom config file location

Use the --config flag to specify a custom config file location instead of the default discovery:

# Use a specific config file
helixcommit generate --config /path/to/my-config.toml

# Use project-specific configs
helixcommit generate --config configs/release.yaml

# Use environment-specific configs
helixcommit generate --config ~/.helixcommit/production.toml

The --config flag is available on both generate and generate-commit commands.

Example: Multiple project configurations

Maintain different configurations for different release types:

# configs/major-release.toml
helixcommit generate --config configs/major-release.toml --unreleased

# configs/patch-release.toml
helixcommit generate --config configs/patch-release.toml --unreleased

Example: Shared team configuration

Store team-wide settings in a central location:

# Use shared config from home directory
helixcommit generate --config ~/.helixcommit/team-config.yaml

# Or from a network location
helixcommit generate --config /shared/configs/helixcommit.toml

Example: CI/CD with custom configs

Use different configs per CI environment:

# GitHub Actions example
- name: Generate release notes (staging)
  run: helixcommit generate --config .ci/staging-config.toml --unreleased

- name: Generate release notes (production)
  run: helixcommit generate --config .ci/production-config.toml --unreleased

Template paths in custom config files are resolved relative to the config file’s location, not the repository root.

TOML format
YAML format

Create a .helixcommit.toml file in your repository root:

# .helixcommit.toml - HelixCommit configuration

[generate]
format = "markdown"           # Output format: markdown, html, text, json
include_scopes = true         # Show commit scopes in output
no_merge_commits = false      # Exclude merge commits
no_prs = false                # Skip PR/MR lookups
fail_on_empty = false         # Exit with error if no commits found

# Advanced filtering (v1.2+)
include_types = []            # Only include these commit types (e.g., ["feat", "fix"])
exclude_scopes = []           # Exclude commits with these scopes (e.g., ["deps", "ci"])
author_filter = ""            # Regex to filter by author name or email

[ai]
enabled = false               # Enable AI-powered summaries (--use-llm)
provider = "openrouter"       # AI provider: openai or openrouter
openai_model = "gpt-4o-mini"
openrouter_model = "x-ai/grok-4.1-fast:free"
include_diffs = false         # Include diffs for better AI context
domain_scope = "software release notes"
expert_roles = ["Product Manager", "Tech Lead", "QA Engineer"]
rag_backend = "simple"        # RAG backend: simple or chroma

Create a .helixcommit.yaml file in your repository root:

# .helixcommit.yaml - HelixCommit configuration

generate:
  format: markdown            # Output format: markdown, html, text, json
  include_scopes: true        # Show commit scopes in output
  no_merge_commits: false     # Exclude merge commits
  no_prs: false               # Skip PR/MR lookups
  fail_on_empty: false        # Exit with error if no commits found

  # Advanced filtering (v1.2+)
  include_types: []           # Only include these commit types
  exclude_scopes: []          # Exclude commits with these scopes
  author_filter: ""           # Regex to filter by author name or email

ai:
  enabled: false              # Enable AI-powered summaries (--use-llm)
  provider: openrouter        # AI provider: openai or openrouter
  openai_model: gpt-4o-mini
  openrouter_model: x-ai/grok-4.1-fast:free
  include_diffs: false        # Include diffs for better AI context
  domain_scope: software release notes
  expert_roles:
    - Product Manager
    - Tech Lead
    - QA Engineer
  rag_backend: simple         # RAG backend: simple or chroma

Never store API keys or tokens in configuration files. Use environment variables for sensitive credentials like OPENAI_API_KEY, GITHUB_TOKEN, etc.

Environment variable expansion

Configuration files support environment variable expansion using the ${VAR} syntax. This allows you to reference environment variables directly in your config files, making configurations more portable across different environments.

Basic syntax
Default values

Use ${VAR_NAME} to reference an environment variable:

# .helixcommit.toml
[ai]
enabled = true
openai_model = "${AI_MODEL}"
domain_scope = "${PROJECT_DOMAIN}"

# .helixcommit.yaml
ai:
  enabled: true
  openai_model: "${AI_MODEL}"
  domain_scope: "${PROJECT_DOMAIN}"

Set the variables before running:

export AI_MODEL=gpt-4o
export PROJECT_DOMAIN=e-commerce
helixcommit generate --unreleased

Use ${VAR:-default} to provide a fallback value when the variable is not set:

# .helixcommit.toml
[ai]
enabled = true
openai_model = "${AI_MODEL:-gpt-4o-mini}"
domain_scope = "${PROJECT_DOMAIN:-software release notes}"

# .helixcommit.yaml
ai:
  enabled: true
  openai_model: "${AI_MODEL:-gpt-4o-mini}"
  domain_scope: "${PROJECT_DOMAIN:-software release notes}"

If AI_MODEL is not set, gpt-4o-mini will be used instead.

Example: Environment-specific configurations

Use environment variables to switch between development and production settings:

# .helixcommit.toml
[generate]
format = "${OUTPUT_FORMAT:-markdown}"

[ai]
enabled = true
provider = "${AI_PROVIDER:-openrouter}"
openai_model = "${OPENAI_MODEL:-gpt-4o-mini}"
openrouter_model = "${OPENROUTER_MODEL:-x-ai/grok-4.1-fast:free}"
domain_scope = "${DOMAIN_SCOPE:-software release notes}"

Then configure per environment:

# Development
export AI_PROVIDER=openrouter
export OPENROUTER_MODEL=x-ai/grok-4.1-fast:free

# Production
export AI_PROVIDER=openai
export OPENAI_MODEL=gpt-4o

Example: Dynamic template paths

Reference template directories via environment variables:

# .helixcommit.toml
[templates]
markdown = "${TEMPLATE_DIR:-templates}/changelog.md.j2"
html = "${TEMPLATE_DIR:-templates}/changelog.html.j2"

Example: Team-specific roles

Configure expert roles per team member or CI environment:

# .helixcommit.toml
[ai]
enabled = true
expert_roles = ["${PRIMARY_ROLE:-Product Manager}", "${SECONDARY_ROLE:-Tech Lead}"]

If an environment variable is not set and no default is provided, the reference (e.g., ${UNDEFINED_VAR}) is kept as-is in the config value.

Environment variable expansion is for non-sensitive configuration values like model names, domains, and paths. Never use this feature for API keys or tokens - those should always be set as environment variables directly and accessed by the application.

Configuration reference

[generate] section

Option	Type	Default	Description
`format`	string	`"markdown"`	Output format: `markdown`, `html`, `text`, or `json`
`include_scopes`	boolean	`true`	Show commit scopes (e.g., `feat(api)`)
`no_merge_commits`	boolean	`false`	Exclude merge commits from output
`no_prs`	boolean	`false`	Skip GitHub/GitLab/Bitbucket PR lookups
`fail_on_empty`	boolean	`false`	Exit with code 1 if no commits found
`include_types`	string[]	`[]`	Only include commits of these types (e.g., `["feat", "fix"]`)
`exclude_scopes`	string[]	`[]`	Exclude commits with these scopes (e.g., `["deps", "ci"]`)
`author_filter`	string	`null`	Regex pattern to filter commits by author name or email

[ai] section

Option	Type	Default	Description
`enabled`	boolean	`false`	Enable AI-powered summaries
`provider`	string	`"openrouter"`	AI provider: `openai` or `openrouter`
`openai_model`	string	`"gpt-4o-mini"`	OpenAI model to use
`openrouter_model`	string	`"x-ai/grok-4.1-fast:free"`	OpenRouter model to use
`include_diffs`	boolean	`false`	Include commit diffs for AI context
`domain_scope`	string	`null`	Domain context for AI prompts
`expert_roles`	string[]	`[]`	Expert roles for multi-perspective analysis
`rag_backend`	string	`"simple"`	RAG backend: `simple` or `chroma`

Example configurations

Minimal AI-enabled setup

# .helixcommit.toml
[ai]
enabled = true
provider = "openrouter"

Then set your API key:

export OPENROUTER_API_KEY=sk-or-...
helixcommit generate --unreleased

CI/CD optimized

# .helixcommit.toml
[generate]
format = "markdown"
no_merge_commits = true
fail_on_empty = true

Full-featured with AI

# .helixcommit.toml
[generate]
format = "markdown"
include_scopes = true
no_merge_commits = true

[ai]
enabled = true
provider = "openai"
openai_model = "gpt-4o-mini"
include_diffs = true
domain_scope = "software release notes"
expert_roles = ["Product Manager", "Tech Lead", "Security Engineer"]

With advanced filtering

# .helixcommit.toml
[generate]
format = "markdown"
no_merge_commits = true

# Only include features, fixes, and performance improvements
include_types = ["feat", "fix", "perf"]

# Exclude dependency updates and CI changes
exclude_scopes = ["deps", "ci"]

# Only include commits from team members
author_filter = ".*@mycompany\\.com"

# .helixcommit.yaml equivalent
generate:
  format: markdown
  no_merge_commits: true
  include_types:
    - feat
    - fix
    - perf
  exclude_scopes:
    - deps
    - ci
  author_filter: ".*@mycompany\\.com"

Core configuration areas

Commit range selection

Control which commits are included in your release notes.

Tag-based ranges
Commit-based ranges
Date-based ranges

Use semantic version tags to define ranges:

# Between two specific tags
helixcommit generate \
  --since-tag v1.2.0 \
  --until-tag v1.2.1

# From tag to HEAD (unreleased)
helixcommit generate \
  --since-tag v1.2.1 \
  --until HEAD

The --unreleased flag automatically uses the latest tag as the starting point.

Use commit SHAs or branch names:

# Specific commit range
gitreleasegen generate \
  --since abc123def \
  --until 456ghi789

# From branch to another
gitreleasegen generate \
  --since main \
  --until feature-branch

Use date expressions:

# Changes in the last week
gitreleasegen generate \
  --since "7 days ago"

# Changes since specific date
gitreleasegen generate \
  --since "2024-01-01" \
  --until "2024-06-30"

Date expressions use Git’s date parsing, which supports relative dates like “1 week ago” and absolute dates like “2024-01-01”.

Output formatting

Customize how release notes are formatted and where they’re saved.

format

string

default:"markdown"

Choose the output format that fits your publishing workflow.Markdown - Perfect for GitHub releases and documentation sites

helixcommit generate --format markdown --out RELEASE_NOTES.md

HTML - Ready for embedding in websites

helixcommit generate --format html --out changelog.html

Text - Plain text for email notifications or chat

helixcommit generate --format text --out changes.txt

JSON - Machine-readable for programmatic use

helixcommit generate --format json --out changelog.json

output destination

string

Control where output is written.Standard output (default)

gitreleasegen generate --format markdown

File output

gitreleasegen generate --out /path/to/output.md

Parent directories are created automatically if they don’t exist.

Filtering commits

Fine-tune which commits appear in your release notes.

Include or exclude merge commits

# Exclude merge commits (cleaner output)
gitreleasegen generate --no-merge-commits

# Include merge commits (default)
gitreleasegen generate

Merge commits often duplicate information. Excluding them typically produces cleaner release notes.

Limit commit count

# Process only the last 50 commits
gitreleasegen generate --max-items 50

Useful for testing or when you only need recent changes.

Show or hide commit scopes

# With scopes (default)
gitreleasegen generate --include-scopes
# Output: "**api**: Add authentication endpoint"

# Without scopes
gitreleasegen generate --no-include-scopes
# Output: "Add authentication endpoint"

Scopes are extracted from Conventional Commits format: feat(api): message

GitHub integration

Configure how GitReleaseGen interacts with GitHub’s API.

Authentication

Create a GitHub token

Visit github.com/settings/tokens and create a personal access token.For public repositories: No special permissions neededFor private repositories: Select the repo scope

Set the token

export GITHUB_TOKEN=ghp_your_token_here

# Use in commands
gitreleasegen generate --unreleased

Never commit tokens to version control. Use environment variables or CI/CD secrets.

Rate limiting and retries

GitReleaseGen handles GitHub API rate limits automatically with exponential backoff.

GITRELEASEGEN_GH_MAX_RETRIES

integer

default:"3"

Maximum number of retry attempts for failed requests.

export GITRELEASEGEN_GH_MAX_RETRIES=5

GITRELEASEGEN_GH_BACKOFF_BASE_SEC

float

default:"0.5"

Initial delay between retries in seconds.

export GITRELEASEGEN_GH_BACKOFF_BASE_SEC=1.0

GITRELEASEGEN_GH_BACKOFF_CAP_SEC

float

default:"8"

Maximum delay between retries in seconds.

export GITRELEASEGEN_GH_BACKOFF_CAP_SEC=16

Caching

Reduce API calls and improve performance with caching.

GITRELEASEGEN_GH_CACHE

boolean

default:"false"

Enable persistent caching of GitHub API responses.

export GITRELEASEGEN_GH_CACHE=1
gitreleasegen generate --unreleased

Valid values: 1, true, yes, on

GITRELEASEGEN_GH_CACHE_DIR

path

default:".gitreleasegen-cache/github"

Directory where cache files are stored.

export GITRELEASEGEN_GH_CACHE_DIR=.cache/gh-api

GITRELEASEGEN_GH_CACHE_TTL_MINUTES

integer

default:"10"

How long cache entries remain valid in minutes.

export GITRELEASEGEN_GH_CACHE_TTL_MINUTES=30

Enable caching in CI/CD environments to speed up repeated runs and reduce API usage.

Skip GitHub integration

Work offline or skip PR lookups:

helixcommit generate --unreleased --no-prs

Using --no-prs means no GitHub API calls are made. Perfect for offline work or when PR metadata isn’t needed.

GitLab integration

HelixCommit automatically detects GitLab repositories (including self-hosted instances) and enriches release notes with merge request data.

Authentication

export GITLAB_TOKEN=glpat-your_token_here

helixcommit generate --unreleased

Required permissions: read_api and read_repository for private projects.

For more details, see the GitLab integration guide.

Bitbucket integration

HelixCommit automatically detects Bitbucket Cloud repositories and enriches release notes with pull request data.

Authentication

export BITBUCKET_TOKEN=your_app_password_here

helixcommit generate --unreleased

Required permissions: Repositories: Read, Pull requests: Read

For more details, see the Bitbucket integration guide.

AI configuration

Configure AI-powered summarization features.

Provider selection

OpenAI
OpenRouter

export OPENAI_API_KEY=sk-...

gitreleasegen generate \
  --unreleased \
  --use-llm \
  --openai-model gpt-4o-mini

Recommended models:

gpt-4o-mini - Fast and cost-effective (recommended)
gpt-4o - Most capable
gpt-3.5-turbo - Budget option

Get your API key at platform.openai.com/api-keys

export OPENROUTER_API_KEY=sk-or-...

gitreleasegen generate \
  --unreleased \
  --use-llm \
  --llm-provider openrouter \
  --openrouter-model meta-llama/llama-3.1-8b-instruct:free

Popular models:

meta-llama/llama-3.1-8b-instruct:free - Free tier
anthropic/claude-3-haiku - Fast and capable
google/gemini-pro - Good balance

Get your API key at openrouter.ai

OpenRouter provides access to many AI models with a single API key, including free options.

Summary caching

AI summaries are cached to minimize token usage and costs.

# Use custom cache location
gitreleasegen generate \
  --use-llm \
  --summary-cache .cache/ai-summaries.json

# Default cache location
# .gitreleasegen-cache/summaries.json

Delete the cache file to regenerate all summaries with updated prompts or settings.

Prompt engineering

Customize AI behavior with advanced options:

domain-scope

string

Set the domain context for better AI summaries.

gitreleasegen generate \
  --use-llm \
  --domain-scope "software release notes"

Examples: "conservation", "healthcare", "finance", "e-commerce"

expert-role

string[]

Define expert roles for multi-perspective analysis.

gitreleasegen generate \
  --use-llm \
  --expert-role "Product Manager" \
  --expert-role "Tech Lead" \
  --expert-role "Security Engineer"

Default roles: Product Manager, Tech Lead, QA Engineer

rag-backend

string

default:"simple"

Choose the retrieval backend for context.

# Simple keyword matching (default)
gitreleasegen generate --use-llm --rag-backend simple

# Vector-based retrieval (requires chromadb)
pip install chromadb
gitreleasegen generate --use-llm --rag-backend chroma

Example configurations

Minimal offline setup

Generate release notes with no external dependencies:

gitreleasegen generate \
  --unreleased \
  --no-prs \
  --no-merge-commits \
  --format markdown \
  --out RELEASE_NOTES.md

Perfect for local development or air-gapped environments.

Full-featured with AI

Maximum enrichment with AI summaries and GitHub integration:

export GITHUB_TOKEN=ghp_...
export OPENAI_API_KEY=sk-...
export GITRELEASEGEN_GH_CACHE=1

gitreleasegen generate \
  --unreleased \
  --use-llm \
  --openai-model gpt-4o-mini \
  --domain-scope "software release notes" \
  --format markdown \
  --out RELEASE_NOTES.md

CI/CD optimized

Fast generation for automated pipelines:

#!/bin/bash
export GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}
export GITRELEASEGEN_GH_CACHE=1
export GITRELEASEGEN_GH_CACHE_TTL_MINUTES=60

gitreleasegen generate \
  --since-tag $PREVIOUS_TAG \
  --until-tag $CURRENT_TAG \
  --no-merge-commits \
  --format markdown \
  --out RELEASE_NOTES.md \
  --fail-on-empty

Team workflow

Balanced configuration for team use:

# .env file
export GITHUB_TOKEN=ghp_...
export GITRELEASEGEN_GH_CACHE=1
export GITRELEASEGEN_GH_MAX_RETRIES=5

# Generate command
gitreleasegen generate \
  --unreleased \
  --include-scopes \
  --format markdown

Custom templates

GitReleaseGen uses formatters to render output. You can customize the look and feel by modifying templates.

Template locations

Templates are located in the GitReleaseGen package:

gitreleasegen/formatters/
├── markdown.py    # Markdown formatter
├── html.py        # HTML formatter
└── text.py        # Text formatter

Creating custom formatters

Copy an existing formatter

cp src/gitreleasegen/formatters/markdown.py my_formatter.py

Modify the template

Edit the rendering logic to match your needs. Formatters use Jinja2 templates for rendering.

Use programmatically

from gitreleasegen.changelog import ChangelogBuilder
import my_formatter

builder = ChangelogBuilder()
changelog = builder.build(...)
output = my_formatter.render(changelog)

For more details on programmatic usage, see the Python API reference.

Environment file

Create a .env file to store configuration:

.env

# GitHub configuration
GITHUB_TOKEN=ghp_your_token_here
GITRELEASEGEN_GH_CACHE=1
GITRELEASEGEN_GH_CACHE_TTL_MINUTES=30

# AI configuration
OPENAI_API_KEY=sk-...
# or
OPENROUTER_API_KEY=sk-or-...

# Rate limiting
GITRELEASEGEN_GH_MAX_RETRIES=5
GITRELEASEGEN_GH_BACKOFF_CAP_SEC=16

Load it before running commands:

source .env
gitreleasegen generate --unreleased

Add .env to your .gitignore to avoid committing secrets.

Next steps

CLI reference

Complete list of all CLI options

AI features

Learn about AI-powered summarization

Examples

See configuration in action

GitHub integration

Deep dive into GitHub API features

Get Started

Core

Advanced

Examples

Community

​Overview

​Configuration methods

Configuration files

Command-line flags

Environment variables

​Configuration precedence

​Configuration files

​Custom config file location

​Environment variable expansion

​Configuration reference

​Example configurations

​Core configuration areas

​Commit range selection

​Output formatting

​Filtering commits

​GitHub integration

​Authentication

​Rate limiting and retries

​Caching

​Skip GitHub integration

​GitLab integration

​Authentication

​Bitbucket integration

​Authentication

​AI configuration

​Provider selection

​Summary caching

​Prompt engineering

​Example configurations

​Custom templates

​Template locations

​Creating custom formatters

​Environment file

​Next steps

CLI reference

AI features

Examples

GitHub integration

Overview

Configuration methods

Configuration precedence

Configuration files

Custom config file location

Environment variable expansion

Configuration reference

Example configurations

Core configuration areas

Commit range selection

Output formatting

Filtering commits

GitHub integration

Authentication

Rate limiting and retries

Caching

Skip GitHub integration

GitLab integration

Authentication

Bitbucket integration

Authentication

AI configuration

Provider selection

Summary caching

Prompt engineering

Example configurations

Custom templates

Template locations

Creating custom formatters

Environment file

Next steps