releaser/docs/content/configuration.md

title, weight

title	weight
Configuration	30

releaser reads .releaser.yml from the repository root. All fields are optional — missing values fall back to the defaults shown below. Run releaser --init to scaffold the file with annotations.

Full reference

git:
  tag_prefix: ""                                     # default: no prefix; "v" for v1.2.3 style
  branch_pattern: "^(?:.*/)?release/(\\d+)\\.(\\d+)$"  # two capture groups: major, minor
  commit_message: "chore(release): {version} [skip ci]"
  author_name: ""                                    # defaults to git config user.name
  author_email: ""                                   # defaults to git config user.email

  # Limit which commit types trigger a release (default: all three).
  releasable_types:
    - fix
    - feat
    - breaking

  # Control which version component each commit type bumps.
  # Valid values: "patch" (default) or "minor".
  bump_rules:
    breaking: "patch"
    feat: "patch"
    fix: "patch"

maven:
  pom_path: "pom.xml"                                # single pom.xml, relative to repo root

  # Multi-module: list overrides pom_path.
  # pom_paths:
  #   - "pom.xml"
  #   - "module-a/pom.xml"
  #   - "module-b/pom.xml"

node:                                                # opt-in — omit section to skip
  # package_json: "package.json"                     # single path

  # Monorepo: list overrides package_json.
  # package_jsons:
  #   - "packages/frontend/package.json"
  #   - "packages/backend/package.json"

gradle:                                              # opt-in — omit section to skip
  # build_file: "build.gradle"                       # Groovy or Kotlin DSL; single path

  # Multi-module: list overrides build_file.
  # build_files:
  #   - "build.gradle"
  #   - "module-a/build.gradle"

python:                                              # opt-in — omit section to skip
  # pyproject_toml: "pyproject.toml"                 # PEP 621 [project].version or [tool.poetry].version

  # Monorepo: list overrides pyproject_toml.
  # pyproject_tomls:
  #   - "pyproject.toml"
  #   - "packages/cli/pyproject.toml"

gitlab:
  url: "https://gitlab.example.com"                  # or env CI_SERVER_URL
  token: ""                                          # prefer env GITLAB_TOKEN
  project: ""                                        # prefer env CI_PROJECT_ID or CI_PROJECT_PATH

github:
  token: ""                                          # prefer env GITHUB_TOKEN
  repo: ""                                           # "owner/repo" format

notify:                                              # opt-in — every field independent; failures are warnings, not errors
  # slack_webhook_url: ""                             # or env SLACK_WEBHOOK_URL
  # teams_webhook_url: ""                             # or env TEAMS_WEBHOOK_URL
  # google_chat_webhook_url: ""                       # or env GOOGLE_CHAT_WEBHOOK_URL
  # telegram_bot_token: ""                            # or env TELEGRAM_BOT_TOKEN (both required)
  # telegram_chat_id: ""                              # or env TELEGRAM_CHAT_ID
  # webhook_url: ""                                   # generic {"version","notes"} JSON POST; or env RELEASER_WEBHOOK_URL

{{< hint info >}} When both github.* and gitlab.* are configured, GitHub takes precedence. {{< /hint >}}

Environment variables

Variable	Used for
GITLAB_TOKEN	GitLab API auth + HTTPS push auth
CI_SERVER_URL	GitLab instance URL
CI_PROJECT_ID	GitLab project identifier (numeric)
CI_PROJECT_PATH	GitLab project identifier (fallback)
GITHUB_TOKEN	GitHub API auth
SLACK_WEBHOOK_URL	Slack release notification
TEAMS_WEBHOOK_URL	Microsoft Teams release notification
GOOGLE_CHAT_WEBHOOK_URL	Google Chat release notification
TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID	Telegram release notification (both required)
RELEASER_WEBHOOK_URL	Generic webhook release notification

Config sources

Run releaser --verbose --dry-run to see every config key, its resolved value, and where it came from (default / config file / env: VARNAME / flag: --name).

git.releasable_types

By default fix, feat, and breaking commits all trigger a release. Use releasable_types to restrict this — for example, on a maintenance branch where you want only bug fixes to release:

git:
  releasable_types:
    - fix

git.bump_rules

By default every releasable commit bumps the patch component. The bump_rules map lets you promote specific types to bump minor instead. This is useful on a branch that manages its own minor versioning:

git:
  bump_rules:
    feat: "minor"      # feat: commits bump minor, not patch
    breaking: "minor"  # breaking changes bump minor too
    fix: "patch"       # fix: stays patch (this is the default)

Multi-module Maven

pom_paths accepts a list and overrides pom_path. All listed files are updated and committed in the same release commit:

maven:
  pom_paths:
    - "pom.xml"
    - "module-a/pom.xml"
    - "module-b/pom.xml"

The --pom CLI flag sets a single path and clears pom_paths.

Node.js support

The node section is opt-in — if omitted, no package.json is touched. Use package_jsons for monorepos:

node:
  package_jsons:
    - "packages/frontend/package.json"
    - "packages/backend/package.json"

Python support

The python section is opt-in — if omitted, no pyproject.toml is touched. releaser reads [project].version (PEP 621) first; if not found it falls back to [tool.poetry].version. The original file formatting is preserved on write.

python:
  pyproject_toml: "pyproject.toml"

Use pyproject_tomls for monorepos:

python:
  pyproject_tomls:
    - "pyproject.toml"
    - "packages/cli/pyproject.toml"
    - "packages/lib/pyproject.toml"

The --pyproject <path> CLI flag sets a single path and clears pyproject_tomls.

Gradle support

The gradle section is opt-in — if omitted, no build file is touched. Both Groovy DSL (version = '1.2.3') and Kotlin DSL (version = "1.2.3") are supported; the original quote style is preserved on write.

gradle:
  build_file: "build.gradle"

Use build_files for multi-module projects:

gradle:
  build_files:
    - "build.gradle"
    - "module-a/build.gradle"
    - "module-b/build.gradle"

The --gradle <path> CLI flag sets a single build file path and clears build_files.

Notifications

The notify section is opt-in — every target is independent, and any combination may be configured at once. A notification failure is logged as a warning and never fails the release; notifications fire once the tag has been pushed, whether or not a GitLab/GitHub release is also created (--no-release still notifies; --no-push and --no-commit do not, since nothing was published).

notify:
  slack_webhook_url: "https://hooks.slack.com/services/..."
  teams_webhook_url: "https://outlook.office.com/webhook/..."
  google_chat_webhook_url: "https://chat.googleapis.com/v1/spaces/.../messages?key=..."
  telegram_bot_token: "123456:ABC-..."
  telegram_chat_id: "-1001234567890"
  webhook_url: "https://example.com/hooks/releaser"

• Slack / Google Chat — a single {"text": "..."} incoming-webhook payload.
• Microsoft Teams — a legacy O365 connector MessageCard payload (the format Teams incoming webhook URLs accept).
• Telegram — telegram_bot_token and telegram_chat_id are both required; posts to the Bot API sendMessage endpoint as plain text (no parse_mode, since release notes come from free-form commit messages and aren't guaranteed to be valid Telegram Markdown).
• Generic webhook — POSTs {"version": "<tag>", "notes": "<release notes>"} for any downstream consumer (n8n, Zapier, a custom receiver).

Each field also has an environment variable fallback — see Environment variables above.