From 7b9b1fb38b71317fd7f91869b9494e5fde816421 Mon Sep 17 00:00:00 2001
From: Matthew Leibowitz <mattleibow@live.com>
Date: Mon, 11 May 2026 21:22:21 +0200
Subject: [PATCH] Improve failure comments: distinguish validation vs merge
 errors

The failure comment now shows specific context:
- Validation failures: shows the check reason and warnings detail
- Merge failures: shows the gh error (e.g. 'not up to date')
- Both can appear together since they're not mutually exclusive

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/automerge-docs.yml | 41 ++++++++++++++++++++++++----
 1 file changed, 35 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/automerge-docs.yml b/.github/workflows/automerge-docs.yml
index da3cc989..f3a00cd0 100644
--- a/.github/workflows/automerge-docs.yml
+++ b/.github/workflows/automerge-docs.yml
@@ -88,6 +88,7 @@ jobs:
         run: python3 .github/scripts/check-learn-build.py
 
       - name: Merge PR
+        id: merge
         if: |
           steps.pr.outputs.found == 'true' &&
           steps.check.outputs.should_merge == 'true' &&
@@ -98,10 +99,15 @@ jobs:
           MERGE_SHA: ${{ steps.pr.outputs.head_sha }}
         run: |
           echo "Auto-merging PR #$PR_NUMBER (SHA: $MERGE_SHA)..."
-          gh pr merge "$PR_NUMBER" --squash \
+          merge_output=$(gh pr merge "$PR_NUMBER" --squash \
             --match-head-commit "$MERGE_SHA" \
             --subject "Update API docs from latest CI build" \
-            --body "Auto-merged after Learn Build validation passed (all checks green, no new warnings)."
+            --body "Auto-merged after Learn Build validation passed (all checks green, no new warnings)." 2>&1) || {
+            echo "merge_error<<EOF" >> "$GITHUB_OUTPUT"
+            echo "$merge_output" >> "$GITHUB_OUTPUT"
+            echo "EOF" >> "$GITHUB_OUTPUT"
+            exit 1
+          }
 
       - name: Dry-run report
         if: |
@@ -128,9 +134,32 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           PR_NUMBER: ${{ steps.pr.outputs.number }}
-          REASON: ${{ steps.check.outputs.reason }}
+          CHECK_REASON: ${{ steps.check.outputs.reason }}
+          NEW_WARNINGS: ${{ steps.check.outputs.new_warnings }}
+          MERGE_ERROR: ${{ steps.merge.outputs.merge_error }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
         run: |
-          gh pr comment "$PR_NUMBER" --body \
-            "⚠️ **Auto-merge blocked**: ${REASON:-unknown failure}
+          body="⚠️ **Auto-merge blocked**"
+          body+="\n"
+
+          # Validation failure
+          if [ "$CHECK_REASON" != "All checks passed" ] && [ -n "$CHECK_REASON" ]; then
+            body+="\n**Validation**: $CHECK_REASON"
+          fi
+
+          # New warnings detail
+          if [ -n "$NEW_WARNINGS" ]; then
+            body+="\nUpdate \`.github/known-warnings.csv\` on \`main\` if these warnings are expected."
+          fi
+
+          # Merge failure (separate from validation)
+          if [ -n "$MERGE_ERROR" ]; then
+            body+="\n**Merge failed**: $MERGE_ERROR"
+            if echo "$MERGE_ERROR" | grep -q "not up to date"; then
+              body+="\nThe PR branch needs to be updated with \`main\` before it can be merged."
+            fi
+          fi
+
+          body+="\n\n[Workflow run]($RUN_URL)"
 
-          Review the [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details. Update \`.github/known-warnings.csv\` on \`main\` if new warnings are expected."
+          printf "$body" | gh pr comment "$PR_NUMBER" --body-file -