javachanges Troubleshooting Guide

1. Overview

This guide collects the most common problems people hit when adopting javachanges in local development, GitHub Actions, GitLab CI/CD, Maven repositories, Gradle repositories, and Maven publishing.

Use it when:

status or plan prints unexpected release information
CI says credentials or variables are missing
Maven publishing fails even though the workflow looks correct
the example workflows were copied but do not run in the target repository

2. Local repository and changeset problems

2.1 `No pending changesets`

Symptom	Cause	Fix
`status` shows `Pending changesets: 0`	`.changesets/*.md` does not exist, was already consumed, or is malformed	create a new changeset with `add`, then rerun `status`

Checks:

bash

find .changesets -maxdepth 1 -name '*.md'
mvn -q -DskipTests compile exec:java -Dexec.args="status --directory /path/to/repo"

2.2 `add` succeeds but `plan` does not affect the module you expected

Symptom	Cause	Fix
The release plan lists the wrong package or misses a package	the changeset uses the wrong Maven artifactId	align the frontmatter keys with the real artifactIds from `pom.xml`

Good example:

---
"core": minor
"api": patch
---

Improve release planning output.

2.3 `plan` does not write `release-plan.json`

Symptom	Cause	Fix
`.changesets/release-plan.json` is missing after `plan`	you ran preview mode only	rerun with `--apply true`

Correct command:

bash

mvn -q -DskipTests compile exec:java -Dexec.args="plan --directory /path/to/repo --apply true"

2.4 `manifest-field` fails

Symptom	Cause	Fix
`manifest-field` cannot read a field	compatibility manifest was not written	use `manifest-field --fresh true`, or apply the plan with generated files enabled

2.5 Gradle repository root is not detected

Symptom	Cause	Fix
`Cannot find repository root` in a Gradle repository	the repository does not have `gradle.properties`, or it has no Gradle settings/build file at the root	add `gradle.properties` plus `settings.gradle(.kts)` or `build.gradle(.kts)`

Minimum Gradle files:

text

gradle.properties
settings.gradle.kts
build.gradle.kts

gradle.properties must contain one supported version key:

properties

version=1.0.0-SNAPSHOT

2.6 Gradle changeset uses the wrong package key

Symptom	Cause	Fix
`Unknown module` for a Gradle multi-project build	the changeset key does not match the final segment of an `include(...)` project path	use `api` for `:api`, `core` for `:core`, and `cli` for `:tools:cli`

Check settings.gradle(.kts) and align the changeset frontmatter:

---
"api": minor
"core": patch
---

Improve Gradle release planning.

2.7 Unsupported release level

Use only patch, minor, or major with javachanges add --release.

bash

javachanges add --directory . --summary "describe the change" --release patch

3. Java and Maven environment problems

3.1 Build fails or behaves differently across machines

Symptom	Cause	Fix
local results differ from CI	Java version drift	standardize on Java 8 for this repository

Verify:

bash

java -version
mvn -v

Expected direction:

Java 8
Maven 3.8+

3.2 `exec:java` fails or the CLI does not start

Symptom	Cause	Fix
Maven cannot run `exec:java`	dependencies were not built yet, or the build is broken	run `mvn -q test` first

3.3 `doctor-local` says `./mvnw` is missing

Symptom	Cause	Fix
the runtime section shows `./mvnw MISSING`	the target repository does not vendor a Maven wrapper	this is fine if a system `mvn` is available and `Maven command` resolves to `mvn (system)`

What to check:

if Maven command is mvn (system), the fallback worked
if both wrapper and system Maven are unavailable, install Maven or add a wrapper

3.4 Example workflow cannot download `javachanges`

Symptom	Cause	Fix
Maven dependency copy fails for `io.github.sonofmagic:javachanges`	`JAVACHANGES_VERSION` is still the placeholder value	replace it with a real published version before enabling CI

The example templates intentionally use:

yaml

JAVACHANGES_VERSION: "REPLACE_WITH_PUBLISHED_VERSION"

That is a reminder, not a runnable default.

3.5 Maven says `Unknown lifecycle phase` when wrapping `javachanges`

Symptom	Cause	Fix
Maven fails with `Unknown lifecycle phase "version --directory ..."` or a similar CLI payload	`-Dexec.args=` was split from the actual `javachanges` command by Make, shell, or CI string concatenation	keep the full `-Dexec.args="..."` assignment in the final command line, or wrap the entire Maven invocation in one Make function or script

Recommended direction:

good: ./mvnw -q -DskipTests compile exec:java -Dexec.args="version --directory $PWD"
bad: define a prefix ending in bare -Dexec.args= and append "version --directory ..." later

3.6 Gradle users are calling the Maven plugin by mistake

Symptom	Cause	Fix
Gradle repository examples fail because `mvn javachanges:...` is unavailable	the Maven plugin goal syntax only works inside Maven	download the CLI jar and run `java -jar .javachanges/javachanges-<version>.jar ...`

Gradle command shape:

bash

java -jar .javachanges/javachanges-1.12.2.jar status --directory .

4. GitHub Actions problems

4.1 `sync-vars` or `audit-vars` says values are missing

Symptom	Cause	Fix
repository variables or secrets are missing	`env/release.env.local` still contains placeholders, or the repository name is wrong	replace placeholder values, then rerun `render-vars`, `sync-vars`, and `audit-vars`

Suggested order:

init-env
fill the env file
render-vars --platform github
sync-vars --platform github --execute true
audit-vars --platform github

4.2 Release PR workflow keeps changing unrelated files

Symptom	Cause	Fix
the release branch includes extra noise	the workflow stages too much or runs additional generators	limit the commit scope to `pom.xml` or `gradle.properties`, `CHANGELOG.md`, and `.changesets`

4.3 Maven downloads still happen even with cache enabled

Symptom	Cause	Fix
the workflow still downloads dependencies	first cache warmup or a changed dependency graph	let one successful run warm the cache; this is normal

4.4 Release tag exists but publishing did not finish

Symptom	Cause	Fix
`Publish Release` created `vX.Y.Z`, but Maven Central publishing or GitHub Release creation failed later	the workflow stopped after tagging and before the remaining publish steps completed	rerun `Publish Release` with the same merged release commit SHA through `workflow_dispatch`
`github-tag-from-plan` says the tag already exists at the target commit	the rerun is correctly targeting the same release commit	continue the rerun; this is the intended recovery path
the workflow says the tag points at a different commit	the retry is targeting the wrong commit, or the tag was moved manually	inspect the tag target and rerun for that commit, or move the tag only after confirming it is wrong

5. GitLab CI/CD problems

5.1 Release MR is never created

Symptom	Cause	Fix
`gitlab-release-plan` skips	no pending changesets, or missing GitLab auth variables	add a new changeset and verify `GITLAB_RELEASE_BOT_USERNAME` / `GITLAB_RELEASE_BOT_TOKEN`

5.2 Release tag job does nothing

Symptom	Cause	Fix
`gitlab-tag-from-plan` skips tagging	release state did not change, or `CI_COMMIT_BEFORE_SHA` is unusable	inspect the default branch pipeline and confirm the version file and changelog changed

5.3 Release MR push fails with `stale info`

Symptom	Cause	Fix
`release_plan_mr` fails with `failed to push some refs` and `stale info`	another writer updated the same `changeset-release/<default-branch>` branch after `gitlab-release-plan` resolved the current remote SHA	rerun the pipeline; if the branch is meant to be owned only by javachanges, remove the competing writer

5.4 Hygiene or secret scanning reports the scanner rules themselves

Symptom	Cause	Fix
a hygiene job flags `.gitlab-ci.yml`, `Makefile`, or a rules file even though no real credential was added	the scanner matched detector literals such as token prefixes or private-key markers inside its own configuration	move secret patterns into one dedicated file, exclude that file and scanner-owned config files from scanning, and keep allowlist comments for reviewed exceptions only

6. Publish and credentials problems

6.1 `preflight` or `publish` says credentials are missing

Symptom	Cause	Fix
publish commands fail before deploy	required repository URLs, ids, or credentials are not set	populate the env file or CI secrets, then rerun `doctor-local` or `doctor-platform`

Minimum shared variables:

Name
`MAVEN_RELEASE_REPOSITORY_URL`
`MAVEN_SNAPSHOT_REPOSITORY_URL`
`MAVEN_RELEASE_REPOSITORY_ID`
`MAVEN_SNAPSHOT_REPOSITORY_ID`
`MAVEN_REPOSITORY_USERNAME`
`MAVEN_REPOSITORY_PASSWORD`

6.1.1 Gradle publish should not use `publish`

Symptom	Cause	Fix
a Gradle repository sees Maven deploy output from `publish`	`preflight` and `publish` are Maven-specific helpers	use `manifest-field` to get the release version, then run `./gradlew publish`

Gradle release handoff:

bash

RELEASE_VERSION="$(java -jar .javachanges/javachanges-1.12.2.jar manifest-field --directory . --field releaseVersion --fresh true)"
./gradlew publish -Pversion="$RELEASE_VERSION"

6.2 Publish fails on a dirty worktree

Symptom	Cause	Fix
`preflight` or `publish` rejects the repository	the repo has local edits or generated files	commit or clean the tree before publishing

Use --allow-dirty true only when you intentionally accept that risk.

6.3 Maven Central publish fails with missing jars or signatures

Symptom	Cause	Fix
`sources.jar`, `javadoc.jar`, or signatures are missing	the `central-publish` profile or GPG setup is incomplete	rerun the Central verification steps from the Maven Central guide

Verification command:

bash

mvn -Pcentral-publish -Dgpg.skip=true verify

6.4 Plain snapshot mode still produces timestamped filenames in Nexus or other snapshot repositories

Symptom	Cause	Fix
`publish --snapshot --snapshot-version-mode plain` kept the project version at `1.2.3-SNAPSHOT`, but the repository shows files like `1.2.3-20260420.154500-1.jar`	Maven snapshot repositories expand snapshot artifact filenames on the server side	this is expected; verify the effective project version from `preflight` / `publish` output or JSON, not from the stored snapshot filename

Important distinction:

plain mode means javachanges no longer rewrites the Maven project version to 1.2.3-<stamp>-SNAPSHOT
repository-side timestamped filenames are still normal Maven snapshot behavior

6.5 Maven Central rejects signatures because the public key fingerprint is not discoverable

Symptom	Cause	Fix
Central says it could not find a public key by the key fingerprint	the signing key was imported in CI, but its public key is not yet visible on a supported keyserver	publish the public key and wait for discovery before `deploy`

Recommended CI check:

bash

mvn -q -DskipTests compile exec:java -Dexec.args="ensure-gpg-public-key --directory $PWD"

This command currently publishes to and verifies discovery from:

hkps://keyserver.ubuntu.com
hkps://keys.openpgp.org

6.6 Manual publish retry uses the wrong commit or release version

Symptom	Cause	Fix
a manual retry creates the wrong tag, or `RELEASE_VERSION` is empty	the retry did not target the merged release commit, or the workflow ran helper logic from the old release tree	rerun `Publish Release` with the original merged release commit SHA through `workflow_dispatch`

For this repository, publish-release.yml now supports manual retries through the release_commit_sha input.

7. Release plan manifest confusion

7.1 `type: other` appears in `release-plan.json`

Symptom	Cause	Fix
the manifest contains `"type": "other"`	the field is a legacy compatibility field retained by the current implementation	ignore it in new integrations and key off `release`, `summary`, and `modules` instead

If you use the official package-map changeset format, type is not the release level. The meaningful release signal is release.

8. Fast checklist

Check	Command or file
Java version	`java -version`
Maven version	`mvn -v`
Gradle version	`./gradlew -v`
Pending changesets	`status`
Applied manifest exists	`.changesets/release-plan.json`
CI variables look correct	`render-vars` / `audit-vars`
Publish inputs are valid	`doctor-local` / `preflight`
Example workflow placeholder replaced	`JAVACHANGES_VERSION`

