Leave the code scanning report off by default

The report needs the security-events: write permission, which the
default token does not have, so with it on by default every workflow
that uses the action would have to add a permissions block, and one
that did not would skip the upload on every run. The code-scanning
input now defaults to false; a workflow that wants the alert sets it
to true and grants the permission, as the README shows. The example
workflow loses the permissions block it no longer needs.

Test Action turns the report on in both jobs: with the permission in
the mode=changed job, where the upload has to go through, and without
it on the first run of the platform matrix, where it has to be
skipped without failing the check.

Author: abashev

.github/workflows/ci.yml

@@ -15,22 +15,23 @@ jobs:
     permissions:
       contents: read
       pull-requests: read # gh pr diff
-      security-events: write # the action reports its version check to code scanning
+      security-events: write # the code scanning upload
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
       - uses: ./
         with:
           mode: changed
+          code-scanning: true # with the permission: the upload has to go through
 
   # The action and the hook on every platform they support, with a file that is formatted and one that
   # is not. The repository itself has no Java files, so the tests write their own.
   test-platforms:
     name: Test on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     permissions:
-      contents: read # no security-events: the action has to do without the code scanning upload
+      contents: read # no security-events: the code scanning upload has to be skipped, not fail the check
     strategy:
       fail-fast: false
       matrix:
@@ -48,6 +49,7 @@ jobs:
         uses: ./
         with:
           mode: all
+          code-scanning: true # without the permission, see above
 
       - name: Write a file that is not formatted
         run: printf 'class Unformatted{int x;}\n' > Unformatted.java

README.md

@@ -22,7 +22,7 @@ v2 is for open-java-format 2.98.0.2 and later, which has a single style. A workf
 |-------|----------|---------|-------------|
 | `version` | yes | `2.98.0.6` | Version of the open-java-format native binary, one of those on [Maven Central](https://repo1.maven.org/maven2/dev/openjavaformat/open-java-format-native/) |
 | `mode` | no | `changed` | `changed` — only files from PR or push; `all` — every `.java` file in repo |
-| `code-scanning` | no | `true` | Report the version check to [code scanning](#code-scanning) as well; `false` keeps it to the log warning |
+| `code-scanning` | no | `false` | Also report the version check to [code scanning](#code-scanning); needs the `security-events: write` permission |
 
 ## How `mode: changed` works
 
@@ -34,7 +34,7 @@ v2 is for open-java-format 2.98.0.2 and later, which has a single style. A workf
 
 - If all files are formatted correctly → passes ✅
 - If any file has formatting issues → lists unformatted files and fails ❌
-- If a newer open-java-format release is out → warns in the job log, and raises a [code scanning alert](#code-scanning) when the job allows it
+- If a newer open-java-format release is out → warns in the job log, and raises a [code scanning alert](#code-scanning) when that is turned on
 
 Files are checked in the open-java-format style, the formatter's only style. When the check fails, fix locally with a native binary or the runnable jar from the [open-java-format releases](https://github.com/openjavaformat/open-java-format/releases):
 
@@ -90,9 +90,9 @@ jobs:
 
 ## Code scanning
 
-The action compares the `version` it runs with the latest [open-java-format release](https://github.com/openjavaformat/open-java-format/releases) and warns in the job log when a newer one is out. A log warning is easy to miss, so the check is also reported to code scanning: the action uploads a SARIF file with one alert while the version is behind, and with none once it is current, which closes the alert. The alert shows up under **Security → Code scanning** and in the **Code scanning results** check on pull requests, and points at the line of the workflow that names the version.
+The action compares the `version` it runs with the latest [open-java-format release](https://github.com/openjavaformat/open-java-format/releases) and warns in the job log when a newer one is out. A log warning is easy to miss, so the check can also be reported to code scanning: the action then uploads a SARIF file with one alert while the version is behind, and with none once it is current, which closes the alert. The alert shows up under **Security → Code scanning** and in the **Code scanning results** check on pull requests, and points at the line of the workflow that names the version.
 
-The upload needs the `security-events: write` permission, which a job gets like this:
+This is off by default, because the upload needs the `security-events: write` permission, which the default token does not have. To turn it on, set `code-scanning: true` and give the job the permission:
 
 ```yaml
 jobs:
@@ -101,18 +101,19 @@ jobs:
     permissions:
       contents: read
       pull-requests: read # mode: changed reads the files of the pull request
-      security-events: write # the action reports its version check to code scanning
+      security-events: write # the code scanning upload
     steps:
       - uses: actions/checkout@v7
 
       - uses: openjavaformat/open-java-format-action@v2
         with:
           version: '2.98.0.6'
+          code-scanning: true
 ```
 
-Without the permission the upload is skipped with a line in the log, the check passes as before, and the log warning stays. Code scanning is free on public repositories; a private repository needs [GitHub Code Security](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository) enabled. Pull requests from forks run with a read-only token and get the log warning only. To stop the upload altogether, set `code-scanning: false`.
+The `permissions` block replaces the default permissions of the job, so it has to name everything else the job needs, such as `contents: read` for the checkout. If the permission is missing anyway, the upload is skipped with a line in the log, the check passes as before, and the log warning stays. Code scanning is free on public repositories; a private repository needs [GitHub Code Security](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository) enabled. Pull requests from forks run with a read-only token and get the log warning only.
 
-One report per job is enough. When the job runs on a matrix, enable it on one leg only:
+One report per job is enough. When the job runs on a matrix, turn it on for one leg only:
 
 ```yaml
         with:

action.yml

@@ -16,9 +16,9 @@ inputs:
     required: false
     default: 'changed'
   code-scanning:
-    description: 'Report the version check to code scanning as well: "true" raises an alert under Security → Code scanning while a newer open-java-format is out, "false" keeps the check to the log warning. The upload needs the security-events: write permission and is skipped without it.'
+    description: 'Also report the version check to code scanning: "true" raises an alert under Security → Code scanning while a newer open-java-format is out. Off by default, because the upload needs the security-events: write permission; without it the upload is skipped.'
     required: false
-    default: 'true'
+    default: 'false'
 
 runs:
   using: 'composite'

example-usage.yml

@@ -10,10 +10,6 @@ jobs:
   format-check:
     name: Check Java formatting
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read # mode: changed reads the files of the pull request
-      security-events: write # the action reports its version check to code scanning
 
     steps:
       - uses: actions/checkout@v7