Deploy Documentation #160
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
| # Workflow for deploying versioned documentation to GitHub Pages. | |
| # Site content (src/site/, pom.xml) lives in THIS repo. | |
| # Java source code is checked out from the monorepo (github/copilot-sdk) at a release tag. | |
| name: Deploy Documentation | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| version: | |
| description: 'Version to build in tag format (e.g., java/v1.0.1-java.0). The java/v prefix is stripped to form the site directory name.' | |
| type: string | |
| required: true | |
| publish_as_latest: | |
| description: 'Also publish as /latest/?' | |
| type: boolean | |
| default: true | |
| monorepo_tag: | |
| description: 'Tag in github/copilot-sdk monorepo (e.g., java/v1.0.1-java.0)' | |
| type: string | |
| required: true | |
| permissions: | |
| contents: write | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| build-and-deploy: | |
| runs-on: ubuntu-latest | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| # 0. Validate inputs | |
| - name: Validate inputs | |
| run: | | |
| VERSION="${{ inputs.version }}" | |
| if [[ -z "${VERSION}" ]]; then | |
| echo "::error::version input is required" | |
| exit 1 | |
| fi | |
| if [[ "${VERSION}" == *"../"* ]]; then | |
| echo "::error::version must not contain '../'" | |
| exit 1 | |
| fi | |
| TAG="${{ inputs.monorepo_tag }}" | |
| if [[ "${TAG}" != java/v* ]]; then | |
| echo "::error::monorepo_tag must start with 'java/v' (got: '${TAG}')" | |
| exit 1 | |
| fi | |
| # 1. Checkout this (standalone) repo — has src/site/, pom.xml, templates | |
| - name: Checkout standalone repo | |
| uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 | |
| # 2. Checkout the monorepo at the release tag (for Java source code) | |
| - name: Checkout monorepo at release tag | |
| uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 | |
| with: | |
| repository: github/copilot-sdk | |
| ref: ${{ inputs.monorepo_tag }} | |
| path: monorepo | |
| # 3. Set up JDK | |
| - name: Set up JDK 25 | |
| uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5 | |
| with: | |
| java-version: '25' | |
| distribution: 'microsoft' | |
| cache: 'maven' | |
| # 4. Compile monorepo Java source (needed for javadoc, SpotBugs, etc.) | |
| - name: Compile monorepo Java source | |
| working-directory: monorepo/java | |
| run: | | |
| echo "Compiling Java source from tag ${{ inputs.monorepo_tag }}" | |
| mvn clean compile test -DskipTests=false -Dcheckstyle.skip=true -B | |
| # 5. Build the Maven Site using THIS repo's pom.xml + src/site/ | |
| - name: Build documentation site | |
| run: | | |
| echo "Building site for version ${{ env.DEPLOY_VERSION }}" | |
| mvn site -Dsite.version=${{ inputs.version }} -B | |
| # 6. Checkout gh-pages branch from this (standalone) repo | |
| - name: Checkout gh-pages branch | |
| uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 | |
| with: | |
| ref: gh-pages | |
| path: site | |
| continue-on-error: true | |
| - name: Initialize site if needed | |
| run: | | |
| if [ ! -d "site/.git" ]; then | |
| rm -rf site | |
| mkdir -p site | |
| cd site | |
| git init | |
| git checkout -b gh-pages | |
| git remote add origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" | |
| fi | |
| # 7. Copy generated site to version directory | |
| - name: Deploy version documentation | |
| run: | | |
| echo "Deploying documentation for version ${DEPLOY_VERSION}" | |
| rm -rf "site/${DEPLOY_VERSION}" | |
| mkdir -p "site/${DEPLOY_VERSION}" | |
| cp -r target/site/* "site/${DEPLOY_VERSION}/" | |
| # Also publish as /latest/ if requested | |
| if [[ "${{ inputs.publish_as_latest }}" == "true" ]]; then | |
| rm -rf "site/latest" | |
| mkdir -p "site/latest" | |
| cp -r target/site/* "site/latest/" | |
| fi | |
| # 8. Copy version index page from templates | |
| - name: Copy version index page | |
| run: | | |
| cp .github/templates/index.html site/index.html | |
| cp .github/templates/styles.css site/styles.css | |
| # 9. Update version list based on directories present in gh-pages | |
| - name: Update version list from deployed directories | |
| run: | | |
| cd site | |
| MONOREPO_URL="https://github.com/github/copilot-sdk" | |
| STANDALONE_URL="https://github.com/github/copilot-sdk-java" | |
| VERSIONS=$(ls -d */ 2>/dev/null | sed 's|/||' | grep -E '^[0-9]+\.[0-9]+' | sort -Vr || true) | |
| HAS_SNAPSHOT=$([ -d "snapshot" ] && echo "true" || echo "false") | |
| CURRENT_HTML="" | |
| OLDER_HTML="" | |
| IS_FIRST_VERSION="true" | |
| if [ "$HAS_SNAPSHOT" = "true" ]; then | |
| CURRENT_HTML+='<li><span class="version-name">Development (main branch)</span><span class="version-links"><a href="./snapshot/" class="doc-link">documentation ↗</a><a href="'"${MONOREPO_URL}"'/blob/main/java/CHANGELOG.md" class="release-link">changelog ↗</a><span class="badge snapshot">snapshot</span></span></li>' | |
| fi | |
| for v in $VERSIONS; do | |
| RELEASE_URL="${MONOREPO_URL}/releases/tag/java/v${v}" | |
| if [ "$IS_FIRST_VERSION" = "true" ]; then | |
| CURRENT_HTML+='<li class="latest-version"><span class="version-name">Version '"$v"'</span><span class="version-links"><a href="./'"$v"'/" class="doc-link">documentation ↗</a><a href="'"$RELEASE_URL"'" class="release-link">release notes ↗</a><span class="badge latest">latest</span></span></li>' | |
| IS_FIRST_VERSION="false" | |
| else | |
| OLDER_HTML+='<li><span>'"$v"'</span><span class="older-links"><a href="./'"$v"'/" class="doc-link">documentation ↗</a><a href="'"$RELEASE_URL"'" class="release-link">release notes ↗</a></span></li>' | |
| fi | |
| done | |
| sed -i "s|<!-- CURRENT_VERSIONS_PLACEHOLDER -->|$CURRENT_HTML|" index.html | |
| sed -i "s|<!-- OLDER_VERSIONS_PLACEHOLDER -->|$OLDER_HTML|" index.html | |
| # 10. Overlay custom JaCoCo CSS | |
| - name: Overlay custom JaCoCo CSS | |
| run: | | |
| cd site | |
| JACOCO_CSS="../src/site/jacoco-resources/report.css" | |
| if [ -f "${JACOCO_CSS}" ]; then | |
| for dir in */jacoco/jacoco-resources; do | |
| if [ -d "$dir" ]; then | |
| cp "${JACOCO_CSS}" "$dir/report.css" | |
| echo "Overlaid JaCoCo CSS in $dir" | |
| fi | |
| done | |
| fi | |
| # 11. Push to gh-pages | |
| - name: Deploy to GitHub Pages | |
| run: | | |
| cd site | |
| git config user.name "github-actions[bot]" | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| git remote set-url origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" 2>/dev/null || \ | |
| git remote add origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" | |
| git add -A | |
| COMMIT_MSG="Deploy documentation: ${DEPLOY_VERSION} (from ${{ inputs.monorepo_tag }})" | |
| git diff --staged --quiet || git commit -m "$COMMIT_MSG" | |
| git push -u origin gh-pages --force | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Setup Pages | |
| uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 | |
| with: | |
| path: 'site' | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0 |