Need	Document
Local setup	Development Guide
Example repository walkthrough	Examples Guide
Gradle setup	Gradle Usage Guide
Full CLI command list	CLI Reference
Generated manifest fields	Release Plan Manifest
GitHub Actions automation	GitHub Actions Usage Guide
GitLab CI/CD automation	GitLab CI/CD Usage Guide

javachanges Troubleshooting Guide ​

1. Overview ​

2. Local repository and changeset problems ​

2.1 No pending changesets ​

2.2 add succeeds but plan does not affect the module you expected ​

2.3 plan does not write release-plan.json ​

2.4 manifest-field fails ​

2.5 Gradle repository root is not detected ​

2.6 Gradle changeset uses the wrong package key ​

2.7 Unsupported release level ​

3. Java and Maven environment problems ​

3.1 Build fails or behaves differently across machines ​

3.2 exec:java fails or the CLI does not start ​

3.3 doctor-local says ./mvnw is missing ​

3.4 Example workflow cannot download javachanges ​

3.5 Maven says Unknown lifecycle phase when wrapping javachanges ​

3.6 Gradle users are calling the Maven plugin by mistake ​

4. GitHub Actions problems ​

4.1 sync-vars or audit-vars says values are missing ​

4.2 Release PR workflow keeps changing unrelated files ​

4.3 Maven downloads still happen even with cache enabled ​

4.4 Release tag exists but publishing did not finish ​

5. GitLab CI/CD problems ​

5.1 Release MR is never created ​

5.2 Release tag job does nothing ​

5.3 Release MR push fails with stale info ​

5.4 Hygiene or secret scanning reports the scanner rules themselves ​

6. Publish and credentials problems ​

6.1 preflight or publish says credentials are missing ​

6.1.1 Gradle publish should not use publish ​

6.2 Publish fails on a dirty worktree ​

6.3 Maven Central publish fails with missing jars or signatures ​

6.4 Plain snapshot mode still produces timestamped filenames in Nexus or other snapshot repositories ​

6.5 Maven Central rejects signatures because the public key fingerprint is not discoverable ​

6.6 Manual publish retry uses the wrong commit or release version ​

7. Release plan manifest confusion ​

7.1 type: other appears in release-plan.json ​

8. Fast checklist ​

9. Related guides ​

javachanges Troubleshooting Guide

1. Overview

2. Local repository and changeset problems

2.1 `No pending changesets`

2.2 `add` succeeds but `plan` does not affect the module you expected

2.3 `plan` does not write `release-plan.json`

2.4 `manifest-field` fails

2.5 Gradle repository root is not detected

2.6 Gradle changeset uses the wrong package key

2.7 Unsupported release level

3. Java and Maven environment problems

3.1 Build fails or behaves differently across machines

3.2 `exec:java` fails or the CLI does not start

3.3 `doctor-local` says `./mvnw` is missing

3.4 Example workflow cannot download `javachanges`

3.5 Maven says `Unknown lifecycle phase` when wrapping `javachanges`

3.6 Gradle users are calling the Maven plugin by mistake

4. GitHub Actions problems

4.1 `sync-vars` or `audit-vars` says values are missing

4.2 Release PR workflow keeps changing unrelated files

4.3 Maven downloads still happen even with cache enabled

4.4 Release tag exists but publishing did not finish

5. GitLab CI/CD problems

5.1 Release MR is never created

5.2 Release tag job does nothing

5.3 Release MR push fails with `stale info`

5.4 Hygiene or secret scanning reports the scanner rules themselves

6. Publish and credentials problems

6.1 `preflight` or `publish` says credentials are missing

6.1.1 Gradle publish should not use `publish`

6.2 Publish fails on a dirty worktree

6.3 Maven Central publish fails with missing jars or signatures

6.4 Plain snapshot mode still produces timestamped filenames in Nexus or other snapshot repositories

6.5 Maven Central rejects signatures because the public key fingerprint is not discoverable

6.6 Manual publish retry uses the wrong commit or release version

7. Release plan manifest confusion

7.1 `type: other` appears in `release-plan.json`

8. Fast checklist

9. Related guides