ci: catch linkcheck failure

The scheduled linkcheck job fails without notification to maintainers.
To catch the failure, a github workflow step has been added which
comments on issue #4106 so that the maintainers get notified.

Signed-off-by: Taimoor Zaeem <taimoorzaeem@gmail.com>

.github/workflows/linkcheck.yaml

@@ -7,6 +7,7 @@ on:
 
 jobs:
   linkcheck:
+    name: Linkcheck
     runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -15,4 +16,28 @@ jobs:
       with:
         authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
         tools: docs.linkcheck.bin
-    - run: postgrest-docs-linkcheck
+
+    - name: Run Linkcheck
+      id: linkcheck
+      run: postgrest-docs-linkcheck
+
+    # This actions creates the github token using the postgrest app secrets
+    - name: Create Github App Token (Runs only on linkcheck failure)
+      id: app-token
+      if: ${{ failure() && steps.linkcheck.outcome == 'failure' }} # only create the token on linkcheck failure
+      uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+      with:
+        app-id: ${{ vars.POSTGREST_CI_APP_ID }}
+        private-key: ${{ secrets.POSTGREST_CI_PRIVATE_KEY }}
+        permission-issues: write # required for commenting on issues
+
+    - name: Notify on linkcheck failure by commenting on GH Issue 4106
+      if: ${{ failure() && steps.linkcheck.outcome == 'failure' }}
+      uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
+      with:
+        token: ${{ steps.app-token.outputs.token }}
+        issue-number: 4106
+        body: |
+          **Linkcheck Job Failed!**
+
+          A broken link was detected in the docs. Please check the [failed run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details.