Merging changes from main into catalina/azure-auto-snapshots-doc

Author: catalinasmeureanu

.github/workflows/broken-link-check-full.yml

@@ -3,7 +3,7 @@ name: Broken Link Check (full)
 on:
   workflow_dispatch:
   schedule:
-    - cron: "0 0 1 * *"
+    - cron: '0 0 * * 1'
 
 jobs:
   link-checker:
@@ -42,25 +42,125 @@ jobs:
           days-before-issue-stale: 0
           # Idle number of days before closing old issues
           days-before-issue-close: 0
-          close-issue-message: "This issue was closed because an updated Link Checker Report has been generated."
+          close-issue-message: 'This issue was closed because an updated Link Checker Report has been generated.'
           repo-token: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Create GitHub Issue From lychee output file
+      - name: Generate enhanced issue content with categorization
+        if: steps.lychee.outputs.exit_code != 0
+        run: |
+          # Count different types of broken links
+          TOTAL_COUNT=$(grep -c "✗" ./lychee/out.md || echo "0")
+          
+          # Define HashiCorp domains (easily maintainable list)
+          HASHICORP_DOMAINS="hashicorp\.com|hashicorp\.io|terraform\.io|consul\.io|vault\.io|nomad\.io|packer\.io|vagrant\.io|waypoint\.io|boundary\.io|hcp\.io"
+          
+          # Count internal HashiCorp links using the dynamic list
+          INTERNAL_COUNT=$(grep -E "✗.*($HASHICORP_DOMAINS)" ./lychee/out.md | wc -l || echo "0")
+          
+          EXTERNAL_COUNT=$((TOTAL_COUNT - INTERNAL_COUNT))
+
+          # Create enhanced issue content
+          cat > ./issue-content.md << EOF
+          # 🔗 Weekly Link Checker Report - $(date '+%B %Y')
+
+          ## 📊 Summary
+
+          - **Total broken links**: $TOTAL_COUNT
+          - **Internal HashiCorp links**: $INTERNAL_COUNT 🚨
+          - **External links**: $EXTERNAL_COUNT ⚠️
+          - **Scan date**: $(date '+%Y-%m-%d')
+          - **Content scanned**: All \`/content/\` directories
+
+          ## 🎯 Prioritization Guide
+
+          When reviewing broken links, prioritize fixes in this order:
+
+          1. **🚨 High Priority**: Internal HashiCorp links (developer.hashicorp.com, etc.)
+          2. **⚠️ Medium Priority**: External documentation/API references users rely on  
+          3. **ℹ️ Low Priority**: External blog posts, news articles, or optional resources
+
+          ## 📋 Action Items
+
+          - [ ] Review high-priority internal links ($INTERNAL_COUNT found)
+          - [ ] Check if external links have moved to new URLs
+          - [ ] Update or remove links that are permanently broken
+          - [ ] Consider adding warnings for unreliable external sources
+
+          ## 🔍 Link Details
+
+          EOF
+
+          # Add the actual lychee output
+          cat ./lychee/out.md >> ./issue-content.md
+
+          # Add footer
+          cat >> ./issue-content.md << EOF
+
+          ---
+
+          **Note**: This issue is automatically updated weekly. Previous reports are closed when new ones are generated.
+
+          For more information, see our [Broken Link Monitoring documentation](.github/BROKEN_LINK_MONITORING.md).
+          EOF
+
+      - name: Create automated GitHub issue with broken link report
         id: create_issue
         if: steps.lychee.outputs.exit_code != 0
         uses: peter-evans/create-issue-from-file@e8ef132d6df98ed982188e460ebb3b5d4ef3a9cd # v5.0.1
         with:
-          title: Link Checker Report
-          content-filepath: ./lychee/out.md
-          labels: link-checker-report
+          title: 'Link Checker Report - $(date +"%B %Y")'
+          content-filepath: ./issue-content.md
+          labels: |
+            link-checker-report
+            content-quality
+
+      - name: Log production broken links to Datadog
+        if: steps.lychee.outputs.exit_code != 0
+        run: |
+          BROKEN_COUNT=$(grep -c "✗" ./lychee/out.md || echo "0")
+          echo "::error::PRODUCTION broken links detected: $BROKEN_COUNT issues affecting end users"
+          echo "GitHub issue: https://github.com/${{ github.repository }}/issues/${{ steps.create_issue.outputs.issue-number }}"
+
+          # Send structured alert to Datadog for production monitoring
+          curl -X POST "https://http-intake.logs.datadoghq.com/v1/input/${{ secrets.DD_API_KEY }}" \
+            -H "Content-Type: application/json" \
+            -d '{
+              "ddsource": "github-actions",
+              "ddtags": "environment:production,service:web-unified-docs,alert_type:broken_links_production",
+              "hostname": "github-actions",
+              "message": "Production broken links detected: '"$BROKEN_COUNT"' issues affecting end users",
+              "level": "error",
+              "broken_link_count": '"$BROKEN_COUNT"',
+              "issue_url": "https://github.com/${{ github.repository }}/issues/${{ steps.create_issue.outputs.issue-number }}"
+            }' || echo "Failed to send Datadog alert"
 
       - name: Report success in GitHub Step Summary
         if: steps.lychee.outputs.exit_code == 0
         run: |
-            echo "🎉 No broken links found! 🎉" >> $GITHUB_STEP_SUMMARY
-            exit 0
+          echo "##  Link Health Report - Success!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo " **No broken links found in production content**" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- **Scan date**: $(date '+%Y-%m-%d %H:%M:%S UTC')" >> $GITHUB_STEP_SUMMARY
+          echo "- **Content scanned**: All \`/content/\` directories" >> $GITHUB_STEP_SUMMARY
+          echo "- **Status**: All links are healthy " >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Great work maintaining high content quality!" >> $GITHUB_STEP_SUMMARY
+
+          # Log success to Datadog for trend tracking
+          curl -X POST "https://http-intake.logs.datadoghq.com/v1/input/${{ secrets.DD_API_KEY }}" \
+            -H "Content-Type: application/json" \
+            -d '{
+              "ddsource": "github-actions",
+              "ddtags": "environment:production,service:web-unified-docs,alert_type:link_health_success",
+              "hostname": "github-actions", 
+              "message": "Production link check passed - no broken links found",
+              "level": "info",
+              "broken_link_count": 0,
+              "scan_status": "success"
+            }' || echo "Failed to send Datadog success metric"
 
       - name: Report failure in GitHub Step Summary
         if: steps.lychee.outputs.exit_code != 0
         run: |
-            echo "Broken links found, [check the following Github issue for more information.](https://github.com/${{ github.repository }}/issues/${{ steps.create_issue.outputs.issue-number }})" >> $GITHUB_STEP_SUMMARY
+          echo "Broken links found, [check the following Github issue for more information.](https://github.com/${{ github.repository }}/issues/${{ steps.create_issue.outputs.issue-number }})" >> $GITHUB_STEP_SUMMARY

.github/workflows/build-pr-preview.yml

@@ -184,7 +184,6 @@ jobs:
         with:
           repository: hashicorp/dev-portal
           path: ./unified-docs-frontend-preview
-
       - name: Use cache
         uses: actions/cache@d4323d4df104b026a6aa633fdb11d772146be0bf # v4.2.2
         with:
@@ -316,7 +315,25 @@ jobs:
       - name: Add Broken Link Checker header to lychee output
         if: steps.lychee.outputs.exit_code != 0
         run: |
-          sed -i '1s/^/## Broken Link Checker\n/' ./lychee/out.md
+          cat > ./lychee/header.md << 'EOF'
+          ## Broken Link Checker
+
+          **This PR contains broken links, but won't be blocked.** Use this report to improve content quality:
+
+          ### Quick Actions
+          - **Internal links** (HashiCorp sites): Please fix these - they impact user experience
+          - **External links**: Consider if these are essential or can be updated/removed
+          - **Temporary issues**: External sites may recover - check again before merging
+
+          ### Need Help?
+          - Review our [Broken Link Monitoring docs](.github/BROKEN_LINK_MONITORING.md)
+          - Check the [monthly production report](https://github.com/hashicorp/web-unified-docs/issues?q=label%3Alink-checker-report+is%3Aopen) for context
+
+          ---
+
+          EOF
+          cat ./lychee/header.md ./lychee/out.md > ./lychee/final.md
+          mv ./lychee/final.md ./lychee/out.md
 
       # Get length of lychee output
       - name: lychee output size check
@@ -357,14 +374,7 @@ jobs:
           header: Link Checker Report
           path: ./lychee/out.md
 
-      # Fail github action if lychee exit code is anything other than the success code (0)
-      - name: lychee exit code check
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
-        if: steps.lychee.outputs.exit_code != 0
-        with:
-          script: |
-            core.setFailed('lychee failed with exit code ${{steps.lychee.outputs.exit_code}}')
-
+      # Note: PRs never fail due to broken links - this is informational only
       # If all previous Github actions run (indicating success), this one will run and overwrite the comment with a success message
       - name: Comment on PR about successful link check
         uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728 # v2.9.1

.github/workflows/repo-sync.yml

@@ -1,26 +1,36 @@
 name: Repo Sync
 
-# **What it does**: HashiCorp Docs has two repositories: hashicorp/web-unified-docs (public) and hashicorp/web-unified-docs-internal (private).
+# HashiCorp Docs has two repositories: hashicorp/web-unified-docs (public) and hashicorp/web-unified-docs-internal (private).
 # This GitHub Actions workflow keeps the `main` branch of those two repos in sync.
-# **Why we have it**: To keep the open-source repository up-to-date
-# while still having an internal repository for sensitive work.
-# **Who does it impact**: Open-source.
 
 on:
   workflow_dispatch:
-  push:
-    branches: main
+  repository_dispatch:
+    types: [push-repo-sync]
 
 permissions:
   contents: write
   pull-requests: write
 
+concurrency:
+  group: repo-sync-${{ github.repository }}
+  # we don't want to cancel an in progress run
+  # as it could leave a repo in an inconsistent state
+  cancel-in-progress: false
+
 jobs:
   repo-sync:
     if: github.repository == 'hashicorp/web-unified-docs-internal' || github.repository == 'hashicorp/web-unified-docs'
     name: Repo Sync
     runs-on: ubuntu-latest
     steps:
+      - name: Report the commit that triggered the sync
+        if: github.event_name == 'repository_dispatch'
+        run: |
+          echo "## Repo Sync Triggered" >> $GITHUB_STEP_SUMMARY
+          echo "Syncing from repository: **${{ github.event.client_payload.repository }}**" >> $GITHUB_STEP_SUMMARY
+          echo "Source commit: [\`${{ github.event.client_payload.commit }}\`](https://github.com/${{ github.event.client_payload.repository }}/commit/${{ github.event.client_payload.commit }})" >> $GITHUB_STEP_SUMMARY
+
       - name: Check out repo
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 2024-10-28
 

.github/workflows/trigger-repo-sync.yml

@@ -0,0 +1,22 @@
+name: Trigger Repo Sync in Other Repo
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  dispatch_workflow:
+    if: github.repository == 'hashicorp/web-unified-docs-internal' || github.repository == 'hashicorp/web-unified-docs'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dispatch workflow in target repo
+        uses: peter-evans/repository-dispatch@ff45666b9427631e3450c54a1bcbee4d9ff4d7c0
+        with:
+          token: ${{ secrets.CI_GITHUB_TOKEN }}
+          repository: hashicorp/${{ github.repository == 'hashicorp/web-unified-docs-internal' && 'web-unified-docs' || 'web-unified-docs-internal' }}
+          event-type: push-repo-sync
+          client-payload: |
+            {
+              "repository": "${{ github.repository }}",
+              "commit": "${{ github.sha }}"
+            }