ci: validate docs on PR and only deploy Pages on release #43
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
| name: Build and Deploy Documentation Site | |
| on: | |
| push: | |
| branches: [ main ] | |
| paths: [ 'docs/**', 'mkdocs.yml', 'mkdocs.shared.yml', 'mkdocs.production.yml', '.github/workflows/build-docs.yml' ] | |
| pull_request: | |
| branches: [ main ] | |
| paths: [ 'docs/**', 'mkdocs.yml', 'mkdocs.shared.yml', 'mkdocs.production.yml', '.github/workflows/build-docs.yml' ] | |
| release: | |
| types: [ published ] | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| defaults: | |
| run: | |
| shell: bash | |
| jobs: | |
| # Builds the production site and uploads it as a Pages artifact. Only needs to run when the | |
| # artifact might actually be deployed (see the 'deploy' job below). | |
| build: | |
| if: ${{ github.event_name == 'release' || github.event_name == 'workflow_dispatch' }} | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout Repository | |
| uses: actions/checkout@v7 | |
| with: | |
| fetch-depth: 0 | |
| - name: Install Python | |
| uses: actions/setup-python@v6 | |
| with: | |
| python-version: 3.x | |
| - name: Install mkdocs | |
| run: pip install mkdocs mkdocs-mermaid2-plugin | |
| - name: Generate site | |
| run: mkdocs build -f ./mkdocs.production.yml | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@v5 | |
| with: | |
| path: ./site | |
| # Validates the docs site without ever deploying it: a strict mkdocs build catches broken | |
| # internal links/anchors/nav entries, and lychee catches dead external links. Runs on every PR | |
| # (and push to main, for parity) so problems are caught before they reach a release. --strict is | |
| # deliberately only used here (not baked into mkdocs.production.yml or used by the 'build' job | |
| # above) so that a stray warning can never block the artifact that 'deploy' publishes. | |
| validate: | |
| if: ${{ github.event_name == 'pull_request' || github.event_name == 'push' || github.event_name == 'workflow_dispatch' }} | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout Repository | |
| uses: actions/checkout@v7 | |
| - name: Install Python | |
| uses: actions/setup-python@v6 | |
| with: | |
| python-version: 3.x | |
| - name: Install mkdocs | |
| run: pip install mkdocs mkdocs-mermaid2-plugin | |
| - name: Validate site (strict build) | |
| run: mkdocs build --strict -f ./mkdocs.production.yml | |
| - name: Check for broken links | |
| uses: lycheeverse/lychee-action@v2 | |
| with: | |
| args: >- | |
| --no-progress | |
| --scheme https --scheme http | |
| --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36" | |
| --exclude "^https://dev\.mysql\.com/" | |
| --exclude "^https://developers\.facebook\.com/" | |
| 'docs/**/*.md' | |
| token: ${{ secrets.GITHUB_TOKEN }} | |
| fail: true | |
| # Only deploys to GitHub Pages on a published release (or a manual dispatch against a release | |
| # tag), never on every push to main and never on a plain feature-branch dispatch. | |
| deploy: | |
| if: >- | |
| ${{ github.event_name == 'release' || | |
| (github.event_name == 'workflow_dispatch' && startsWith(github.ref, 'refs/tags/')) }} | |
| needs: build | |
| permissions: | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Setup Pages | |
| uses: actions/configure-pages@v6 | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v5 |