Configuration

Complete guide to configuring Relizy.

Configuration File

Create a configuration file in your project root:

relizy.config.ts

import { defineConfig } from 'relizy'

export default defineConfig({
  monorepo: {
    versionMode: 'selective',
    packages: ['packages/*'],
  },
})

relizy.config.js

import { defineConfig } from 'relizy'

export default defineConfig({
  monorepo: {
    versionMode: 'selective',
    packages: ['packages/*'],
  },
})

relizy.config.json

{
  "monorepo": {
    "versionMode": "selective",
    "packages": ["packages/*"]
  }
}

package.json

{
  "name": "my-monorepo",
  "version": "1.0.0",
  "relizy": {
    "monorepo": {
      "versionMode": "selective",
      "packages": ["packages/*"]
    }
  }
}

relizy.config.yml

monorepo:
  versionMode: selective
  packages:
    - packages/*

relizy.config.toml

[monorepo]
versionMode = "selective"
packages = [ "packages/*" ]

Supported Formats

Relizy supports multiple configuration formats. It loaded with c12, check the documentation for more details.

• relizy.config.ts (recommended)
• relizy.config.js
• relizy.config.mjs
• relizy.config.json
• relizy.config.yaml
• relizy.config.yml
• relizy.config.toml
• And more...

Zero Configuration

Relizy works out of the box without any configuration (for single package):

relizy release

Configuration is only needed for:

• Monorepo settings (needs monorepo section with versionMode and packages glob patterns to find your packages)
• Custom commit types
• Multiple release strategies

Quick Start

Single Package

No configuration needed! Just run:

relizy release --minor

Monorepo - Basic

// relizy.config.ts
export default defineConfig({
  monorepo: {
    versionMode: 'selective',
    packages: ['packages/*'],
  },
})

Monorepo - Advanced

// relizy.config.ts
export default defineConfig({
  projectName: 'My project', // replace the name in your root package.json (Useful for Twitter (X) and Slack posts)
  monorepo: {
    versionMode: 'selective',
    packages: ['packages/*'],
    ignorePackageNames: ['pacakge-a'],
  },
  bump: {
    dependencyTypes: ['dependencies', 'devDependencies'],
  },
  types: {
    feat: { title: '🎉 Features', semver: 'minor' },
    fix: { title: '🐛 Fixes', semver: 'patch' },
  },
  publish: {
    access: 'public',
    tag: 'latest',
  },
})

Configuration Sections

Section	Description
monorepo	Monorepo-specific settings
types	Commit type customization
bump	Version bump settings
changelog	Changelog generation settings
publish	NPM publishing options
release	Release workflow settings
ai	AI-enhanced changelogs and announcements
social	Social media integration (Twitter, Slack)
prComment	PR comment settings
hooks	Lifecycle hooks for custom scripts
multiple-configs	Using multiple configuration files

TypeScript Support

Get full IntelliSense with TypeScript:

import { defineConfig } from 'relizy'

export default defineConfig({
  // Full type checking and autocomplete
  monorepo: {
    versionMode: 'selective', // ← Autocompleted
  },
})

Multiple Configurations

Use different configs for different workflows:

# Use default config
relizy release

# Use staging config
relizy release --config relizy.staging

# Uses relizy.staging.config.ts

Learn more in Multiple Configs.

Default Configuration

If no config file exists, Relizy uses these defaults:

const defaultConfig = {
  cwd: process.cwd(),
  types: {
    feat: { title: '🚀 Enhancements', semver: 'minor' },
    perf: { title: '🔥 Performance', semver: 'patch' },
    fix: { title: '🩹 Fixes', semver: 'patch' },
    refactor: { title: '💅 Refactors', semver: 'patch' },
    docs: { title: '📖 Documentation', semver: 'patch' },
    build: { title: '📦 Build', semver: 'patch' },
    types: { title: '🌊 Types', semver: 'patch' },
    chore: { title: '🏡 Chore' },
    examples: { title: '🏀 Examples' },
    test: { title: '✅ Tests' },
    style: { title: '🎨 Styles' },
    ci: { title: '🤖 CI' },
  },
  templates: {
    // commitMessage / commitBody are resolved based on monorepo.versionMode:
    //   - independent      → 'chore(release): bump {{packageCount}} packages' + body '{{packageList}}'
    //   - unified/selective → 'chore(release): bump version to {{newVersion}}' (no body)
    // See: /config/commit-templates for placeholders and examples.
    commitMessage: undefined,
    commitBody: undefined,
    tagMessage: 'Bump version to {{newVersion}}',
    tagBody: 'v{{newVersion}}',
    emptyChangelogContent: 'No relevant changes for this release',
    twitterMessage: '📣 {{projectName}} {{newVersion}} is out!\n\n{{changelog}}\n\n{{releaseUrl}}\n{{changelogUrl}}',
    slackMessage: undefined,
    changelogTitle: '{{oldVersion}}...{{newVersion}}',
  },
  excludeAuthors: [],
  noAuthors: false,
  bump: {
    type: 'release',
    clean: true,
    dependencyTypes: ['dependencies'],
    yes: false,
  },
  changelog: {
    rootChangelog: true,
    includeCommitBody: true,
  },
  publish: {
    private: false,
    args: [],
  },
  tokens: {
    gitlab:
        process.env.RELIZY_GITLAB_TOKEN
        || process.env.GITLAB_TOKEN
        || process.env.GITLAB_API_TOKEN
        || process.env.CI_JOB_TOKEN,
    github:
        process.env.RELIZY_GITHUB_TOKEN
        || process.env.GITHUB_TOKEN
        || process.env.GH_TOKEN,
    twitter: {
      apiKey: process.env.RELIZY_TWITTER_API_KEY || process.env.TWITTER_API_KEY,
      apiKeySecret: process.env.RELIZY_TWITTER_API_KEY_SECRET || process.env.TWITTER_API_KEY_SECRET,
      accessToken: process.env.RELIZY_TWITTER_ACCESS_TOKEN || process.env.TWITTER_ACCESS_TOKEN,
      accessTokenSecret: process.env.RELIZY_TWITTER_ACCESS_TOKEN_SECRET || process.env.TWITTER_ACCESS_TOKEN_SECRET,
    },
    slack:
        process.env.RELIZY_SLACK_TOKEN
        || process.env.SLACK_TOKEN,
    ai: {
      'claude-code': {
        apiKey: process.env.RELIZY_ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY,
        oauthToken: process.env.RELIZY_CLAUDE_CODE_OAUTH_TOKEN || process.env.CLAUDE_CODE_OAUTH_TOKEN,
      },
    },
  },
  scopeMap: {},
  social: {
    twitter: {
      enabled: false,
      onlyStable: true,
    },
    slack: {
      enabled: false,
      onlyStable: true,
    },
  },
  prComment: {
    mode: 'append',
  },
  ai: {
    provider: 'claude-code',
    language: 'en',
    fallback: 'raw',
    providers: {
      'claude-code': { model: 'haiku' },
    },
    providerRelease: { enabled: false },
    social: {
      twitter: { enabled: false },
      slack: { enabled: false },
    },
  },
  release: {
    commit: true,
    publish: true,
    changelog: true,
    push: true,
    clean: true,
    providerRelease: true,
    noVerify: false,
    gitTag: true,
    social: true,
    prComment: true,
  },
  logLevel: 'default',
  detectRewrittenTags: true,
}

Detecting Rewritten Tags

When a release tag is created and pushed, then the branch is later rebased, the tag keeps pointing to the old (now orphaned) commit. Resolving a changelog from an orphaned tag spans the whole divergent range (often the entire history since the last stable release, with duplicated commits) and over-bumps packages.

Relizy detects this automatically and recovers safely. Two top-level options control the behavior:

Option	Type	Default	Description
detectRewrittenTags	boolean	true	Detect when the from tag is no longer reachable from to and recover.
onRewrittenTag	string	auto	prompt | ephemeral | rebind | error. Auto = prompt (TTY) / ephemeral (CI/--yes).

A commit is never rewritten; the only possible mutation is moving a tag. See the Rewritten Tags & Rebases guide for the full explanation and the recommended git workflow.

Next Steps

Explore specific configuration sections:

• Monorepo Config - Monorepo-specific settings
• Changelog Config - Changelog generation and commit types
• Bump Config - Version bump settings
• Publish Config - NPM publishing options
• Release Config - Release workflow settings
• AI Config - AI-enhanced changelogs and announcements
• Social Config - Social media integration (Twitter, Slack)
• PR Comment Config - PR comment settings
• Hooks Config - Lifecycle hooks for custom scripts
• Multiple Configs - Using multiple configuration files