javachanges Configuration Reference

1. Overview

This page is the configuration catalog for javachanges.

Use it when you need one place to look up:

• changeset file structure
• CLI flags that affect behavior
• env/release.env.example variables
• GitHub Actions and GitLab CI/CD variable mapping
• publishing-related environment prerequisites

2. Configuration Surface Map

Surface	Where it lives	Typical owner
Changeset files	.changesets/*.md	Contributors
CLI invocation flags	command line / CI workflow YAML	Maintainers and CI authors
Release env template	env/release.env.example	Maintainers
Platform variables and secrets	GitHub Actions / GitLab CI/CD settings	Repository admins
Maven publish credentials	local env, CI secrets, generated settings.xml	Release maintainers
Repository version model	Maven root pom.xml <revision> or Gradle gradle.properties version	Maintainers

3. Changeset File Configuration

3.1 Recommended format

javachanges now defaults to the official Changesets-style package map:

---
"javachanges": minor
---

Add GitHub Actions release automation.

Monorepo example:

---
"core": minor
"cli": patch
---

Improve CLI parsing and release planning.

Rules:

Part	Meaning
frontmatter key	Maven artifactId or Gradle project name
frontmatter value	patch, minor, or major
markdown body	user-facing summary and notes

3.2 .changesets/config.json / .changesets/config.jsonc

javachanges also supports a repository-level config file:

{
  "baseBranch": "main",
  "releaseBranch": "changeset-release/main",
  "snapshotBranch": "snapshot",
  "snapshotVersionMode": "plain",
  "tagStrategy": "whole-repo"
}

Accepted forms:

• .changesets/config.json
• .changesets/config.jsonc
• comments are allowed in either form through // and /* ... */

Supported fields:

Field	Meaning	Default
baseBranch	Default base branch for release-plan automation	main
releaseBranch	Default generated release branch name	changeset-release/<baseBranch>
snapshotBranch	Conventional branch used for snapshot publishing	snapshot
snapshotVersionMode	Snapshot publish strategy: stamped or plain	stamped
tagStrategy	Release tag strategy: whole-repo or per-module	whole-repo

Current behavior:

• GitLab release-plan defaults read baseBranch and releaseBranch from this file when CLI flags and CI variables are absent
• GitLab tag creation reads baseBranch and releaseBranch from this file to avoid tagging from the release branch and other non-base branches
• preflight and publish read snapshotBranch from this file and default to snapshot mode when the current CI branch matches it
• preflight and publish also read snapshotVersionMode; CLI --snapshot-version-mode overrides the config file
• when snapshotBranch matches and snapshotVersionMode is plain, GitLab snapshot-branch jobs can keep using publish --execute true without extra shell branching
• plan, github-tag-from-plan, and gitlab-tag-from-plan read tagStrategy; per-module creates one artifactId/vX.Y.Z tag per affected module
• GitHub Actions examples in this repository follow the same branch naming model
• snapshotBranch is no longer documentation-only; GitLab snapshot publish flows consume it directly

3.3 Legacy compatibility

The older javachanges frontmatter is still accepted:

---
release: minor
type: ci
modules: javachanges
summary: automate javachanges self-release publishing via GitHub Actions
---

Compatibility status:

Field	Status
release	Legacy, still parsed
modules	Legacy, still parsed
summary	Legacy, still parsed
type	Legacy metadata, still parsed

Note: new files should use the official package-map format instead of the legacy fields above.

4. CLI Flags That Affect Configuration

4.1 add

Flag	Meaning	Default
--summary	First line of the generated markdown body	interactive prompt if omitted
--release	Release type to write for each selected package	interactive prompt if omitted
--modules	Comma-separated Maven artifactIds, Gradle project names, or all	all
--body	Extra markdown body after the summary	empty
--type	Legacy metadata only	omitted
--format	Output format, text or json	text
--no-interactive	Fail instead of prompting when required input is missing	false

