chore: fix the Javadocs publishing action

.github/workflows/publish.yml

@@ -35,10 +35,21 @@ jobs:
       pages: write
 
     steps:
-      - name: Checkout code
+      # Checkout the main and gh-pages branches. Main is used to generate the Javadoc, gh-pages stores the output Javadoc.
+      - name: Checkout main branch
+        uses: actions/checkout@v4
+        with:
+          path: main
+          persist-credentials: true
+          fetch-depth: 0
+
+      - name: Checkout gh-pages branch
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          path: gh-pages
+          persist-credentials: true
+          ref: gh-pages
 
       - name: Set up Java 11
         uses: actions/setup-java@v4
@@ -47,17 +58,12 @@ jobs:
           distribution: 'temurin'
           cache: 'maven'
 
-      - name: Set artifact version to ${{ github.ref_name }}
-        run: mvn -B versions:set -DnewVersion=${{ github.ref_name}} -DgenerateBackupPoms=false
-
       - name: Publish Javadocs
         env:
-          GH_TOKEN: ${{ secrets.GH_TOKEN }}
           GITHUB_REPO_SLUG: ${{ github.repository }}
           GITHUB_TAG: ${{ github.ref_name}}
         run: |
-          mvn clean javadoc:aggregate --settings build/.github.settings.xml
-          build/publishJavadoc-gha.sh
+          main/build/publishJavadoc-gha.sh
 
   publish-maven-central:
     # Requires GPG_KEYNAME, GPG_PRIVATE_KEY, GPG_PASSPHRASE, CP_USERNAME, CP_PASSWORD

build/publishJavadoc-gha.sh

@@ -1,43 +1,41 @@
 #!/bin/bash
 
+set -e
+
 # Required environment variables:
-# GH_TOKEN
 # GITHUB_REPO_SLUG
 # GITHUB_TAG
 
 printf "\n>>>>> Publishing javadoc for release build: repo=%s tag=%s\n" ${GITHUB_REPO_SLUG} ${GITHUB_TAG}
 
-printf "\n>>>>> Cloning repository's gh-pages branch into directory 'gh-pages'\n"
-rm -fr ./gh-pages
-# TODO this approach doesnt work when using GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} in workflow
-# git config --global user.email "github-actions[bot]@users.noreply.github.com"
-# git config --global user.name "github-actions[bot]"
-# git clone --branch=gh-pages https://${GH_TOKEN}@github.com/${GITHUB_REPO_SLUG}.git gh-pages
-# TODO For now using a hardcoded token in the repo settings secrets, tied to brian.gleeson@ie.ibm.com
-git clone --branch=gh-pages https://${GH_TOKEN}@github.com/${GITHUB_REPO_SLUG}.git gh-pages
-printf "\n>>>>> Finished cloning...\n"
-
-gh auth status
-
-printf "\n>>>>> Finished checking gh auth status...\n"
+# Open the "main" dir, containing the checked out main branch
+pushd main
 
-pushd gh-pages
+printf "\n>>>>> Generating Javadoc...\n"
+mvn -B versions:set -DnewVersion="${GITHUB_TAG}" -DgenerateBackupPoms=false
+mvn -B -ntp clean javadoc:aggregate --settings build/.github.settings.xml
+printf "\n>>>>> Finished generating Javadoc...\n"
 
 # Create a new directory for this branch/tag and copy the javadocs there.
 printf "\n>>>>> Copying javadocs to new directory: docs/%s\n" ${GITHUB_TAG}
-rm -rf docs/${GITHUB_TAG}
-mkdir -p docs/${GITHUB_TAG}
-cp -rf ../target/site/apidocs/* docs/${GITHUB_TAG}
+rm -rf ../gh-pages/docs/${GITHUB_TAG}
+mkdir -p ../gh-pages/docs/${GITHUB_TAG}
+cp -rf target/site/apidocs/* ../gh-pages/docs/${GITHUB_TAG}
+
+# Return to root dir, then open "gh-pages" dir
+popd 
+pushd gh-pages
 
 printf "\n>>>>> Generating gh-pages index.html...\n"
-../build/generateJavadocIndex.sh > index.html
+../main/build/generateJavadocIndex.sh > index.html
 
 printf "\n>>>>> Committing new javadoc...\n"
+git config user.email "github-actions[bot]@users.noreply.github.com"
+git config user.name "github-actions[bot]"
 git add -f .
 printf "\n>>>>> Added files...\n"
 git commit -m "docs: latest javadoc for ${GITHUB_TAG}"
 printf "\n>>>>> Committed changes...\n"
-git remote -v
 git push -f origin gh-pages
 printf "\n>>>>> Pushed changes...\n"