Skip to content

configuration-reference.md

Latest commit

 

History

History
418 lines (310 loc) · 16.2 KB

configuration-reference.md

File metadata and controls

418 lines (310 loc) · 16.2 KB
Raw
description Reference for javachanges changeset files, CLI flags, environment variables, and publish-related configuration.

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