Follow open-java-format releases from CI

Until now every open-java-format release meant changing ojf_version in
zensical.toml by hand and pushing. The "Follow open-java-format
releases" workflow now does that once an hour: when the latest GitHub
release differs from ojf_version, it changes that line, pushes the
bump to main and runs Documentation on it to deploy the site.

Documentation gains workflow_dispatch for that run, because a push made
with the workflow's own token starts no push-triggered workflow, and
it deploys on any run that is not a pull request.

The GitHub Action page's table now writes the action's default as
{{ ojf_version }}: the action follows the releases the same way since
openjavaformat/open-java-format-action@6e1a02b, so the two no longer
drift apart.

Author: abashev

.github/workflows/docs.yml

@@ -7,6 +7,7 @@ on:
     branches:
       - main
   pull_request:
+  workflow_dispatch: # Follow open-java-format releases runs this on the bump it pushes
 
 permissions:
   contents: read
@@ -34,15 +35,16 @@ jobs:
       - name: Build the site
         run: zensical build --clean --strict
 
+      # A pull request is only built. A push and the dispatched run above deploy.
       - name: Upload the Pages artifact
-        if: github.event_name == 'push'
+        if: github.event_name != 'pull_request'
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: site
 
   deploy:
     name: deploy
-    if: github.event_name == 'push'
+    if: github.event_name != 'pull_request'
     needs: build
     runs-on: ubuntu-latest
     permissions:

.github/workflows/follow-releases.yml

@@ -0,0 +1,58 @@
+name: Follow open-java-format releases
+
+# The pages install the formatter version that zensical.toml names as ojf_version. Once an hour this
+# compares it with the latest release of openjavaformat/open-java-format. When a new release is out,
+# that line is changed, the result is pushed to main, and Documentation is run on it to deploy the
+# site. That run has to be explicit: a push made with the workflow's own token starts no
+# push-triggered workflow. Nothing but that line changes: the pages name earlier versions as
+# history, on Migrate for instance, and those stay as written.
+
+on:
+  schedule:
+    - cron: '17 * * * *' # not on the hour, when GitHub's schedule queue is longest
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  bump:
+    name: Bump to the latest release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # push to main
+      actions: write # run Documentation
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Bump when a new release is out
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          current=$(sed -n 's/^ojf_version = "\(.*\)"$/\1/p' zensical.toml)
+          release=$(gh release view --repo openjavaformat/open-java-format --json tagName,publishedAt)
+          latest=$(jq -r .tagName <<< "$release")
+          published=$(jq -r '.publishedAt[:10]' <<< "$release")
+          if [ "$latest" = "$current" ]; then
+            echo "Already on $current."
+            exit 0
+          fi
+
+          # The dots are escaped so that sed takes them literally.
+          sed -i "s/^ojf_version = \"${current//./\\.}\"$/ojf_version = \"$latest\"/" zensical.toml
+          git diff
+
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git commit --all --quiet --file - <<COMMIT
+          Install open-java-format $latest
+
+          The pages install $latest, which openjavaformat/open-java-format
+          released on $published. Made by the "$GITHUB_WORKFLOW" workflow:
+          $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID
+          COMMIT
+          gh auth setup-git
+          git push origin HEAD:main
+          gh workflow run docs.yml --ref main

docs/get-started/github-actions.md

@@ -29,7 +29,7 @@ the files that are not formatted and fails the job if there are any.
 
 | Input | Default | Meaning |
 | --- | --- | --- |
-| `version` | `2.98.0.5` | The formatter version to download |
+| `version` | `{{ ojf_version }}` | The formatter version to download |
 | `mode` | `changed` | `changed` checks the files of the pull request or push, `all` checks every `.java` file |
 
 A workflow that still pins 2.98.0.1 stays on `@v1`: that version needs the `--ojf` flag, which `@v2`