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: "Publish the combined report to the rolling docs-content issue. A manual run only covers one version/language, so it will overwrite the scheduled run's fuller report."
        type: boolean
        required: false
        default: false

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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - 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/create-workflow-failure-issue
        id: create-failure-issue
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

      - uses: ./.github/actions/slack-alert
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
          issue_url: ${{ steps.create-failure-issue.outputs.issue_url }}

  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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - uses: ./.github/actions/node-npm-setup

      # 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 }}
          # Include the JSON alongside the Markdown so the structured report is
          # consumable outside this job, not just readable in the issue body.
          path: artifacts/link-report-*
          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 directives = redirectGroups.map(g => {
              const occ = g.occurrences[0]
              const redirectTarget = occ?.redirectTarget ?? 'unknown'
              const file = occ?.file ?? 'unknown'
              const lines = (occ?.lines ?? []).join(', ') || 'unknown'
              return `- Update \`${g.target}\` to \`${redirectTarget}\` in \`${file}\` (line(s): ${lines})`
            }).join('\n')

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

            const bodyLines = [
              'Copilot, fix the redirected internal links listed below. All changes should be made within the `github/docs-internal` repository.',
              '',
              'For each directive below, open the specified file and find the old link path. Replace it with the new link path exactly as shown. Do not invent or guess link paths — only use the exact paths provided in each directive.',
              '',
              '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 update',
              '',
              directives,
            ]

            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: 'Follow each directive in the issue exactly. Each directive specifies a file, the old link to find, and the new link to replace it with. Use only the exact paths provided — do not invent or guess any link paths. 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/create-workflow-failure-issue
        id: create-failure-issue
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

      - uses: ./.github/actions/slack-alert
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
          issue_url: ${{ steps.create-failure-issue.outputs.issue_url }}

  # 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
    # Serialize publishing so two overlapping runs can't both create a
    # "rolling" issue, or write their results out of order.
    concurrency:
      group: broken-internal-links-report
      cancel-in-progress: false
    permissions:
      contents: read
      issues: write
    steps:
      - name: Checkout
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - uses: ./.github/actions/node-npm-setup

      - 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
        env:
          ACTION_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          # A version with no broken links uploads no report, so the files on disk undercount
          # what was checked. Pass the matrix so the report can say "broken in all versions"
          # and mean it.
          MATRIX: ${{ needs.setup-matrix.outputs.matrix }}
        run: |
          # Merge the per-version JSON rather than concatenating the rendered Markdown.
          # A link broken in every version is one problem, not one per version.
          if ls reports/*.json 1> /dev/null 2>&1; then
            echo "has_reports=true" >> $GITHUB_OUTPUT
            VERSIONS=$(echo "$MATRIX" | jq -r '[.include[] | "\(.version) \(.language)"] | join(",")')
            npm run combine-link-reports -- \
              --input reports \
              --output combined-report.md \
              --versions "$VERSIONS" \
              --action-url "$ACTION_RUN_URL"
          else
            echo "has_reports=false" >> $GITHUB_OUTPUT
            echo "No broken link reports generated - all links valid!"
          fi

      - name: Create or update the rolling report issue
        if: |
          steps.combine.outputs.has_reports == 'true'
          && needs.check-internal-links.result == 'success'
          && (github.event_name != 'workflow_dispatch' || inputs.create_report)
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
        with:
          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
          script: |
            const fs = require('fs')
            const title = '🔗 Broken Internal Links Report'
            const owner = 'github'
            const repo = 'docs-content'
            const label = 'broken link report'

            // GitHub rejects issue bodies over 65536 characters with a 422. The
            // internal report routinely exceeds that, so truncate and point at
            // the run artifact for the full contents.
            const MAX_BODY_SIZE = 60000
            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`
            let body = fs.readFileSync('combined-report.md', 'utf8')
            if (body.length > MAX_BODY_SIZE) {
              const notice = `\n\n---\n\n*Report truncated. Download the full report from the [workflow run artifacts](${runUrl}).*`
              body = body.slice(0, MAX_BODY_SIZE - notice.length) + notice
              core.warning(`Report exceeded ${MAX_BODY_SIZE} characters, so it was truncated.`)
            }

            // Reuse a single rolling issue instead of opening a new one every
            // week, which floods the first responders' board. Find the open
            // report issues (newest first).
            const open = await github.paginate(github.rest.issues.listForRepo, {
              owner,
              repo,
              state: 'open',
              labels: label,
              per_page: 100,
            })
            const reportIssues = open
              .filter((issue) => !issue.pull_request && issue.title === title)
              .sort((a, b) => b.number - a.number)

            if (reportIssues.length === 0) {
              const created = await github.rest.issues.create({
                owner,
                repo,
                title,
                body,
                labels: [label],
              })
              core.info(`Created rolling report issue: ${created.data.html_url}`)
              return
            }

            // Refresh the newest open report in place and close any older
            // duplicates so exactly one canonical issue remains.
            const [canonical, ...superseded] = reportIssues
            await github.rest.issues.update({
              owner,
              repo,
              issue_number: canonical.number,
              title,
              body,
            })
            core.info(`Updated rolling report issue: ${canonical.html_url}`)

            // Attempt every duplicate even if one fails, so a single transient
            // API error doesn't leave the rest open.
            const results = await Promise.allSettled(
              superseded.map(async (issue) => {
                await github.rest.issues.createComment({
                  owner,
                  repo,
                  issue_number: issue.number,
                  body: `Superseded by the current rolling report: #${canonical.number}.`,
                })
                await github.rest.issues.update({
                  owner,
                  repo,
                  issue_number: issue.number,
                  state: 'closed',
                  state_reason: 'not_planned',
                })
                core.info(`Closed superseded report issue #${issue.number}`)
              }),
            )
            const failures = results.filter((result) => result.status === 'rejected')
            if (failures.length > 0) {
              throw new AggregateError(
                failures.map((failure) => failure.reason),
                `Failed to close ${failures.length} superseded report issue(s).`,
              )
            }

      - name: Close the rolling report issue when all links are valid
        if: |
          steps.combine.outputs.has_reports == 'false'
          && needs.check-internal-links.result == 'success'
          && github.event_name != 'workflow_dispatch'
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
        with:
          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
          script: |
            const title = '🔗 Broken Internal Links Report'
            const owner = 'github'
            const repo = 'docs-content'
            const label = 'broken link report'

            // A clean run means the open report is stale. Leaving it open would
            // keep fixed failures on the first responders' board.
            const open = await github.paginate(github.rest.issues.listForRepo, {
              owner,
              repo,
              state: 'open',
              labels: label,
              per_page: 100,
            })
            const reportIssues = open.filter(
              (issue) => !issue.pull_request && issue.title === title,
            )

            if (reportIssues.length === 0) {
              core.info('No open report issue to close.')
              return
            }

            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`
            const results = await Promise.allSettled(
              reportIssues.map(async (issue) => {
                await github.rest.issues.createComment({
                  owner,
                  repo,
                  issue_number: issue.number,
                  body: `All internal links are valid as of the [latest run](${runUrl}). Closing this report. A new one opens if links break again.`,
                })
                await github.rest.issues.update({
                  owner,
                  repo,
                  issue_number: issue.number,
                  state: 'closed',
                  state_reason: 'completed',
                })
                core.info(`Closed resolved report issue #${issue.number}`)
              }),
            )
            const failures = results.filter((result) => result.status === 'rejected')
            if (failures.length > 0) {
              throw new AggregateError(
                failures.map((failure) => failure.reason),
                `Failed to close ${failures.length} resolved report issue(s).`,
              )
            }

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

      - uses: ./.github/actions/slack-alert
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
          issue_url: ${{ steps.create-failure-issue.outputs.issue_url }}