ci: create reusable workflow to comment PR about changes (#715)

Use a reusable workflow to comment a PR separately then deploy a preview
workflow.
  - This provides a better separation of concerns.
- It also allows direct use of the existing custom action to be executed
in a `pull_request` event context.
- This will require managing an additional workflow in all content
repositories, which will increase maintenance a little, but using a
“reusable workflow” will limit the cost (mainly the cost at installation
time).
- It will be called in workflows triggered by the `pull_request_target`
event (there is no build but only a check of files modified by the PR).

Covers #686

.github/actions/comment-pr-with-links/action.yml

@@ -6,7 +6,7 @@ inputs:
     description: "The url of preview to check the PR update"
     required: true
   component-name:
-    description: "The name of the component to build. If set, the build-preview-command input is ignored"
+    description: "The name of the component to build."
     required: false
     default: "bonita"
   pattern:

.github/workflows/_reusable_pr-comment-list-changes.yml

@@ -0,0 +1,45 @@
+# WARN: this workflow may be reused in other workflows
+# * triggered by a pull_request_target (to work with fork repository). This workflow doesn't do any unsecure action regarding the pull_request_target context.
+# * called with secret: inherit
+# * with:
+#    permissions:
+#     pull-requests: write
+name: Comments PR with changes list
+
+on:
+  workflow_call: # this allows the workflow to be reused
+    inputs:
+      component-name:
+        type: string
+        description: "The name of the component to build."
+        required: false
+        default: "bonita"
+      pattern:
+        type: string
+        description: ""
+        required: false
+        default: "modules/**/pages/**/*.adoc"
+      # needed by content repositories (default master) and by the doc-site repository (computed)
+      doc-site-branch:
+        type: string
+        description: "The branch of the `bonita-documentation-site` used to download js files"
+        required: false
+        default: "master"
+
+jobs:
+  # IMPORTANT: the job id must be the same as in "_reusable_surge-deploy-preview.yml" as the surge-preview-tools action uses it to generate the preview URL (current limitation of v3.2.0)
+  deploy:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: bonitasoft/actions/packages/surge-preview-tools@v3
+        id: surge-preview-tools
+        with:
+          surge-token: ${{ secrets.SURGE_TOKEN_DOC }}
+      - uses: actions/checkout@v4 # access to the local action
+      - name: Publish comments
+        uses: ./.github/actions/comment-pr-with-links
+        with:
+          site-url: ${{ steps.surge-preview-tools.outputs.preview-url }}
+          pattern: ${{ inputs.pattern }}
+          component-name: ${{ inputs.component-name }}
+          doc-site-branch : ${{ inputs.doc-site-branch }}

.github/workflows/_reusable_surge-deploy-preview.yml

@@ -20,6 +20,7 @@ on:
 
 jobs:
   # MUST be unique across all surge preview deployments for a repository as the job id is used in the deployment URL
+  # IMPORTANT: the job id must be the same as in "_reusable_pr-comment-list-changes.yml" as the surge-preview-tools action uses it to generate the preview URL (current limitation of v3.2.0)
   # IMPORTANT: the logic is duplicated in the `surge-deploy-pr-preview-test.yml` workflow. Keep both definitions in sync.
   deploy:
     runs-on: ubuntu-22.04

.github/workflows/pr-comment-list-changes.yml

@@ -0,0 +1,15 @@
+name: Comments PR with changes list
+
+on:
+  pull_request_target:
+    paths:
+      - '.github/actions/comment-pr-with-links/**/*'
+      - '.github/workflows/_reusable_pr-comment-list-changes'
+      - '.github/workflows/pr-comment-list-changes.yml'
+
+jobs:
+  site:
+    permissions:
+      pull-requests: write # write PR comments
+    uses: ./.github/workflows/_reusable_pr-comment-list-changes.yml
+    secrets: inherit