Publishing a Material for MkDocs site to Azure, with automatic branch/PR preview deployments

public
,
1

After some experimentation I have a GitHub Action which works for multiple deployments from PRs and branches on GitHub, to an Azure Static Web App. It means that we can preview any PRs or branches in a deployment before we merge into the live site.

The GitHub Action workflow is based on the CI workflow which Azure automatically writes into the repo when you set up a Static Web App running from GitHub Actions, but with actions/checkout and actions/setup-python updated to v3 and v4 respectively, and the section for MkDocs installation and build inserted.

Placeholders

The PRODUCTION_BRANCH variable above is the name of the branch which is considered to be your main Production branch. All other branches will be considered to be PRs or branches, and will be deployed to a named static web app. The URL for thiss will be automatically commented into the PR discussion.

name: ALL-BRANCHES-ALL-PRs-build-and-deploy-to-azure.yml

on:
  push:
    branches:
      - '**'
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - =PRODUCTION_BRANCH=
permissions:
  contents: write
  pull-requests: write  # this permission is required in order to allow PR comment with staging URL
jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy to Azure
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install git+https://${{ secrets.MATERIAL_FOR_MKDOCS_ACCESS_TOKEN }}@github.com/squidfunk/mkdocs-material-insiders.git
      - run: pip install -r requirements.txt
      - run: mkdocs build
      - name: Upload to Azure
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
          action: "upload"
          production_branch: "=PRODUCTION_BRANCH="
          app_location: "" # App source code path relative to repository root
          api_location: "" # Api source code path relative to repository root - optional
          output_location: "site" # Built app content directory, relative to app_location - optional

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          action: "close"

The user will need to insert their AZURE_STATIC_WEB_APPS_API_TOKEN into the repo Secrets in GitHub.

Related links

1 Like