ci.yml

name: CI

on:
  push:
    branches:
      - main
    paths:
      # mkdocs source
      - "src/**"
      - "mkdocs.yml"
      # poetry source
      - "pyproject.toml"
      - "poetry.lock"
      # run updated workflows
      - ".github/workflows/**"
  pull_request:
    paths:
      - "src/**"
      - "mkdocs.yml"
      - "pyproject.toml"
      - "poetry.lock"
      - ".github/workflows/**"
  workflow_dispatch:
    inputs:
      do_release:
        description: "Create a release?"
        default: false
        type: boolean
  # Run the workflow every Monday at 8am
  schedule:
    - cron: "0 8 * * 1"

concurrency:
  group: ci-${{ github.ref_name }}
  cancel-in-progress: true

env:
  artifact: site

jobs:
  ############################################################
  # Lints Markdown files
  ############################################################
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: xt0rted/markdownlint-problem-matcher@v3
      - uses: DavidAnson/markdownlint-cli2-action@v16
        continue-on-error: true

  ############################################################
  # Build the site with MkDocs
  ############################################################
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          lfs: true # images are stored with LFS
      # From: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#caching-packages
      - name: Install poetry
        run: pipx install poetry==1.7.1
      - uses: actions/setup-python@v5
        with:
          python-version-file: .python-version
          cache: poetry
      # Install with --no-root because project does produce a python package
      - run: poetry install --no-root
      # From: https://github.com/squidfunk/mkdocs-material/blob/master/docs/publishing-your-site.md#with-github-actions
      - name: Setup MkDocs cache
        uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ github.run_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - name: Build site with MkDocs
        run: poetry run mkdocs build
      - name: Upload build artifact
        id: upload
        uses: actions/upload-artifact@v4
        with:
          name: ${{ env.artifact }}
          path: site/
          retention-days: 1

  ############################################################
  # Deploys the site to GitHub Pages
  ############################################################
  deploy:
    needs: build
    if: ${{ github.ref_name == github.event.repository.default_branch && ! inputs.do_release }}
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    env:
      # directory that artifact is downloaded to
      # and deployed from
      workdir: "site"
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write # to deploy to pages
      id-token: write # unsure
      pull-requests: write # to leave comment on PR
    outputs:
      page_url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/configure-pages@v4
      - name: Download the build artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ env.artifact }}
          path: ${{ env.workdir }}
      - name: Convert and upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ${{ env.workdir }}
      - name: Deploy site to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  ############################################################
  # Triggers a release with Semantic Release
  ############################################################
  release:
    needs: build
    # Release when requested and on scheduled workflows
    # This guarantees dependency upgrades get deployed at least once a week
    if: ${{ inputs.do_release || github.event == 'schedule' }}
    runs-on: ubuntu-latest
    permissions:
      contents: write # to be able to publish a GitHub release
      issues: write # to be able to comment on released issues
      pull-requests: write # to be able to comment on released pull requests
      id-token: write # to enable use of OIDC for npm provenance
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - name: Install poetry # Needed for updating version in pyproject.toml
        run: pipx install poetry==1.7.1
      - name: List semantic release plugins
        id: listPlugins
        uses: mikefarah/yq@master
        with:
          cmd: yq '[ .plugins[] | .[0] // . ] | join(" ")' .releaserc
      - name: Install Semantic Release
        run: npm install -g semantic-release
      - name: Install Semantic Release plugins
        run: npm install -g ${{ steps.listPlugins.outputs.result }}
      - name: Run Semantic Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: semantic-release

  ############################################################
  # Analyze code with CodeQL
  ############################################################
  analyze:
    needs: build
    # Only run this job on scheduled workflows (it takes a while)
    if: ${{ github.event == 'schedule' }}
    # Consider using larger runners for possible analysis time improvements.
    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
    timeout-minutes: ${{ (matrix.language == 'swift' && 120) || 360 }}
    permissions:
      actions: read
      contents: read
      security-events: write
    strategy:
      fail-fast: false
      matrix:
        # https://aka.ms/codeql-docs/language-support
        language: [javascript-typescript]
    steps:
      - uses: actions/checkout@v4
      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ env.artifact }}
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          # https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
          languages: ${{ matrix.language }}
      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v3
        with:
          category: "/language:${{matrix.language}}"