4.2 plan

Flag	Meaning	Default
--apply	Apply the calculated release plan and write files	false
--directory	Target repository path	current directory, resolved upward

4.3 preflight and publish

Flag	Meaning	Default
--snapshot	Publish the current snapshot version	false
--snapshot-version-mode	Snapshot version strategy: stamped or plain	config value, then stamped
--snapshot-build-stamp	Explicit snapshot publish stamp	auto-generated
--tag	Publish a release tag like v1.2.3	none
--module	Restrict publish to one Maven artifactId or Gradle project name	all packages
--allow-dirty	Skip dirty worktree protection	false
--execute	Run the final publish command instead of only printing it	false

GitLab CI defaults for these commands:

• CI_COMMIT_TAG is used automatically as the publish tag when --tag is omitted
• .changesets/config.json / .changesets/config.jsonc snapshotBranch is used automatically when --snapshot is omitted
• .changesets/config.json / .changesets/config.jsonc snapshotVersionMode is used automatically when --snapshot-version-mode is omitted
• this lets a GitLab job use publish --execute true directly for both tag and snapshot pipelines

4.4 GitLab release commands

Command	Flag	Default source
gitlab-release-plan	--project-id	CI_PROJECT_ID
gitlab-release-plan	--target-branch	CI_DEFAULT_BRANCH, then main
gitlab-release-plan	--release-branch	.changesets/config.* releaseBranch, then changeset-release/<target-branch>
gitlab-tag-from-plan	--before-sha	CI_COMMIT_BEFORE_SHA
gitlab-tag-from-plan	--current-sha	CI_COMMIT_SHA
gitlab-tag-from-plan	branch guard	.changesets/config.* baseBranch and releaseBranch
gitlab-release	--tag	CI_COMMIT_TAG
gitlab-release	--project-id	CI_PROJECT_ID
gitlab-release	--gitlab-host	CI_SERVER_HOST
init-gitlab-ci	generated branch rules	.changesets/config.* baseBranch and snapshotBranch

5. env/release.env.example

Current template:

Variable	Required	Meaning
MAVEN_RELEASE_REPOSITORY_URL	Yes	Maven release repository URL
MAVEN_SNAPSHOT_REPOSITORY_URL	Yes	Maven snapshot repository URL
MAVEN_RELEASE_REPOSITORY_ID	Yes	Release server id used in Maven settings
MAVEN_SNAPSHOT_REPOSITORY_ID	Yes	Snapshot server id used in Maven settings
MAVEN_REPOSITORY_USERNAME	Yes unless release/snapshot credentials are split	Shared username fallback
MAVEN_REPOSITORY_PASSWORD	Yes unless release/snapshot credentials are split	Shared password fallback
MAVEN_RELEASE_REPOSITORY_USERNAME	No	Explicit release username override
MAVEN_RELEASE_REPOSITORY_PASSWORD	No	Explicit release password override
MAVEN_SNAPSHOT_REPOSITORY_USERNAME	No	Explicit snapshot username override
MAVEN_SNAPSHOT_REPOSITORY_PASSWORD	No	Explicit snapshot password override
MAVEN_CENTRAL_USERNAME	No	Sonatype Central Portal token username fallback
MAVEN_CENTRAL_PASSWORD	No	Sonatype Central Portal token password fallback
JAVACHANGES_SNAPSHOT_BUILD_STAMP	No	Snapshot publish stamp; defaults to UTC timestamp + git short sha when unset
GITLAB_RELEASE_TOKEN	No	Optional GitLab release token for some GitLab release scenarios

Resolution rules used by the code:

Setting	Fallback logic
Release username/password	MAVEN_RELEASE_REPOSITORY_*, then MAVEN_CENTRAL_*, then shared MAVEN_REPOSITORY_*
Snapshot username/password	MAVEN_SNAPSHOT_REPOSITORY_*, then MAVEN_CENTRAL_*, then shared MAVEN_REPOSITORY_*
Release server id	MAVEN_RELEASE_REPOSITORY_ID, then maven-releases
Snapshot server id	MAVEN_SNAPSHOT_REPOSITORY_ID, then maven-snapshots

