wip: fix workflow trigger + docs to release/[0-9]*.[0-9]*.[0-9]*

Author: simbo1905

.github/workflows/release-on-tag.yml

@@ -0,0 +1,72 @@
+name: Release on Tag
+
+on:
+  push:
+    tags:
+      - 'release/[0-9]*.[0-9]*.[0-9]*'
+
+permissions:
+  contents: write    # push tags, push commits
+  pull-requests: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Java, Central creds and GPG
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+          server-id: central
+          server-username: CENTRAL_USERNAME
+          server-password: CENTRAL_PASSWORD
+          gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
+          gpg-passphrase: ${{ secrets.GPG_PASSPHRASE }}
+
+      - name: Create GitHub Release with notes
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          generate_release_notes: true
+
+      - name: Build and Deploy to Central
+        env:
+          CENTRAL_USERNAME: ${{ secrets.CENTRAL_USERNAME }}
+          CENTRAL_PASSWORD: ${{ secrets.CENTRAL_PASSWORD }}
+        run: |
+          mvn -B -ntp clean deploy
+
+      - name: Configure Git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Create branch from tag for PR
+        id: prbranch
+        run: |
+          BRANCH_NAME="release-bot-$(date +%Y%m%d-%H%M%S)"
+          git checkout -B "$BRANCH_NAME" $GITHUB_SHA
+          git push origin "$BRANCH_NAME"
+          echo "branch=$BRANCH_NAME" >> "$GITHUB_OUTPUT"
+
+      - name: Open PR back to main
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh pr create \
+            --title "chore: merge release ${{ github.ref_name }} to main" \
+            --body "Automated PR created from tag ${{ github.ref_name }}." \
+            --base main \
+            --head "${{ steps.prbranch.outputs.branch }}" \
+          || echo "PR already exists or nothing to compare"

AGENTS.md

@@ -81,8 +81,8 @@ Prerequisites
 - Optional: alias `mvn` to `mvnd` for faster builds (see note at top).
 
 Automated Release (preferred)
-- Push a tag named `releases/X.Y.Z` (semver, no leading `v`).
-- The workflow `.github/workflows/release-on-branch.yml` will:
+- Push a tag named `release/X.Y.Z` (semver, no leading `v`).
+- The workflow `.github/workflows/release-on-tag.yml` will:
   - Create a GitHub Release for that tag with autogenerated notes.
   - Build and deploy artifacts to Maven Central (Central Publishing plugin).
   - Create a branch `release-bot-YYYYMMDD-HHMMSS` at the tagged commit and open a PR back to `main` (no version bumps).
@@ -105,6 +105,11 @@ Notes
 - To skip signing locally for quick checks, add `-Dgpg.skip=true`.
 - The Central Publishing plugin configuration lives in the parent `pom.xml` and applies to all modules.
 
+Secrets Helper
+- Use `./scripts/setup-release-secrets.zsh` to set GitHub Actions secrets (`CENTRAL_USERNAME`, `CENTRAL_PASSWORD`, `GPG_PRIVATE_KEY`, `GPG_PASSPHRASE`).
+- The script can auto-detect a signing key if neither `GPG_KEY_ID` nor `GPG_PRIVATE_KEY` is provided.
+- List keys explicitly with: `gpg --list-secret-keys --keyid-format=long`.
+
 ## Python Usage (Herodoc, 3.2-safe)
 - Prefer `python3` with a heredoc over Perl/sed for non-trivial transforms.
 - Target ancient Python 3.2 syntax: no f-strings, no fancy deps.

RELEASE-GIST.md

@@ -1,6 +1,6 @@
 # Tag-Triggered Maven Central Release (GitHub Actions)
 
-- Trigger: push tag `releases/X.Y.Z` (no leading `v`).
+- Trigger: push tag `release/X.Y.Z` (no leading `v`).
 - CI creates a GitHub Release from the tag, then deploys to Maven Central.
 - CI opens a PR back to `main` from `release-bot-YYYYMMDD-HHMMSS` (no version bumps).
 
@@ -11,7 +11,7 @@ name: Release on Tag
 on:
   push:
     tags:
-      - 'releases/*'
+      - 'release/[0-9]*.[0-9]*.[0-9]*'
 permissions:
   contents: write
   pull-requests: write
@@ -62,7 +62,7 @@ jobs:
 - CENTRAL_USERNAME, CENTRAL_PASSWORD (Central Portal token)
 - GPG_PRIVATE_KEY (ASCII-armored secret key), GPG_PASSPHRASE
 
-zsh helper (uses gh, gpg):
+zsh helper (uses gh, gpg) — auto-detects a signing key if not provided:
 
 ```zsh
 #!/usr/bin/env zsh
@@ -72,13 +72,17 @@ export CENTRAL_PASSWORD=your_pass
 export GPG_PASSPHRASE=your_passphrase
 export GPG_KEY_ID=YOUR_KEY_ID   # or export GPG_PRIVATE_KEY="$(gpg --armor --export-secret-keys YOUR_KEY_ID)"
 ./scripts/setup-release-secrets.zsh
+
+# If you don't set GPG_KEY_ID or GPG_PRIVATE_KEY, the script tries to
+# auto-detect a signing key. To see candidates explicitly:
+gpg --list-secret-keys --keyid-format=long
 ```
 
 ## Trigger a Release
 
 ```bash
-git tag 'releases/0.1.0'
-git push origin 'releases/0.1.0'
+git tag 'release/0.1.0'
+git push origin 'release/0.1.0'
 ```
 
 ## Publish this doc as a Gist