ci-workflow.yml

name: CI Workflow
run-name: ${{ format('{0} triggered {1} on {2}', (github.event_name == 'workflow_dispatch' && format('User {0}', github.actor) || format('{0} event', github.event_name) ), github.workflow, github.ref) }}
on:
  schedule:
    - cron: '0 4 * * 1'

  pull_request:

  push:
    branches:
      - 'main'

  workflow_dispatch:
    inputs:
      forceDocsUpload:
        description: 'Force API docs upload'
        required: true
        default: false
        type: boolean

jobs:
  CI:
    name: CI
    runs-on: ubuntu-22.04
    outputs:
      shouldUpload: ${{ steps.shouldUpload.outputs.upload }}
    steps:
      - name: Check out repository code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0 # check out the entire repo history for SHA verification in lastSuccessful step

      - name: Lint Markdown docs
        run: make lint-markdown

      - name: Lint specification
        run: make lint-apispec

      - name: Render API docs
        run: make render

      #################################
      ## Upload deployable artefacts ##
      #################################
      - name: Identify latest successful run
        id: lastSuccessful
        uses: SamhammerAG/last-successful-build-action@1c368a27a90596574a71ac0ede422a897d0e8e84  # @v4
        with:
          branch: ${{ github.ref_name }}
          workflow: ${{ github.workflow }}
          verify: true

      - name: Determine if this workflow should upload artefacts
        id: shouldUpload
        shell: bash
        run: |
          if [ "${{ steps.lastSuccessful.outputs.sha }}" != "${{ github.sha }}" ] && [ "${{ github.ref_name }}" == "main" ]
          then
            echo "upload=true" >> $GITHUB_OUTPUT;
          else
            echo "upload=false" >> $GITHUB_OUTPUT;
          fi

      - name: Setup pages
        if: ${{ inputs.forceDocsUpload || ( steps.shouldUpload.outputs.upload == 'true' ) }}
        uses: actions/configure-pages@v3

      - name: Upload documentation artifact
        if: ${{ inputs.forceDocsUpload || ( steps.shouldUpload.outputs.upload == 'true' ) }}
        uses: actions/upload-pages-artifact@v2
        with:
          path: './api/docs'

  DeployPages:
    name: Deploy Pages
    # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
    permissions:
      contents: read
      pages: write
      id-token: write
    runs-on: ubuntu-22.04
    needs: CI
    if: ${{ inputs.forceDocsUpload || ( needs.CI.outputs.shouldUpload == 'true' ) }}
    steps:
      - name: Deploy documentation to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2
      - name: Adding summary
        run: |
          echo "Documentation URL: ${{ steps.deployment.outputs.page_url }}" >> $GITHUB_STEP_SUMMARY