When MAVEN_CENTRAL_USERNAME and MAVEN_CENTRAL_PASSWORD are set, generated settings also include a central server entry for central-publishing-maven-plugin.

6. GitHub Actions Variable Mapping

6.1 Recommended GitHub Actions variables

These are treated as non-secret variables:

Name
MAVEN_RELEASE_REPOSITORY_URL
MAVEN_SNAPSHOT_REPOSITORY_URL
MAVEN_RELEASE_REPOSITORY_ID
MAVEN_SNAPSHOT_REPOSITORY_ID

6.2 Recommended GitHub Actions secrets

Name
MAVEN_REPOSITORY_USERNAME
MAVEN_REPOSITORY_PASSWORD
MAVEN_CENTRAL_USERNAME
MAVEN_CENTRAL_PASSWORD
MAVEN_RELEASE_REPOSITORY_USERNAME
MAVEN_RELEASE_REPOSITORY_PASSWORD
MAVEN_SNAPSHOT_REPOSITORY_USERNAME
MAVEN_SNAPSHOT_REPOSITORY_PASSWORD

6.3 Repository-specific Maven Central signing secrets

The self-release workflow in this repository also requires:

Secret	Purpose
MAVEN_GPG_PRIVATE_KEY	ASCII-armored private key
MAVEN_GPG_PASSPHRASE	GPG key passphrase

7. GitLab CI/CD Variable Mapping

7.1 Variables synced from the env file

When sync-vars --platform gitlab is used, these values are written as GitLab variables:

Name	Secret	Protected
MAVEN_RELEASE_REPOSITORY_URL	No	No
MAVEN_SNAPSHOT_REPOSITORY_URL	No	No
MAVEN_RELEASE_REPOSITORY_ID	No	No
MAVEN_SNAPSHOT_REPOSITORY_ID	No	No
MAVEN_REPOSITORY_USERNAME	Yes	Yes
MAVEN_REPOSITORY_PASSWORD	Yes	Yes
MAVEN_CENTRAL_USERNAME	Yes	Yes
MAVEN_CENTRAL_PASSWORD	Yes	Yes
MAVEN_RELEASE_REPOSITORY_USERNAME	Yes	Yes
MAVEN_RELEASE_REPOSITORY_PASSWORD	Yes	Yes
MAVEN_SNAPSHOT_REPOSITORY_USERNAME	Yes	Yes
MAVEN_SNAPSHOT_REPOSITORY_PASSWORD	Yes	Yes
GITLAB_RELEASE_TOKEN	Yes	Yes

Operational note:

• doctor-platform --platform gitlab now checks both remote protected variables and the configured snapshotBranch
• if protected variables exist but the snapshot branch is not protected, the command fails with a concrete remediation hint because GitLab will not expose protected variables to that branch

7.2 Extra GitLab CI runtime variables

These are expected by the GitLab release automation:

Variable	Source
CI_PROJECT_ID	GitLab built-in variable
CI_DEFAULT_BRANCH	GitLab built-in variable
CI_SERVER_HOST	GitLab built-in variable
CI_SERVER_URL	GitLab built-in variable
CI_PROJECT_PATH	GitLab built-in variable
CI_COMMIT_BEFORE_SHA	GitLab built-in variable
CI_COMMIT_SHA	GitLab built-in variable
GITLAB_RELEASE_BOT_USERNAME	Project variable you provide
GITLAB_RELEASE_BOT_TOKEN	Project variable you provide

8. Repository Version And Publish Configuration

8.1 Repository version model

Recommended Maven root pom.xml pattern:

<version>${revision}</version>

And the mutable version field:

