docs: update GitHub Actions documentation #1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Documentation Post-Merge Checks | ||
| on: | ||
| # Run after merges to main | ||
| push: | ||
| branches: | ||
| - main | ||
| paths: | ||
| - 'docs/**' | ||
| - '**.md' | ||
| - '.github/docs/**' | ||
| - '.github/workflows/docs-link-check.yaml' | ||
| # Weekly run on Monday at 9 AM | ||
| schedule: | ||
| - cron: "0 9 * * 1" | ||
| # Allow manual triggering for testing | ||
| workflow_dispatch: | ||
| permissions: | ||
| contents: read | ||
| issues: write # needed to create GitHub issues | ||
| jobs: | ||
| post-merge-checks: | ||
| name: Check Links and Cross-References | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Harden Runner | ||
| uses: step-security/harden-runner@v2 | ||
| with: | ||
| egress-policy: audit | ||
| - name: Checkout | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| fetch-depth: 0 # Needed for cross-reference checking | ||
| - name: Setup Environment | ||
| uses: ./.github/docs/actions/docs-setup | ||
| with: | ||
| setup-vale: false # Don't need Vale for post-merge checks | ||
| # Check links with lychee (faster and more robust than linkspector) | ||
| - name: Check Markdown links | ||
| id: lychee | ||
| uses: lycheeverse/lychee-action@v1.8.0 | ||
| with: | ||
| args: >- | ||
| --verbose | ||
| --no-progress | ||
| --exclude-mail | ||
| --exclude-loopback | ||
| --exclude-private | ||
| --ignore-file=.github/docs/.lycheeignore | ||
| './docs/**/*.md' | ||
| format: json | ||
| output: ./lychee-result.json | ||
| fail: false | ||
| # Check cross-references specifically using our shared action | ||
| - name: Check Cross-References | ||
| id: cross-references | ||
| uses: ./.github/docs/actions/docs-shared | ||
| with: | ||
| github-token: ${{ secrets.GITHUB_TOKEN }} | ||
| docs-dir: docs | ||
| include-md-files: "true" | ||
| check-links: "false" # Skip link check (already done) | ||
| lint-markdown: "false" # Skip linting on merge | ||
| check-format: "false" # Skip format checking on merge | ||
| lint-vale: "false" # Skip Vale on merge | ||
| check-cross-references: "true" # Only check cross-references | ||
| generate-preview: "false" # No preview needed | ||
| post-comment: "false" # No PR to comment on | ||
| fail-on-error: "false" # Don't fail workflow | ||
| # Aggregate results from both checks | ||
| - name: Process validation results | ||
| id: process-results | ||
| if: always() # Run even if the previous steps fail | ||
| run: | | ||
| # Initialize variables | ||
| HAS_ISSUES="false" | ||
| ISSUE_CONTENT="" | ||
| ISSUE_TITLE="" | ||
| # Process link check results from lychee | ||
| if [ -f "./lychee-result.json" ]; then | ||
| echo "Reading link check results from lychee-result.json" | ||
| # Count broken links with error handling | ||
| BROKEN_LINKS=0 | ||
| if jq -e '.data.failed' "./lychee-result.json" > /dev/null 2>&1; then | ||
| BROKEN_LINKS=$(jq '.data.failed | length' "./lychee-result.json" || echo "0") | ||
| fi | ||
| echo "broken_links=$BROKEN_LINKS" >> $GITHUB_OUTPUT | ||
| if [ "$BROKEN_LINKS" -gt 0 ]; then | ||
| HAS_ISSUES="true" | ||
| ISSUE_TITLE="📚 Documentation Health Check: Broken Links and References" | ||
| # Format link results with lychee's output structure | ||
| LINK_RESULTS="## Broken Links ($BROKEN_LINKS found)\n\n" | ||
| LINK_RESULTS+="| File | Link | Status |\n" | ||
| LINK_RESULTS+="|------|------|--------|\n" | ||
| # Process lychee's output format which is different from linkspector | ||
| LINK_TABLE=$(jq -r '.data.failed[] | "| \(.input_file // "Unknown") | \(.url) | \(.status_code // "Error") |"' "./lychee-result.json") | ||
| LINK_RESULTS+="$LINK_TABLE" | ||
| ISSUE_CONTENT+="$LINK_RESULTS\n\n" | ||
| fi | ||
| fi | ||
| # Process cross-reference results | ||
| if [ -n "${{ steps.cross-references.outputs.cross_ref_results }}" ]; then | ||
| echo "Found broken cross-references" | ||
| HAS_ISSUES="true" | ||
| ISSUE_TITLE="📚 Documentation Health Check: Broken Links and References" | ||
| # Format cross-reference results | ||
| XREF_RESULTS="## Broken Cross-References\n\n" | ||
| XREF_RESULTS+="The following cross-references were broken in the recent merge:\n\n" | ||
| XREF_RESULTS+="${{ steps.cross-references.outputs.cross_ref_results }}" | ||
| ISSUE_CONTENT+="$XREF_RESULTS\n\n" | ||
| fi | ||
| # Add guidance if issues were found | ||
| if [ "$HAS_ISSUES" == "true" ]; then | ||
| ISSUE_CONTENT+="## How to Fix\n\n" | ||
| ISSUE_CONTENT+="### For Broken Links\n\n" | ||
| ISSUE_CONTENT+="1. Check if the link is correct\n" | ||
| ISSUE_CONTENT+="2. Update the link if needed or remove it\n" | ||
| ISSUE_CONTENT+="3. If the link is valid but fails the check, consider adding it to the ignore list in `.github/docs/.lycheeignore`\n\n" | ||
| # Use cat with heredoc instead of echo -e for more reliable newline handling | ||
| cat << 'EOT' >> /tmp/issue-guidance.txt | ||
| ### Additional Guidance | ||
| - For 404 errors: Check if the resource was moved or renamed | ||
| - For timeout errors: The site might be temporarily down, consider retrying | ||
| - For redirect issues: Update to the final URL | ||
| EOT | ||
| ISSUE_CONTENT+=$(cat /tmp/issue-guidance.txt) | ||
| ISSUE_CONTENT+="### For Broken Cross-References\n\n" | ||
| ISSUE_CONTENT+="1. Update references to deleted or renamed files\n" | ||
| ISSUE_CONTENT+="2. Update references to removed headings\n" | ||
| ISSUE_CONTENT+="3. Check for references in both documentation and code\n\n" | ||
| ISSUE_CONTENT+="---\n\nThis issue was automatically created by the Documentation Post-Merge Checks workflow." | ||
| # Save for issue creation | ||
| echo "issue_title<<EOF" >> $GITHUB_OUTPUT | ||
| echo "$ISSUE_TITLE" >> $GITHUB_OUTPUT | ||
| echo "EOF" >> $GITHUB_OUTPUT | ||
| echo "issue_content<<EOF" >> $GITHUB_OUTPUT | ||
| echo -e "$ISSUE_CONTENT" >> $GITHUB_OUTPUT | ||
| echo "EOF" >> $GITHUB_OUTPUT | ||
| echo "has_issues=true" >> $GITHUB_OUTPUT | ||
| else | ||
| echo "No issues found in documentation checks" | ||
| echo "has_issues=false" >> $GITHUB_OUTPUT | ||
| fi | ||
| # Create a single GitHub issue for all problems found | ||
| - name: Create GitHub issue | ||
| if: steps.process-results.outputs.has_issues == 'true' | ||
| id: create-issue | ||
| uses: peter-evans/create-issue-from-file@v4.0.1 | ||
| with: | ||
| title: ${{ steps.process-results.outputs.issue_title }} | ||
| content: ${{ steps.process-results.outputs.issue_content }} | ||
| labels: | | ||
| documentation | ||
| bug | ||
| needs-triage | ||
| # Configure assignee through CODEOWNERS or a team instead of hardcoding | ||
| # Additional reviewers can be added in codeowners file or docs team | ||
| # Log result for troubleshooting | ||
| - name: Log issue creation status | ||
| if: steps.process-results.outputs.has_issues == 'true' | ||
| run: | | ||
| if [ -n "${{ steps.create-issue.outputs.issue-number }}" ]; then | ||
| echo "✅ GitHub issue #${{ steps.create-issue.outputs.issue-number }} created successfully" | ||
| else | ||
| echo "⚠️ Failed to create GitHub issue for documentation issues" | ||
| echo "Check GitHub API permissions and rate limits" | ||
| fi | ||
| # Slack notification removed per request | ||