docs: clean up DSMS package and align legal pages #674
Workflow file for this run
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
| # Documentation Deployment Pipeline | |
| # | |
| # Separation of Concerns: | |
| # - CI: Quality gate in ci-quality-gates.yml validates docs build | |
| # - CD: This workflow handles deployment only (GitHub Pages + PR previews) | |
| # | |
| # Triggers: | |
| # - push to main with docs changes: Deploy to GitHub Pages | |
| # - PR with docs changes: Deploy preview to Surge.sh with comment | |
| # | |
| # Best Practices (2025): | |
| # - Path filtering prevents unnecessary runs | |
| # - Surge.sh teardown removes preview when PR closes | |
| # - Uses upload-pages-artifact@v3 and deploy-pages@v4 per GitHub requirements | |
| # - Docusaurus build caching for faster deploys | |
| name: CD / Docs | |
| on: | |
| push: | |
| branches: [main] | |
| paths: | |
| - "docs/**" | |
| - ".github/workflows/cd-docs.yml" | |
| # PR events for build/preview (path-filtered) | |
| pull_request: | |
| types: [opened, synchronize, reopened] | |
| paths: | |
| - "docs/**" | |
| - ".github/workflows/cd-docs.yml" | |
| workflow_dispatch: | |
| # Separate workflow for teardown - see cd-docs-teardown.yml | |
| # Path filters are unreliable for 'closed' events, so teardown is in a separate workflow | |
| concurrency: | |
| group: docs-deploy-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || github.ref }} | |
| cancel-in-progress: true | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| pull-requests: write | |
| statuses: write | |
| jobs: | |
| # Build docs for PR preview (baseUrl = '/') | |
| build-preview: | |
| name: Build (Preview) | |
| if: github.event_name == 'pull_request' | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 | |
| - name: Setup Node.js | |
| uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 | |
| with: | |
| node-version-file: ".node-version" | |
| cache: npm | |
| cache-dependency-path: docs/package-lock.json | |
| - name: Cache Docusaurus build | |
| uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 | |
| with: | |
| path: | | |
| docs/.docusaurus | |
| docs/node_modules/.cache | |
| key: ${{ runner.os }}-docusaurus-preview-${{ hashFiles('docs/package-lock.json') }}-${{ hashFiles('docs/**/*.md', 'docs/**/*.mdx', 'docs/**/*.ts') }} | |
| restore-keys: | | |
| ${{ runner.os }}-docusaurus-preview-${{ hashFiles('docs/package-lock.json') }}- | |
| ${{ runner.os }}-docusaurus-preview- | |
| - name: Install dependencies | |
| run: npm ci --no-audit --progress=false | |
| working-directory: docs | |
| - name: Build documentation (preview) | |
| run: npm run build | |
| working-directory: docs | |
| env: | |
| DOCUSAURUS_BASE_URL: "/" | |
| - name: Upload build artifact | |
| uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 | |
| with: | |
| name: docs-build-preview | |
| path: docs/build | |
| retention-days: 1 | |
| # Build docs for production (baseUrl = '/Hephaestus/') | |
| build-production: | |
| name: Build (Production) | |
| if: github.event_name == 'push' && github.ref == 'refs/heads/main' | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 | |
| - name: Setup Node.js | |
| uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 | |
| with: | |
| node-version-file: ".node-version" | |
| cache: npm | |
| cache-dependency-path: docs/package-lock.json | |
| - name: Cache Docusaurus build | |
| uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 | |
| with: | |
| path: | | |
| docs/.docusaurus | |
| docs/node_modules/.cache | |
| key: ${{ runner.os }}-docusaurus-prod-${{ hashFiles('docs/package-lock.json') }}-${{ hashFiles('docs/**/*.md', 'docs/**/*.mdx', 'docs/**/*.ts') }} | |
| restore-keys: | | |
| ${{ runner.os }}-docusaurus-prod-${{ hashFiles('docs/package-lock.json') }}- | |
| ${{ runner.os }}-docusaurus-prod- | |
| - name: Install dependencies | |
| run: npm ci --no-audit --progress=false | |
| working-directory: docs | |
| - name: Build documentation (production) | |
| run: npm run build | |
| working-directory: docs | |
| - name: Upload build artifact | |
| uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 | |
| with: | |
| name: docs-build-production | |
| path: docs/build | |
| retention-days: 1 | |
| # PR Preview: Deploy to Surge.sh with custom comment | |
| preview: | |
| name: PR Preview | |
| needs: build-preview | |
| if: github.event_name == 'pull_request' | |
| runs-on: ubuntu-latest | |
| env: | |
| PREVIEW_URL: ls1intum-hephaestus-docs-pr-${{ github.event.number }}.surge.sh | |
| steps: | |
| - name: Download build artifact | |
| uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 | |
| with: | |
| name: docs-build-preview | |
| path: docs-build | |
| - name: Install Surge | |
| run: npm install -g surge | |
| - name: Deploy to Surge.sh | |
| run: surge ./docs-build ${{ env.PREVIEW_URL }} --token ${{ secrets.SURGE_TOKEN }} | |
| - name: Comment on PR | |
| uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2 | |
| with: | |
| header: docs-preview | |
| message: | | |
| ## 📚 Documentation Preview | |
| This PR includes documentation changes. A preview has been deployed: | |
| 🔗 **[View Docs Preview](https://${{ env.PREVIEW_URL }})** | |
| <sub>Preview for commit ${{ github.event.pull_request.head.sha }}. Updates automatically on new commits.</sub> | |
| - name: Create Docs Preview status check | |
| uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 | |
| with: | |
| script: | | |
| const sha = context.payload.pull_request?.head?.sha || context.sha; | |
| await github.rest.repos.createCommitStatus({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| sha: sha, | |
| state: 'success', | |
| target_url: 'https://${{ env.PREVIEW_URL }}', | |
| description: 'Click Details to view Docs Preview', | |
| context: 'Preview / Docs' | |
| }); | |
| # Teardown handled by cd-docs-teardown.yml (separate workflow for reliability) | |
| # Production: Deploy to GitHub Pages | |
| deploy: | |
| name: GitHub Pages | |
| needs: build-production | |
| if: github.event_name == 'push' && github.ref == 'refs/heads/main' | |
| runs-on: ubuntu-latest | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Download build artifact | |
| uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 | |
| with: | |
| name: docs-build-production | |
| path: docs-build | |
| - name: Upload to GitHub Pages | |
| uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3 | |
| with: | |
| path: docs-build | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4 |