feat(commitlint): use step summaries for output and adjust comment format (#144)

Author: JossWhittle

.github/workflows/pr-title-commitlint.yaml

@@ -9,7 +9,17 @@ on:
 
       comment-header:
         description: "Header line for the PR comment."
-        default: ":black_nib: Commitlint PR Title"
+        default: ":black_nib: PR Title Commitlint"
+        type: string
+
+      comment-success:
+        description: "Success message for the PR comment."
+        default: ":heavy_check_mark: Lint success!"
+        type: string
+
+      comment-error:
+        description: "Error message for the PR comment."
+        default: ":x: Lint error! Fix title before merging!"
         type: string
 
       config:
@@ -50,7 +60,7 @@ jobs:
         shell: bash
         run: |
           set +e
-          lint=$(echo "$TITLE" | npx commitlint --config="$CONFIG")
+          lint=$(echo "$TITLE" | npx commitlint --config="$CONFIG" --help-url="$CONFIG")
           status=$?
           echo "$lint"
           printf "lint<<EOF\n%s\nEOF" "${lint}" >> "$GITHUB_OUTPUT"
@@ -59,6 +69,33 @@ jobs:
           TITLE: ${{ github.event.pull_request.title }}
           CONFIG: ${{ inputs.config }}
 
+      - name: create step summary on bad lint
+        if: always() && steps.commitlint.outcome != 'success'
+        shell: bash
+        run: |
+          printf "%s" "${SUMMARY}" >> "$GITHUB_STEP_SUMMARY"
+          printf "COMMENT_BODY<<EOF\n%s\nEOF" "${SUMMARY}" >> "$GITHUB_ENV"
+        env:
+          # Note the intentional double spaces at the end of some lines. This is markdown.
+          SUMMARY: |
+            #### ${{ inputs.comment-header }} - ${{ inputs.comment-error }}
+            Expected PR title to be conventional commit format: ie. `type(scope): summary`
+            ```
+            ${{ steps.commitlint.outputs.lint }}
+            ```
+            Conventional Commits :open_book: [Docs](https://www.conventionalcommits.org/en/v1.0.0)  
+            Commitlint :file_cabinet: [Config](https://github.com/${{ github.repository }}/blob/${{ github.sha }}/${{ inputs.config }}) :open_book: [Docs](https://commitlint.js.org/reference/rules)   
+
+      - name: create step summary on good lint
+        if: always() && steps.commitlint.outcome == 'success'
+        shell: bash
+        run: |
+          printf "%s" "${SUMMARY}" >> "$GITHUB_STEP_SUMMARY"
+          printf "COMMENT_BODY<<EOF\n%s\nEOF" "${SUMMARY}" >> "$GITHUB_ENV"
+        env:
+          SUMMARY: |
+            #### ${{ inputs.comment-header }} - ${{ inputs.comment-success }}
+
       - name: find pr comment
         uses: peter-evans/find-comment@v3
         if: always()
@@ -68,28 +105,15 @@ jobs:
           body-includes: ${{ inputs.comment-header }}
           comment-author: "github-actions[bot]"
 
-      - name: create or update pr comment on bad lint
-        uses: peter-evans/create-or-update-comment@v4
-        if: always() && steps.commitlint.outcome == 'failure'
-        with:
-          comment-id: ${{ steps.find-pr-comment.outputs.comment-id }}
-          issue-number: ${{ github.event.pull_request.number }}
-          edit-mode: replace
-          body: |
-            #### :x: ${{ inputs.comment-header }} - Fix title before merge!
-            ```
-            ${{ steps.commitlint.outputs.lint }}
-            ```
-
-      - name: create or update pr comment on successful lint
+      - name: create or update pr comment
         uses: peter-evans/create-or-update-comment@v4
-        if: always() && steps.commitlint.outcome == 'success'
+        if: always() && (steps.commitlint.outcome == 'success' || steps.commitlint.outcome == 'failure')
         with:
           comment-id: ${{ steps.find-pr-comment.outputs.comment-id }}
           issue-number: ${{ github.event.pull_request.number }}
           edit-mode: replace
           body: |
-            #### :heavy_check_mark: ${{ inputs.comment-header }} - Good Title
+            ${{ env.COMMENT_BODY }}
 
       - name: add error label on bad lint
         uses: actions/github-script@v7.0.1