Merge pull request #8618 from hmac/hmac/qlhelp-comment-workflow

Update existing qhelp comment, if it exists

.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: Post PR comment
 on:
   workflow_run:
-    workflows: ["Query help preview"]
+    workflows: [Render QHelp changes]
     types:
       - completed
 
 permissions:
   pull-requests: write
+  actions: read
 
 jobs:
   post_comment:
@@ -17,15 +22,53 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.token }}
           WORKFLOW_RUN_ID: ${{ github.event.workflow_run.id }}
-      - run: |
-          PR="$(grep -o '^[0-9]\+$' pr.txt)"
+
+      - name: Check that PR SHA matches workflow SHA
+        run: |
+          PR="$(grep -o '^[0-9]\+$' pr_number.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
           if [ "${WORKFLOW_RUN_HEAD_SHA}" != "${PR_HEAD_SHA}" ]; then
             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 }}
+
+      - name: Create or update comment
+        run: |
+          COMMENT_PREFIX="QHelp previews"
+          COMMENT_AUTHOR="github-actions[bot]"
+          PR_NUMBER="$(grep -o '^[0-9]\+$' pr_number.txt)"
+
+          # If there is no existing comment, comment_id.txt will contain just a
+          # newline (due to jq & gh behaviour). This will cause grep to fail, so
+          # we catch that.
+          RAW_COMMENT_ID=$(grep -o '^[0-9]\+$' comment_id.txt || true)
+
+          if [ $RAW_COMMENT_ID ]
+          then
+            # Fetch existing comment, and validate:
+            # - comment belongs to the PR with number $PR_NUMBER
+            # - comment starts with the expected prefix ("QHelp previews")
+            # - comment author is github-actions[bot]
+            FILTER='select(.issue_url | endswith($repo+"/issues/"+$pr))
+                  | select(.body | startswith($prefix))
+                  | select(.user.login == $author)
+                  | .id'
+            COMMENT_ID=$(gh api "repos/${GITHUB_REPOSITORY}/issues/comments/${RAW_COMMENT_ID}" | jq --arg repo "${GITHUB_REPOSITORY}" --arg pr "${PR_NUMBER}" --arg prefix "${COMMENT_PREFIX}" --arg author "${COMMENT_AUTHOR}" "${FILTER}")
+            if [ $COMMENT_ID ]
+            then
+              # Update existing comment
+              jq --rawfile body comment_body.txt '{"body":$body}' -n | gh api "repos/${GITHUB_REPOSITORY}/issues/comments/${COMMENT_ID}" -X PATCH --input -
+            else
+              echo "Comment ${RAW_COMMENT_ID} did not pass validations: not editing." >&2
+              exit 1
+            fi
+          else
+            # Create new comment
+            jq --rawfile body comment_body.txt '{"body":$body}' -n | gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" -X POST --input -
+          fi
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

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

@@ -1,7 +1,25 @@
-name: Query help preview
+# This workflow checks for any changes in .qhelp files in pull requests.
+# For any changed files, it renders them to markdown in a file called `comment_body.txt`.
+# It then checks if there's an existing comment on the pull request generated by
+# this workflow, and writes the comment ID to `comment_id.txt`.
+# It also writes the PR number to `pr_number.txt`.
+# These three files are uploaded as an artifact.
+
+# When this workflow completes, the workflow "Post PR comment" 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
+  pull-requests: read
 
 on:
   pull_request:
@@ -15,12 +33,16 @@ jobs:
   qhelp:
     runs-on: ubuntu-latest
     steps:
-      - run: echo "${{  github.event.number }}" > pr.txt
+      - run: echo "${PR_NUMBER}" > pr_number.txt
+        env:
+          PR_NUMBER: ${{ github.event.number }}
       - uses: actions/upload-artifact@v2
         with:
           name: comment
-          path: pr.txt
+          path: pr_number.txt
+          if-no-files-found: error
           retention-days: 1
+
       - uses: actions/checkout@v2
         with:
           fetch-depth: 2
@@ -36,7 +58,7 @@ jobs:
       - name: QHelp preview
         run: |
           EXIT_CODE=0
-          echo "QHelp previews:" > comment.txt
+          echo "QHelp previews:" > comment_body.txt
           while read -r -d $'\0' path; do
             if [ ! -f "${path}" ]; then
                exit 1
@@ -52,12 +74,29 @@ jobs:
                echo '```'
             fi
             echo "</details>"
-          done < "${RUNNER_TEMP}/paths.txt" >> comment.txt
+          done < "${RUNNER_TEMP}/paths.txt" >> comment_body.txt
           exit "${EXIT_CODE}"
 
       - if: always()
         uses: actions/upload-artifact@v2
         with:
           name: comment
-          path: comment.txt
+          path: comment_body.txt
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: Save ID of existing QHelp comment (if it exists)
+        run: |
+          # Find the latest comment starting with "QHelp previews"
+          COMMENT_PREFIX="QHelp previews"
+          gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" --paginate | jq --arg prefix "${COMMENT_PREFIX}" '[.[] | select(.body|startswith($prefix)) | .id] | max' > comment_id.txt
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.number }}
+
+      - uses: actions/upload-artifact@v2
+        with:
+          name: comment
+          path: comment_id.txt
+          if-no-files-found: error
           retention-days: 1