Fix retarget workflow: avoid rebase, fix token scope, add PR comment

SufficientDaikon · SufficientDaikon · commit 3d0b04a6d1c3 · 2026-03-26T01:16:32.000+02:00
- Remove auth header from upstream API check (public repo, cross-org
  token causes 403)
- Replace git rebase with reset+save/restore (rebase fails in CI
  with conflicts and no interactive mode)
- Set git identity before any git operations
- Use git apply --3way with fallback instead of blind file copy
- Fix commit message indentation (was baking YAML whitespace)
- Add PR comment step so retarget is visible without checking Actions
- Handle alternate What's New section headers (Updated cmdlets)
- Warn when What's New 7.7 is missing instead of silently skipping
- Stage specific files instead of git add -A
diff --git a/.github/workflows/retarget-7.7.yml b/.github/workflows/retarget-7.7.yml
@@ -8,6 +8,7 @@ on:
 
 permissions:
   contents: write
+  pull-requests: write
 
 jobs:
   check-and-retarget:
@@ -17,26 +18,30 @@ jobs:
       - name: Check if 7.7 folder exists upstream
         id: check
         run: |
+          # Public repo — no auth needed (avoids cross-org token scope issues)
           STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
-            "https://api.github.com/repos/MicrosoftDocs/PowerShell-Docs/contents/reference/7.7/Microsoft.PowerShell.Utility" \
-            -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}")
+            "https://api.github.com/repos/MicrosoftDocs/PowerShell-Docs/contents/reference/7.7/Microsoft.PowerShell.Utility")
+          echo "status=$STATUS" >> "$GITHUB_OUTPUT"
           if [ "$STATUS" = "200" ]; then
             echo "exists=true" >> "$GITHUB_OUTPUT"
           else
             echo "exists=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::reference/7.7/ not found upstream (HTTP $STATUS). Will check again tomorrow."
           fi
 
-      - name: Exit early if 7.7 not ready
-        if: steps.check.outputs.exists != 'true'
-        run: echo "reference/7.7/ not found upstream yet. Will check again tomorrow."
-
       - name: Checkout fork
         if: steps.check.outputs.exists == 'true'
         uses: actions/checkout@v4
         with:
           ref: doc/new-guid-uuid-v7
           fetch-depth: 0
 
+      - name: Configure git identity
+        if: steps.check.outputs.exists == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
       - name: Add upstream remote
         if: steps.check.outputs.exists == 'true'
         run: |
@@ -49,94 +54,135 @@ jobs:
         run: |
           if [ -f "reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md" ]; then
             echo "done=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::Already retargeted — nothing to do."
           else
             echo "done=false" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Retarget docs from 7.6 to 7.7
         if: steps.check.outputs.exists == 'true' && steps.already.outputs.done != 'true'
         run: |
-          # Rebase onto latest upstream main
-          git rebase upstream/main
+          set -euo pipefail
+
+          # ── 1. Reset branch to upstream main (clean slate, avoids rebase conflicts) ──
+          # Save our modified files first
+          cp reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md /tmp/New-Guid-ours.md
+          git diff upstream/main -- reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md \
+            > /tmp/whats-new-76.patch || true
+
+          git reset --hard upstream/main
 
-          # Get the upstream 7.7 New-Guid.md as base (if it exists), otherwise copy from 7.6
+          # ── 2. Create 7.7 New-Guid.md from our modified version ──
+          mkdir -p reference/7.7/Microsoft.PowerShell.Utility
+
+          # Start with upstream's 7.7 base if it exists, otherwise use our modified file
           if git show upstream/main:reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md > /dev/null 2>&1; then
-            mkdir -p reference/7.7/Microsoft.PowerShell.Utility
+            # Upstream has a 7.7 base — use it and apply our changes on top
             git show upstream/main:reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md \
               > reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
-          fi
 
-          # Apply our New-Guid changes to the 7.7 version
-          # Copy our modified 7.6 file as the 7.7 version
-          mkdir -p reference/7.7/Microsoft.PowerShell.Utility
-          cp reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md \
-             reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
+            # Generate a patch from upstream 7.6 → our 7.6 and apply to 7.7
+            git diff upstream/main -- reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md \
+              < /dev/null > /tmp/new-guid.patch || true
+            if [ -s /tmp/new-guid.patch ]; then
+              # Repath the patch from 7.6 to 7.7
+              sed -i 's|reference/7.6/|reference/7.7/|g' /tmp/new-guid.patch
+              git apply --3way /tmp/new-guid.patch || {
+                echo "::warning::Patch apply failed — falling back to direct copy"
+                cp /tmp/New-Guid-ours.md reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
+              }
+            fi
+          else
+            # No upstream 7.7 base — copy our modified 7.6 file directly
+            cp /tmp/New-Guid-ours.md reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
+          fi
 
-          # Update the online version URL from 7.6 to 7.7
+          # Update version URL: 7.6 → 7.7
           sed -i 's/view=powershell-7\.6/view=powershell-7.7/g' \
             reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
 
-          # Revert the 7.6 file back to upstream state
-          git checkout upstream/main -- reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md
-
-          # Handle What's New: revert 7.6 file, create 7.7 entry if it exists
-          git checkout upstream/main -- reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md
-
-          # If What's New 7.7 file exists upstream, add our entries there
+          # ── 3. Handle What's New ──
+          # The 7.6 file is already at upstream state (we did reset --hard).
+          # Check if a 7.7 What's New file exists.
           WHATS_NEW_77="reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-77.md"
           if [ -f "$WHATS_NEW_77" ]; then
