ci: implement automated releasing

[karel-rehor]

Proposed Changes

Sets up automated releasing.

1. For uploads to Maven Central replaces nexus-staging-maven-plugin with recommended central-publishing-maven-plugin
2. Introduces a new GitHub Actions workflow maven-release.yml
   1. Verifies the action environment to ensure that all required variables are present and valid.
   2. Executes the on-release.sh script which ensures values in pom.xml files and documentation match the release version and tag.
   3. Triggers the release process, which packages and then uploads the module to Maven Central.
   4. Automatically generates and then publishes GitHub pages. This will trigger a second GitHub Action "pages build and deployment".
   5. Automatically updates CHANGELOG.md and pom.xml with the next release version. e.g. in pom.xml 1.11.0 is incremented to 1.12.0-SNAPSHOT.

Note this requires up-to-date values for action secrets (already configured in project - but not fully verified)

• GPG_PASSPHRASE
• GPG_PRIVATE_KEY (in tests using key for karel-rehor@users.noreply.github.com which is password protected and without expiration, so it could be used in production.)
• SONATYPE_PASSWORD
• SONATYPE_USERNAME

Checklist

• CHANGELOG.md updated
• Rebased/mergeable
• [ ] A test has been added if appropriate N.A.
• Tests pass
• Commit messages are conventional
• Sign CLA (if not already signed)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.73%. Comparing base (8243f59) to head (994733a).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #446   +/-   ##
=======================================
  Coverage   88.73%   88.73%           
=======================================
  Files          21       21           
  Lines        1553     1553           
  Branches      281      281           
=======================================
  Hits         1378     1378           
  Misses         77       77           
  Partials       98       98           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[bednar]

Security review: changes are required before this PR can be approved.

[bednar]

Security: Please run this job through a protected GitHub Actions environment named release, with required reviewers, self-review disabled, and deployment restricted to release tags matching v*. Move GPG_PRIVATE_KEY, GPG_PASSPHRASE, SONATYPE_USERNAME, and SONATYPE_PASSWORD to secrets of that environment.

Currently, the job receives all signing and publishing credentials immediately after a release is published and then executes the script and Maven configuration from the checked-out tag. A compromised or incorrectly created release tag could therefore exfiltrate these credentials before a second person reviews the release.

See GitHub documentation on environments, required reviewers, and branch/tag restrictions.

[bednar]

Security review: changes are required for the checkout and publishing authentication flow.

[bednar]

Security: Please set persist-credentials: false for this checkout. The default checkout behavior stores the contents: write token in .git/config while the release-tag script and Maven plugins are being executed. A compromised release tag or Maven plugin could read the token and push unauthorized changes to the repository.

Because this workflow later performs both git push and documentation publishing, authentication should be configured explicitly only in the steps that require it:

- name: Checkout
  uses: actions/checkout@v6
  with:
    persist-credentials: false

- name: Prepare next cycle
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    # ...
    gh auth setup-git
    git push --set-upstream origin "${NEXT_RELEASE_BRANCH}"

For Maven documentation publishing, please add a token-free scm-settings.xml template:

<settings>
  <servers>
    <server>
      <id>github</id>
      <username>x-access-token</username>
      <password>${env.GITHUB_TOKEN}</password>
    </server>
  </servers>
</settings>

Then use it only in the publishing step:

- name: Build documentation
  run: mvn clean site site:stage -DskipTests

- name: Publish documentation
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    mvn -s ./scm-settings.xml --batch-mode \
      scm-publish:publish-scm \
      -Dscmpublish.serverId=github

Please also remove GITHUB_TOKEN from the job-level environment. This keeps the token unavailable during the release build and documentation generation. Maven supports environment-variable interpolation in settings.xml; see the Maven Settings Reference and scm-publish authentication documentation.

[karel-rehor]

updated

[bednar]

Security review: the GPG passphrase must not be persisted across subsequent workflow steps.

[bednar]

Please do not persist GPG_PASSPHRASE through $GITHUB_ENV. Set it only in the release/signing step, where it is required. Moving the secret to a protected environment controls when it becomes available, but $GITHUB_ENV still makes it available to every subsequent step in the job, including the next-cycle and documentation steps.

For example:

- name: Release
  env:
    GPG_PASSPHRASE_PRELIM: ${{ secrets.GPG_PASSPHRASE }}
    SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
    SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}
  run: |
    if [[ "$GPG_PASSPHRASE_PRELIM" == "EMPTY" ]]; then
      GPG_PASSPHRASE=""
    else
      GPG_PASSPHRASE="$GPG_PASSPHRASE_PRELIM"
    fi
    export GPG_PASSPHRASE

    mvn release:perform \
      -Dgoals=deploy \
      -s ./deploy-settings.xml \
      -Darguments="-DskipTests -DskipITs -DperformRelease=true"

Please remove the corresponding GPG_PASSPHRASE write to $GITHUB_ENV and keep the signing and Maven Central credentials scoped to this release step.

[karel-rehor]

sensitive secrets and environment variables no longer echoed into GITHUB_ENV