<revision>1.2.3-SNAPSHOT</revision>

Recommended Gradle gradle.properties pattern:

version=1.2.3-SNAPSHOT

javachanges also accepts revision=1.2.3-SNAPSHOT in gradle.properties, but version is preferred for Gradle builds.

8.2 Local Maven repository override

publish and preflight recognize MAVEN_OPTS values like:

export MAVEN_OPTS="-Dmaven.repo.local=.m2/repository"

Effect:

Setting	Result
no MAVEN_OPTS override	uses .m2/repository inside the target repo
relative maven.repo.local	resolved relative to the target repo
absolute maven.repo.local	used as-is

8.3 Snapshot version modes

javachanges supports two snapshot publish modes:

Mode	Behavior
stamped	rewrites 1.2.3-SNAPSHOT to a unique value like 1.2.3-20260420.154500.abc1234-SNAPSHOT before deploy
plain	keeps the effective Maven version at the original revision such as 1.2.3-SNAPSHOT

Important note:

• plain mode preserves the Maven project version only
• Maven or Nexus snapshot repositories still typically store expanded timestamped filenames for uploaded snapshot artifacts
• that filename expansion is standard repository behavior, not an extra rewrite by javachanges

Gradle note:

• preflight and publish are Maven-specific
• Gradle builds should use manifest-field --field releaseVersion and run ./gradlew publish -Pversion=...
• Gradle release planning still writes gradle.properties, CHANGELOG.md, and .changesets/release-plan.*

9. Recommended Defaults By Scenario

9.1 Single-module library

Surface	Recommendation
Changeset file	one package key matching the root artifactId
--modules	omit it or use all
release tagging	v1.2.3
publish target	all packages

9.2 Maven monorepo

Surface	Recommendation
Changeset file	one frontmatter entry per affected artifactId
--modules	pass explicit artifactIds during add
release tagging	whole-repo v1.2.3 unless you intentionally use module tags elsewhere
publish target	all packages, or one --module when needed

9.3 Gradle single-project or multi-project build

Surface	Recommendation
Version file	gradle.properties with version=...-SNAPSHOT
Project detection	settings.gradle(.kts) include(...) entries
Changeset file	one frontmatter entry per affected Gradle project name
--modules	pass project names such as core,api, or all
publish target	Gradle publish tasks, using manifest fields as inputs

9.4 Why whole-repo tags are the default for Maven and Gradle monorepos

javachanges intentionally defaults to whole-repo tags such as v1.2.3 for Java monorepos.

Reasoning:

• many Maven and Gradle monorepos publish a coordinated release train where multiple artifacts move to the same version together
• the release PR, changelog, release notes, signing, and Maven Central deploy steps are commonly handled as one repository-level release operation
• Java consumers often reason about compatibility as "this repository release" or "this platform version", not only as isolated package versions

This differs from the usual Changesets workflow in npm monorepos, where per-package tags such as pkg-a@1.2.3 are often more useful because packages are published and consumed independently.

In practice, the recommended mental model is:

• use whole-repo tags like v1.2.3 when your Maven modules are versioned and released together
• use module tags only when your repository deliberately treats modules as independently tagged release units

javachanges can still parse module tags like demo-app/v2.0.0 for downstream release and notes workflows, but release-plan automation creates a single whole-repo tag by default.

If you opt into per-module tagging:

• plan --apply true still computes one shared releaseVersion
• github-tag-from-plan and gitlab-tag-from-plan create one tag per affected module, such as core/v1.2.3
• github-release-from-plan only works when the plan resolves to a single tag; for multi-module plans, use explicit tag-based release commands instead

10. Related Guides

Need	Document
Command-by-command syntax	CLI Reference
Generated manifest files	Release Plan Manifest
GitHub workflow patterns	GitHub Actions Usage Guide
GitLab workflow patterns	GitLab CI/CD Usage Guide
Maven Central self-release flow	Publish To Maven Central