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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

- name: Generate GitHub App token

id: app-token

uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0

with:

app-id: ${{ secrets.DOCS_BOT_APP_ID }}

private-key: ${{ secrets.DOCS_BOT_APP_PRIVATE_KEY }}

owner: github

repositories: docs-engineering

- 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_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}

- uses: ./.github/actions/create-workflow-failure-issue

if: ${{ failure() && github.event_name != 'workflow_dispatch' }}

with:

token: ${{ steps.app-token.outputs.token }}

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

- name: Generate GitHub App token

id: app-token

uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0

with:

app-id: ${{ secrets.DOCS_BOT_APP_ID }}

private-key: ${{ secrets.DOCS_BOT_APP_PRIVATE_KEY }}

owner: github

repositories: docs-content,docs-internal.es-es,docs-internal.ja-jp,docs-internal.pt-br,docs-internal.zh-cn,docs-internal.ru-ru,docs-internal.fr-fr,docs-internal.ko-kr,docs-internal.de-de,docs-engineering

- 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: ${{ steps.app-token.outputs.token }}

- 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: ${{ steps.app-token.outputs.token }}

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/slack-alert

if: ${{ failure() && github.event_name != 'workflow_dispatch' }}

with:

slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}

- uses: ./.github/actions/create-workflow-failure-issue

if: ${{ failure() && github.event_name != 'workflow_dispatch' }}

with:

token: ${{ steps.app-token.outputs.token }}

# 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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

- name: Generate GitHub App token

id: app-token

uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0

with:

app-id: ${{ secrets.DOCS_BOT_APP_ID }}

private-key: ${{ secrets.DOCS_BOT_APP_PRIVATE_KEY }}

owner: github

repositories: docs-content,docs-engineering

- 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 "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: ${{ steps.app-token.outputs.token }}

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_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}

- uses: ./.github/actions/create-workflow-failure-issue

if: ${{ failure() && github.event_name != 'workflow_dispatch' }}

with:

token: ${{ steps.app-token.outputs.token }}