-            # Add breaking change entry if not already present
-            if ! grep -q "New-Guid.*Version 7" "$WHATS_NEW_77"; then
-              # Insert after "## Breaking changes" or "## Cmdlet improvements" headers
-              python3 - "$WHATS_NEW_77" <<'PYEOF'
+            if ! grep -q "New-Guid" "$WHATS_NEW_77"; then
+              python3 <<'PYEOF'
 import sys
-path = sys.argv[1]
+
+path = "reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-77.md"
 with open(path, 'r') as f:
     content = f.read()
 
-breaking_entry = """- `New-Guid` now generates Version 7 (time-sortable) UUIDs by default instead of Version 4
-  (random). The output format is unchanged. Scripts that depend on fully random GUIDs should use
-  `[guid]::NewGuid()` directly. ([#27033][27033])"""
+breaking_entry = ("- `New-Guid` now generates Version 7 (time-sortable) UUIDs by default instead of Version 4\n"
+                   "  (random). The output format is unchanged. Scripts that depend on fully random GUIDs should use\n"
+                   "  `[guid]::NewGuid()` directly. ([#27033][27033])")
 
-cmdlet_entry = """- Change `New-Guid` to generate UUID v7 by default using `Guid.CreateVersion7()`
-  ([#27033][27033])"""
+cmdlet_entry = ("- Change `New-Guid` to generate UUID v7 by default using `Guid.CreateVersion7()`\n"
+                "  ([#27033][27033])")
 
 link_entry = "[27033]: https://github.com/PowerShell/PowerShell/pull/27033"
 
-# Add entries (simple append approach - manual placement may be needed)
+modified = False
+
 if '## Breaking changes' in content:
-    content = content.replace('## Breaking changes\n', f'## Breaking changes\n\n{breaking_entry}\n')
+    content = content.replace('## Breaking changes\n', '## Breaking changes\n\n' + breaking_entry + '\n', 1)
+    modified = True
+
 if '## Cmdlet improvements' in content:
-    content = content.replace('## Cmdlet improvements\n', f'## Cmdlet improvements\n\n{cmdlet_entry}\n')
+    content = content.replace('## Cmdlet improvements\n', '## Cmdlet improvements\n\n' + cmdlet_entry + '\n', 1)
+    modified = True
+elif '## Updated cmdlets' in content:
+    content = content.replace('## Updated cmdlets\n', '## Updated cmdlets\n\n' + cmdlet_entry + '\n', 1)
+    modified = True
+
 if link_entry not in content:
     content = content.rstrip() + '\n' + link_entry + '\n'
+    modified = True
+
+if not modified:
+    print("::warning::What's New 7.7 exists but has no recognized section headers. Manual edit needed.")
+    sys.exit(0)
 
 with open(path, 'w') as f:
     f.write(content)
+print("Updated What's New 7.7 with New-Guid entries.")
 PYEOF
             fi
+          else
+            echo "::notice::What-s-New-in-PowerShell-77.md does not exist yet. Only New-Guid.md will be included."
           fi
 
-          # Stage and commit
-          git add -A
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git commit -m "Retarget New-Guid UUID v7 docs from 7.6 to 7.7
+          # ── 4. Stage and commit ──
+          git add reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
+          if [ -f "$WHATS_NEW_77" ]; then
+            git add "$WHATS_NEW_77"
+          fi
 
-          The 7.7 reference folder is now available upstream.
-          Moved New-Guid changes to reference/7.7/ and reverted
-          reference/7.6/ to upstream state.
+          git commit -m "Retarget New-Guid UUID v7 docs from 7.6 to 7.7
 
-          Co-Authored-By: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>"
+The 7.7 reference folder is now available upstream.
+Moved New-Guid changes to reference/7.7/ and reverted
+reference/7.6/ to upstream state."
 
       - name: Push changes
         if: steps.check.outputs.exists == 'true' && steps.already.outputs.done != 'true'
         run: git push origin doc/new-guid-uuid-v7 --force-with-lease
 
+      - name: Comment on PR
+        if: steps.check.outputs.exists == 'true' && steps.already.outputs.done != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh pr comment 12888 --repo MicrosoftDocs/PowerShell-Docs --body \
+            "The \`reference/7.7/\` folder is now available upstream. I've retargeted this PR — \`New-Guid.md\` changes now live under \`reference/7.7/\` and the 7.6 file has been reverted to upstream state. Ready for review when convenient."
+
       - name: Post summary
         if: steps.check.outputs.exists == 'true' && steps.already.outputs.done != 'true'
         run: |
           echo "## Retarget complete" >> "$GITHUB_STEP_SUMMARY"
           echo "" >> "$GITHUB_STEP_SUMMARY"
-          echo "Moved New-Guid UUID v7 docs from \`reference/7.6/\` to \`reference/7.7/\`." >> "$GITHUB_STEP_SUMMARY"
-          echo "PR #12888 branch has been updated." >> "$GITHUB_STEP_SUMMARY"
+          echo "- Moved \`New-Guid.md\` from \`reference/7.6/\` → \`reference/7.7/\`" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Reverted \`reference/7.6/\` to upstream state" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Updated PR branch \`doc/new-guid-uuid-v7\`" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Posted comment on PR #12888" >> "$GITHUB_STEP_SUMMARY"
