Update QHelp PR comment if it already exists

If we've already commented on a PR with a preview of the QHelp changes,
then update the existing comment instead of creating a new one.

.github/workflows/post-pr-comment.yml

@@ -1,12 +1,17 @@
-name: Post pull-request comment
+# This workflow is the second part of the process described in
+# .github/workflows/qhelp-pr-preview.yml
+# See that file for more info.
+
+name: Add PR comment with QHelp preview
 on:
   workflow_run:
-    workflows: ["Query help preview"]
+    workflows: [Render QHelp changes]
     types:
       - completed
 
 permissions:
   pull-requests: write
+  actions: read
 
 jobs:
   post_comment:
@@ -17,7 +22,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.token }}
           WORKFLOW_RUN_ID: ${{ github.event.workflow_run.id }}
-      - run: |
+
+      - name: Check that PR SHA matches workflow SHA
+        run: |
           PR="$(grep -o '^[0-9]\+$' pr.txt)"
           PR_HEAD_SHA="$(gh api "/repos/${GITHUB_REPOSITORY}/pulls/${PR}" --jq .head.sha)"
           # Check that the pull-request head SHA matches the head SHA of the workflow run
@@ -25,7 +32,42 @@ jobs:
             echo "PR head SHA ${PR_HEAD_SHA} does not match workflow_run event SHA ${WORKFLOW_RUN_HEAD_SHA}. Stopping." 1>&2
             exit 1
           fi
-          gh pr comment "${PR}" --repo "${GITHUB_REPOSITORY}" -F comment.txt
         env:
           GITHUB_TOKEN: ${{ github.token }}
           WORKFLOW_RUN_HEAD_SHA: ${{ github.event.workflow_run.head_commit.id }}
+
+      # create-or-update-comment doesn't support fetching the comment directly
+      # from a file, so we have to output it from a step.
+      - id: get-comment-body
+        run: |
+          body="$(cat comment.txt)"
+          # Escape newlines - sadly required for some reason:
+          # https://github.community/t/set-output-truncates-multiline-strings/16852/3
+          body="${body//'%'/'%25'}"
+          body="${body//$'\n'/'%0A'}"
+          body="${body//$'\r'/'%0D'}"
+          echo "::set-output name=body::$body"
+
+      - id: get-pr-number
+        run: |
+          pr="$(cat pr.txt)"
+          echo "::set-output name=pr-number::$pr"
+
+      - name: Find existing comment, if it exists
+        uses: peter-evans/find-comment@v2
+        id: find-comment
+        with:
+          issue-number: ${{ steps.get-pr-number.outputs.pr-number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: QHelp previews
+          direction: last
+          token: ${{ github.token }}
+
+      - name: Create or update comment
+        uses: peter-evans/create-or-update-comment@v2
+        with:
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          issue-number: ${{ steps.get-pr-number.outputs.pr-number }}
+          edit-mode: replace
+          token: ${{ github.token }}
+          body: ${{ steps.get-comment-body.outputs.body }}

.github/workflows/qhelp-pr-preview.yml

@@ -1,4 +1,19 @@
-name: Query help preview
+# This workflow checks for any changes in .qhelp files in pull requests.
+# For any changed files, it renders them to HTML in a file called `comment.txt`.
+# It also writes the PR number to `pr.txt`.
+# These two files are uploaded as an artifact.
+
+# When this workflow completes, the workflow "Add PR comment with QHelp preview" runs.
+# It downloads the artifact and adds a comment to the PR with the rendered
+# QHelp.
+
+# The task is split like this because creating PR comments requires extra
+# permissions that we don't want to expose to PRs from external forks.
+
+# For more info see:
+# https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run
+# https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token
+name: Render QHelp changes
 
 permissions:
   contents: read