docs/.github/workflows/validate-github-github-docs-urls.yml

name: Validate github/github docs URLs

# **What it does**: Checks the URLs in docs-urls.json in github/github
# **Why we have it**: To ensure the values in docs-urls.json are perfect.
# **Who does it impact**: Docs content.

on:
  workflow_dispatch:
  schedule:
    - cron: '20 16 * * 1' # Run every Monday at 16:20 UTC / 8:20 PST
  pull_request:
    paths:
      - 'content/**'
      # In case a relevant dependency changes
      - 'package*.json'
      # The scripts
      - 'src/links/scripts/validate-github-github-docs-urls/**'
      # The workflow
      - .github/workflows/validate-github-github-docs-urls.yml

permissions:
  contents: read
  issues: write
  pull-requests: write

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
jobs:
  validate_github_github_docs_urls:
    name: Validate github/github docs URLs
    if: github.repository == 'github/docs-internal'
    runs-on: ubuntu-20.04-xl
    steps:
      - name: Check out repo's default branch
        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
        with:
          # Picking this number is a "best guess". If we make it too large,
          # the checkout will take potentially unnecessariily long.
          # This reduces the chance that tj-actions/changed-files has to
          # fetch deeper history. But if it needs to, it will.
          fetch-depth: 10

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

      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
        with:
          token: ${{ secrets.DOCS_BOT_PAT_READPUBLICKEY }}
          repository: github/github
          ref: master
          path: github

      - name: Run validation
        run: |
          # This will generate a .json file which we can use to
          # do other things in other steps.
          npm run validate-github-github-docs-urls -- validate \
            --output checks.json \
            github/config/docs-urls.json

      - name: Update config/docs-urls.json in github/github (possibly)
        if: ${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}
        env:
          GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_WRITEORG_PROJECT }}
        run: |
          npm run validate-github-github-docs-urls -- generate-new-json checks.json github/config/docs-urls.json

          cd github
          git status
          git diff
          changes=$(git diff --name-only | wc -l)
          if [[ $changes -eq 0 ]]; then
            echo "There are no changes to commit after running generate-new-json. Exiting this step"
            exit 0
          fi

          current_timestamp=$(date '+%Y-%m-%d-%H%M%S')
          branch_name="update-docs-urls-$current_timestamp"
          git checkout -b "$branch_name"
          current_daystamp=$(date '+%Y-%m-%d')
          git commit -a -m "Update Docs URLs from automation ($current_daystamp)"
          git push origin "$branch_name"

          # XXX TODO
          # Perhaps post an issue somewhere, about that the fact that this
          # branch has been created and now needs to be turned into a PR
          # that some human can take responsibility for.

      - name: Clean up old branches in github/github
        if: ${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}
        env:
          GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_WRITEORG_PROJECT }}
        run: |
          npm run validate-github-github-docs-urls -- clean-up-old-branches --prefix update-docs-urls

          echo "To see them all, go to:"
          echo "https://github.com/github/github/branches/all?query=update-docs-urls-"

      # If a PR comes along to github/docs-internal that causes some
      # URLs in docs-urls.json (in github/github) to now fail, then
      # we'll want to make the PR author+reviewer aware of this.
      # For example, you moved a page without setting up a redirect.
      # Or you edited a heading that now breaks a URL with fragment.
      # In the latter case, you might want to update the URL in docs-urls.json
      # after this PR has landed, or consider using `<a name="..."></a>` as a
      # workaround for the time being.
      # First, gather the URLs that were relevant
      - name: Get changed content/data files
        if: ${{ github.event_name == 'pull_request' }}
        id: changed-files
        uses: tj-actions/changed-files@1754cd4b9e661d1f0eced3b33545a8d8b3bc46d8 # v44.5.0
        with:
          # No need to escape the file names because we make the output of
          # tj-actions/changed-files be set as an environment variable. Not
          # as a direct input to the line of bash that uses it.
          safe_output: false
          files: |
            content/**

      - name: Generate PR comment
        if: ${{ github.event_name == 'pull_request' && steps.changed-files.outputs.any_changed == 'true' }}
        env:
          # Make it an environment variable so that its value doesn't need to be escaped.
          # See https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-variable
          CHANGED_FILES: |-
            ${{ steps.changed-files.outputs.all_changed_files }}
          GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_WRITEORG_PROJECT }}
          ISSUE_NUMBER: ${{ github.event.pull_request.number }}
          REPOSITORY: ${{ github.repository }}
        run: npm run validate-github-github-docs-urls -- post-pr-comment checks.json --changed-files $CHANGED_FILES

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