fix(ci): use merge commit for apidiff to avoid false positives

Author: DmitriyLewen

.github/workflows/apidiff.yaml

@@ -20,19 +20,31 @@ jobs:
     runs-on: ubuntu-24.04
     name: API Diff Check
     steps:
-      # Checkout PR code for static analysis only
+      # Check if PR has conflicts. When conflicts exist, the merge commit becomes
+      # frozen at an old state and apidiff cannot run correctly.
+      # Note: mergeable can be true/false/null (when status is being computed)
+      - name: Check for merge conflicts
+        if: ${{ github.event.pull_request.mergeable != true }}
+        run: |
+          echo "::error::This PR has merge conflicts. Please resolve conflicts before running apidiff."
+          exit 1
+
+      # Checkout PR merge commit to compare against base branch
+      # This ensures we compare the actual merge result with the base branch,
+      # avoiding false positives when PR is not rebased with latest main
       - name: Checkout
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
-          ref: ${{ github.event.pull_request.head.sha }}
+          ref: refs/pull/${{ github.event.pull_request.number }}/merge
 
       - name: Set up Go
         uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version-file: go.mod
           cache: false
 
-      # Ensure the base commit exists locally when checkout uses depth=1 (default).
+      # Ensure the base commit exists locally for go-apidiff to compare against.
+      # Even though we checkout the merge commit, go-apidiff needs the base ref to exist.
       - name: Fetch base commit
         run: |
           BASE_REF="${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha }}"
@@ -129,4 +141,4 @@ jobs:
             } catch (error) {
               core.error(`Failed to request trivy-premium reviewers: ${error.message}`);
               throw error;
-            }
+            }