From e666c015cd9ec24fb6da300f91ff986d55d0b87e Mon Sep 17 00:00:00 2001 From: Bruno Borges Date: Tue, 7 Jul 2026 13:44:36 -0400 Subject: [PATCH] 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/advanced-usage.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index 2b769abd..3f25fc37 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -601,6 +601,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 stack traces, e.g. `Exception in thread "main" ...` (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: