link-check-internal.yml

name: 'Link Check: Internal'

on:
  schedule:
    - cron: '20 16 * * 1' # Run every Monday at 16:20 UTC / 8:20 PST
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to check (e.g., free-pro-team@latest, enterprise-server@3.19)'
        type: string
        required: true
      language:
        description: 'Language to check (e.g., en, es, ja)'
        type: string
        required: true
        default: 'en'
      create_copilot_issue:
        description: 'Create a Copilot-assigned issue with the top 10 redirects to fix'
        type: boolean
        required: false
        default: false
      create_report:
        description: 'Create the combined broken links report issue in docs-content'
        type: boolean
        required: false
        default: true

permissions:
  contents: read

jobs:
  # Determine which version/language combos to run
  setup-matrix:
    if: github.repository == 'github/docs-internal'
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - name: Checkout
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1

      - uses: ./.github/actions/node-npm-setup

      - name: Set matrix
        id: set-matrix
        run: |
          if [[ "${EVENT_NAME}" == "workflow_dispatch" ]]; then
            # Manual run: use the provided version and language
            echo "matrix={\"include\":[{\"version\":\"${INPUT_VERSION}\",\"language\":\"${INPUT_LANGUAGE}\"}]}" >> $GITHUB_OUTPUT
          else
            # Scheduled run: English free-pro-team + English latest enterprise-server
            LATEST_GHES=$(npx tsx -e "import { latest } from './src/versions/lib/enterprise-server-releases'; console.log(latest)")
            echo "matrix={\"include\":[{\"version\":\"free-pro-team@latest\",\"language\":\"en\"},{\"version\":\"enterprise-server@${LATEST_GHES}\",\"language\":\"en\"}]}" >> $GITHUB_OUTPUT
          fi
        env:
          EVENT_NAME: ${{ github.event_name }}
          INPUT_VERSION: ${{ inputs.version }}
          INPUT_LANGUAGE: ${{ inputs.language }}

      - uses: ./.github/actions/slack-alert
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
          slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}

      - uses: ./.github/actions/create-workflow-failure-issue
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

  check-internal-links:
    if: github.repository == 'github/docs-internal'
    needs: setup-matrix
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.setup-matrix.outputs.matrix) }}
    env:
      # Disable Elasticsearch for faster warmServer
      ELASTICSEARCH_URL: ''
    steps:
      - name: Checkout
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1

      - uses: ./.github/actions/node-npm-setup

      - name: Install dependencies
        run: npm ci

      # Clone translations if not English
      - name: Clone translations
        if: matrix.language != 'en'
        uses: ./.github/actions/clone-translations
        with:
          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

      - name: Check internal links
        env:
          VERSION: ${{ matrix.version }}
          LANGUAGE: ${{ matrix.language }}
          CHECK_ANCHORS: true
          ACTION_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: npm run check-links-internal

      - name: Upload report artifact
        if: always()
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: link-report-${{ matrix.version }}-${{ matrix.language }}
          path: artifacts/link-report-*.md
          retention-days: 5
          if-no-files-found: ignore

      - name: Create Copilot redirect issue
        if: inputs.create_copilot_issue
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
        with:
          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
          script: |
            const fs = require('fs')
            const reportFile = 'artifacts/link-report-${{ matrix.version }}-${{ matrix.language }}.json'

            if (!fs.existsSync(reportFile)) {
              core.info('No JSON report found — all links valid, skipping Copilot issue.')
              return
            }

            const report = JSON.parse(fs.readFileSync(reportFile, 'utf8'))
            const allRedirectGroups = report.groups.filter(g => g.isWarning)
            const redirectGroups = allRedirectGroups.slice(0, 10)

            if (redirectGroups.length === 0) {
              core.info('No redirect groups found, skipping Copilot issue.')
              return
            }

            const tableRows = redirectGroups.map(g => {
              const occ = g.occurrences[0]
              const redirectTarget = occ?.redirectTarget ?? 'unknown'
              const file = occ?.file ?? 'unknown'
              const lines = (occ?.lines ?? []).join(', ')
              return `| \`${g.target}\` | \`${redirectTarget}\` | \`${file}\` | ${lines} |`
            }).join('\n')

            const artifactsUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}/artifacts`

            const bodyLines = [
              'Copilot please fix the redirected internal links listed in the table below. All changes should be made within the `github/docs-internal` repository. For each entry, open the source file and replace the **Current Link** with the **Update To** path.',
              'When all changes are made, open a pull request in `github/docs-internal` with the fixes. The pull request description should reference this issue to create a link between them. When the pull request is open, leave a comment on this issue with a link to it.',
              '',
              `These are the first ${redirectGroups.length} of ${allRedirectGroups.length} redirects found.`,
              '',
              '## Redirects to fix',
              '',
              '| Current Link | Update To | File | Line(s) |',
              '|---|---|---|---|',
              tableRows,
            ]

            const MAX_ISSUE_BODY_LENGTH = 65536
            const artifactNote = `\n\n> [!NOTE]\n> The report was truncated because it exceeded the issue body length limit. [View the complete redirect report in the workflow artifacts](${artifactsUrl}).`

            let body = bodyLines.join('\n')
            if (body.length > MAX_ISSUE_BODY_LENGTH) {
              const truncatedLength = MAX_ISSUE_BODY_LENGTH - artifactNote.length
              const lastNewline = body.lastIndexOf('\n', truncatedLength)
              body = body.slice(0, lastNewline > 0 ? lastNewline : truncatedLength) + artifactNote
            }

            // Use the REST API with agent_assignment to properly trigger Copilot cloud agent.
            // See: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions#using-the-rest-api
            const issue = await github.request('POST /repos/{owner}/{repo}/issues', {
              owner: 'github',
              repo: 'docs-content',
              title: '[Copilot Task] Fix top redirect links: ${{ matrix.version }}/${{ matrix.language }}',
              body,
              labels: ['broken link report'],
              assignees: ['copilot-swe-agent[bot]'],
              agent_assignment: {
                target_repo: 'github/docs-internal',
                base_branch: 'main',
                custom_instructions: 'For each entry in the table, open the source file in the github/docs-internal repository and replace the Current Link with the Update To path. When all changes are made, open a pull request in github/docs-internal with the fixes. When the pull request is open, leave a comment on this issue with a link to it.',
              },
            })

            core.info(`Created Copilot redirect issue: ${issue.data.html_url}`)

      - uses: ./.github/actions/slack-alert
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
          slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}

      - uses: ./.github/actions/create-workflow-failure-issue
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

  # Create combined report after all matrix jobs complete
  create-report:
    if: always() && github.repository == 'github/docs-internal'
    needs: [setup-matrix, check-internal-links]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - name: Checkout
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1

      - name: Download all artifacts
        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
        with:
          path: reports
          pattern: link-report-*
          merge-multiple: true

      - name: Combine reports
        id: combine
        run: |
          # Check if any reports exist
          if ls reports/*.md 1> /dev/null 2>&1; then
            echo "has_reports=true" >> $GITHUB_OUTPUT

            # Combine all markdown reports
            echo "# Internal Links Report" > combined-report.md
            echo "" >> combined-report.md
            echo "> [!NOTE]" >> combined-report.md
            echo "> **No action needed right now.** The link checker is being actively worked on and may produce false positives. You can safely ignore this report for now. We'll let you know when it's reliable." >> combined-report.md
            echo "" >> combined-report.md
            echo "Generated: $(date -u +'%Y-%m-%d %H:%M UTC')" >> combined-report.md
            echo "[Action run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})" >> combined-report.md
            echo "" >> combined-report.md

            for report in reports/*.md; do
              echo "---" >> combined-report.md
              cat "$report" >> combined-report.md
              echo "" >> combined-report.md
            done
          else
            echo "has_reports=false" >> $GITHUB_OUTPUT
            echo "No broken link reports generated - all links valid!"
          fi

      - name: Create issue if broken links found
        if: steps.combine.outputs.has_reports == 'true' && (github.event_name != 'workflow_dispatch' || inputs.create_report != false)
        uses: peter-evans/create-issue-from-file@fca9117c27cdc29c6c4db3b86c48e4115a786710 # v5
        with:
          token: ${{ secrets.DOCS_BOT_PAT_BASE }}
          repository: github/docs-content
          title: '🔗 Broken Internal Links Report'
          content-filepath: combined-report.md
          labels: broken link report

      - uses: ./.github/actions/slack-alert
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
          slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}

      - uses: ./.github/actions/create-workflow-failure-issue
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          token: ${{ secrets.DOCS_BOT_PAT_BASE }}