From c4922bf8099a153c2ad2fa6c869b9e6fa8d21017 Mon Sep 17 00:00:00 2001 From: Bruno Borges Date: Tue, 7 Jul 2026 14:14:25 -0400 Subject: [PATCH] docs: document problem matcher (and how to disable it), Maven Wrapper caching, and generated interactiveMode (#1075) * docs: document the Java problem matcher and how to disable it Add an advanced-usage section explaining the javac/java problem matcher that setup-java registers, and how to turn it off for a job using the built-in ::remove-matcher:: workflow command (owners javac and java). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs: document Maven Wrapper caching and generated interactiveMode - README: note that cache: 'maven' also caches/restores the Maven Wrapper distribution (~/.m2/wrapper/dists), not just the local repository. - advanced-usage: note that the generated settings.xml sets interactiveMode=false for non-interactive CI runs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Clarify Java problem matcher annotations Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 2 ++ docs/advanced-usage.md | 40 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/README.md b/README.md index d11e1855..fa3f8394 100644 --- a/README.md +++ b/README.md @@ -147,6 +147,8 @@ The workflow output `cache-hit` is set to indicate if an exact match was found f The cache input is optional, and caching is turned off by default. +**Maven Wrapper:** when `cache: 'maven'` is enabled, the action also caches and restores the Maven Wrapper distribution downloaded to `~/.m2/wrapper/dists` (in addition to the local repository), so wrapper-based (`./mvnw`) builds don't re-download the wrapper on every run. This is keyed on `**/.mvn/wrapper/maven-wrapper.properties` as shown above. + #### Caching gradle dependencies ```yaml steps: diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index 2b769abd..65193c4b 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -516,6 +516,8 @@ The two `settings.xml` files created from the above example look like the follow ***NOTE***: The `settings.xml` file is created in the Actions `$HOME/.m2` directory. If you have an existing `settings.xml` file at that location, it will be overwritten. See [below](#apache-maven-with-a-settings-path) for using the `settings-path` to change your `settings.xml` file location. +***NOTE***: The generated `settings.xml` sets `false` so that Maven never blocks a CI run waiting on an interactive prompt. This is applied automatically whenever the action generates `settings.xml`. + If you don't want to overwrite the `settings.xml` file, you can set `overwrite-settings: false` ### Extra setup for pom.xml: @@ -601,6 +603,44 @@ jobs: - This setting only affects Maven. It has no effect on Gradle, sbt, or other build tools. - `-ntp` only controls transfer/progress output; it does not change whether Maven runs in batch mode. Use `-B`/`--batch-mode` (or `false` in `settings.xml`) if you also want non-interactive runs. +## Java problem matcher (compiler annotations) + +`setup-java` registers a [problem matcher](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md) for Java after installing the JDK. It scans the log output of subsequent steps and turns `javac` diagnostics into GitHub [annotations](https://docs.github.com/actions/using-workflows/workflow-commands-for-github-actions#setting-a-warning-message) that appear in the run summary and inline on the affected files. It matches two kinds of lines: + +- Compiler errors and warnings, e.g. `App.java:12: error: cannot find symbol` (owner `javac`). +- Uncaught-exception header lines, e.g. `Exception in thread "main" ...`; because these lines have no file or line captures, they appear as log/run-level annotations rather than inline file annotations (owner `java`). + +This is enabled by default and requires no configuration. + +### Disabling the problem matcher + +There is no action input to turn the matcher off, but you can disable it for the rest of the job with the built-in [`remove-matcher`](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md#remove-a-problem-matcher) workflow command. Pass the matcher **owner** (not a file name); the Java matcher defines two owners, `javac` and `java`, so remove both to fully suppress it: + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v6 + - uses: actions/setup-java@v5 + with: + distribution: '' + java-version: '21' + + - name: Disable the Java problem matcher + run: | + echo "::remove-matcher owner=javac::" + echo "::remove-matcher owner=java::" + + - name: Build with Maven + run: mvn -B package --file pom.xml +``` + +***NOTES***: +- `remove-matcher` only stops annotations from being created; the underlying compiler output is unchanged, so a failing `javac`/build still fails the step. +- The command is scoped to the job, so add the step right after `setup-java` (and before your build) in every job where you want the matcher disabled. + ## Publishing using Gradle ```yaml jobs: