docs-matrix-spec/.github/workflows/main.yml

name: "Spec"
on:
  push:
    branches:
      - main
    tags:
      - v*
  pull_request:
  workflow_dispatch:
  schedule:
    # Run this workflow every day at 2am. This helps keep the page of
    # current spec proposals up-to-date.
    - cron: '0 2 * * *'

jobs:
  validate-openapi:
    name: "🔎 Validate OpenAPI specifications"
    runs-on: ubuntu-latest
    steps:
      - name: "📥 Source checkout"
        uses: actions/checkout@v2
      - name: "➕ Setup Node"
        uses: actions/setup-node@v2
        with:
          node-version: '14'
      - name: "⚙️ npm"
        working-directory: "./scripts"
        run: |
          npm install
      - name: "🔎 Run validator"
        working-directory: "./scripts"
        run: |
          node validator.js -s "../data/api/application-service"
          node validator.js -s "../data/api/client-server"
          node validator.js -s "../data/api/push-gateway"

  check-examples:
    name: "🔎 Check Event schema examples"
    runs-on: ubuntu-latest
    container: uhoreg/matrix-doc-build
    steps:
      - name: "📥 Source checkout"
        uses: actions/checkout@v2
      - name: "🔎 Run validator"
        run: |
          /env/bin/python scripts/check-event-schema-examples.py
        
  calculate-baseurl:
    name: "⚙️ Calculate baseURL for later jobs"
    runs-on: ubuntu-latest
    outputs:
      baseURL: "${{ steps.set-baseurl.outputs.baseURL }}"
    steps:
      # For PRs, set the baseURL to `/`.
      # For releases, set the baseURL to `/$tag` (eg: `/v1.2`).
      # Otherwise, set it to `/unstable`.
      - name: "⚙️ Calculate baseURL"
        id: set-baseurl
        # Double brackets on the elif to avoid auto-escaping refs/tags/* because we need
        # the asterisk matching behaviour, not the literal string.
        run: |
          if [ "${GITHUB_EVENT_NAME}" == "pull_request" ]; then
              echo ::set-output name=baseURL::/
          elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
              echo ::set-output name=baseURL::"/${GITHUB_REF/refs\/tags\//}"
          else
              echo ::set-output name=baseURL::/unstable
          fi

  build-openapi:
    name: "🐍 Build OpenAPI definitions"
    runs-on: ubuntu-latest
    container: "python:3.9"
    needs: [calculate-baseurl]
    steps:
      - name: "📥 Source checkout"
        uses: actions/checkout@v2
      - name: "📦 Asset creation"
        run: |
          python3 -m venv env && . env/bin/activate
          pip install -r scripts/requirements.txt
          # The output path matches the final deployment path at spec.matrix.org
          scripts/dump-swagger.py \
            --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
            --api application-service \
            -o spec/application-service-api/api.json
          scripts/dump-swagger.py \
            --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
            --api client-server \
            -o spec/client-server-api/api.json
          scripts/dump-swagger.py \
            --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
            --api push-gateway \
            -o spec/push-gateway-api/api.json
          tar -czf openapi.tar.gz spec
      - name: "📤 Artifact upload"
        uses: actions/upload-artifact@v2
        with:
          name: openapi-artifact
          path: openapi.tar.gz

  generate-changelog:
    name: "📢 Run towncrier for changelog"
    # skip for builds of git tags
    if: "!startsWith(github.ref, 'refs/tags/')"
    runs-on: ubuntu-latest
    steps:
      - name: "📥 Source checkout"
        uses: actions/checkout@v2
      - name: "➕ Setup Python"
        uses: actions/setup-python@v4
      - name: "➕ Install towncrier"
        run: "pip install 'towncrier'"
      - name: "Generate changelog"
        run: ./scripts/generate-changelog.sh vUNSTABLE
      - name: "📤 Artifact upload"
        uses: actions/upload-artifact@v2
        with:
          name: changelog-artifact
          path: content/changelog/vUNSTABLE.md

  build-spec:
    name: "📖 Build the spec"
    runs-on: ubuntu-latest
    needs: [calculate-baseurl, build-openapi, generate-changelog]
    # run even if generate-changelog was skipped
    if: ${{ always() }}
    steps:
      - name: "➕ Setup Node"
        uses: actions/setup-node@v2
        with:
          node-version: '14'
      - name: "➕ Setup Hugo"
        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
        with:
          hugo-version: '0.93.3'
          extended: true
      - name: "📥 Source checkout"
        uses: actions/checkout@v2
      - name: "⚙️ npm"
        run: |
          npm i
          npm run get-proposals
      - name: "📥 Download generated changelog"
        if: "needs.generate-changelog.result == 'success'"
        uses: actions/download-artifact@v3
        with:
          name: changelog-artifact
          path: content/changelog
      - name: "⚙️ hugo"
        run: hugo --baseURL "${{ needs.calculate-baseurl.outputs.baseURL }}" -d "spec"
      # We manually unpack the spec OpenAPI definition JSON to the website tree
      # to make it available to the world in a canonical place:
      # https://spec.matrix.org/latest/client-server-api/api.json
      # Works for /unstable/ and /v1.1/ as well.
      - name: "📥 Spec definition download"
        uses: actions/download-artifact@v2
        with:
          name: openapi-artifact
      - name: "📝 Unpack the OpenAPI definitions in the right location"
        run: |
          tar -xzf openapi.tar.gz

      - name: "📦 Tarball creation"
        run: tar -czf spec.tar.gz spec
      - name: "📤 Artifact upload"
        uses: actions/upload-artifact@v2
        with:
          name: spec-artifact
          path: spec.tar.gz

  htmlcheck:
    name: "🔎 Validate generated HTML"
    runs-on: ubuntu-latest
    needs: [build-spec]
    steps:
      - name: "📥 Source checkout"
        uses: actions/checkout@v2

      - name: "📥 Fetch built spec"
        uses: actions/download-artifact@v2
        with:
          name: spec-artifact

      - name: "📝 Unpack the spec"
        run: |
          tar -xvzf spec.tar.gz

      - name: "Run htmltest"
        uses: wjdp/htmltest-action@master
        with:
          config: .htmltest.yaml

  build-historical-spec:
    name: "📖 Build the historical backup spec"
    runs-on: ubuntu-latest
    needs: [build-openapi]
    if: ${{ startsWith(github.ref, 'refs/tags/') }}
    steps:
      - name: "➕ Setup Node"
        uses: actions/setup-node@v2
        with:
          node-version: '14'
      - name: "➕ Setup Hugo"
        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
        with:
          hugo-version: '0.93.3'
          extended: true
      - name: "📥 Source checkout"
        uses: actions/checkout@v2
      - name: "⚙️ npm"
        run: |
          npm i
          npm run get-proposals
      - name: "⚙️ hugo"
        # Create a baseURL like `/v1.2` out of the `v1.2` tag
        run: |
          echo -e '[params.version]\nstatus="historical"' > historical.toml
          hugo --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"

      - name: "📥 Spec definition download"
        uses: actions/download-artifact@v2
        with:
          name: openapi-artifact
      - name: "📝 Unpack the OpenAPI definitions in the right location"
        run: |
          tar -xzf openapi.tar.gz

      - name: "📦 Tarball creation"
        run: tar -czf spec-historical.tar.gz spec
      - name: "📤 Artifact upload"
        uses: actions/upload-artifact@v2
        with:
          name: spec-historical-artifact
          path: spec-historical.tar.gz