Deploy Versioned Javadoc (Manual Trigger) #180
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Deploy Versioned Javadoc (Manual Trigger) | |
| # Select the target TAG where to run the workflow from. | |
| # This TAG name becomes the subdirectory under branch gh-pages/docs/${TAG} | |
| # where the javadocs will be copied to. | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| tag_ref: | |
| description: 'Existing Git Tag to deploy (e.g., 1.0.0):' | |
| required: true | |
| default: '99.0.0' # unlikely to conflict if accidentally used. Can be left blank | |
| jobs: | |
| build-and-deploy-javadoc: | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: write | |
| steps: | |
| - name: Checkout Code at Specified Tag | |
| uses: actions/checkout@v5 | |
| with: | |
| ref: ${{ github.event.inputs.tag_ref }} # from manual trigger input | |
| fetch-depth: 0 | |
| - name: Set up JDK | |
| uses: actions/setup-java@v4 | |
| with: | |
| java-version: '25' | |
| distribution: 'temurin' | |
| cache: 'maven' | |
| - name: Build and Generate Javadoc # POM is configured to output to target/site/apidocs | |
| run: mvn javadoc:javadoc | |
| - name: Deploy Javadoc via Worktree | |
| env: | |
| TAG_NAME: ${{ github.event.inputs.tag_ref }} | |
| run: | | |
| # 1. Initialize error tracking | |
| EXIT_CODE=0 | |
| # 2. Configure Git Identity | |
| git config user.email "noreply@github.com" | |
| git config user.name "github-actions[bot]" | |
| # 3. Ensure gh-pages exists and is fetched | |
| git fetch origin gh-pages --depth=1 || git branch gh-pages | |
| # 4. Create worktree for the gh-pages branch in a separate folder | |
| git worktree add ./gh-pages-dir origin/gh-pages | |
| # 5. Deployment Logic in a subshell to capture exit code | |
| ( | |
| set -e # Exit subshell on any internal error | |
| TARGET_PATH="gh-pages-dir/docs/$TAG_NAME" # target directory inside the worktree | |
| mkdir -p "$TARGET_PATH" | |
| cp -a target/site/apidocs/. "$TARGET_PATH/" | |
| cd gh-pages-dir | |
| git add . | |
| if git diff --staged --quiet; then | |
| echo "No changes detected for Javadoc $TAG_NAME." | |
| else | |
| git commit -m "Manual Javadoc deployment for tag $TAG_NAME" | |
| git push origin gh-pages | |
| fi | |
| ) || EXIT_CODE=$? | |
| # 6. Cleanup (Always runs) | |
| echo "Cleaning up worktree..." | |
| git worktree remove --force ./gh-pages-dir || true | |
| # 7. Final exit based on subshell success | |
| exit $EXIT_CODE | |
| - name: Confirm Deployment | |
| if: success() | |
| run: echo "Javadoc for ${{ github.event.inputs.tag_ref }} is now live on gh-pages." |