Repo sync

.github/workflows/enterprise-dates.yml

@@ -1,17 +1,12 @@
 name: Enterprise date updater
 
-# **What it does**: Runs on a schedule to update
-# src/ghes-releases/lib/enterprise-dates.json.
-# **Why we have it**: The src/ghes-releases/lib/enterprise-dates.json
-# file needs to be up-to-date for the
-# Used to display deprecation banner dates and as a reference
-# for all past server release numbers.
-# **Who does it impact**: Docs engineering, docs content.
+# Keep src/ghes-releases/lib/enterprise-dates.json current for deprecation banner dates
+# and historical GitHub Enterprise Server release references.
 
 on:
   workflow_dispatch:
   schedule:
-    - cron: '20 16 * * 1' # Run every Monday at 16:20 UTC / 8:20 PST
+    - cron: '20 16 * * 1'
 
 permissions:
   contents: write
@@ -36,10 +31,11 @@ jobs:
         id: create-pull-request
         uses: peter-evans/create-pull-request@98357b18bf14b5342f975ff684046ec3b2a07725 # pin @v8.0.0
         env:
-          # Disable pre-commit hooks; they don't play nicely here
+          # Create-pull-request runs git commands itself, so disable hooks that can
+          # change the worktree.
           HUSKY: '0'
         with:
-          # need to use a token with repo and workflow scopes for this step
+          # This PR update requires repo and workflow scopes.
           token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           commit-message: '🤖 ran src/ghes-releases/scripts/update-enterprise-dates.ts'
           title: 🤖 src/ghes-releases/lib/enterprise-dates.json update

.github/workflows/enterprise-release-issue.yml

@@ -1,13 +1,12 @@
 name: Open Enterprise release or deprecation issue
 
-# **What it does**: Checks if there is an Enterprise release or deprecation upcoming, and if so, opens an issue with the tasks to be completed.
-# **Why we have it**: GHES releases and deprecations run on a predictable schedule, so we can automate some of the project management aspects.
-# **Who does it impact**: Docs engineering, docs content.
+# GHES releases and deprecations follow a predictable schedule, so this workflow opens
+# their planning issues automatically.
 
 on:
   workflow_dispatch:
   schedule:
-    - cron: '20 16 * * 1' # Run every Monday at 16:20 UTC / 8:20 PST
+    - cron: '20 16 * * 1'
 
 permissions:
   contents: read

.github/workflows/expertise-required-label-message.yml

@@ -1,8 +1,6 @@
 name: Expertise Required label message
 
-# **What it does**: Adds a bot comment stating a certain level of expertise is required to a docs-content issue when the `contributor-expertise-required` label is applied
-# **Why we have it**: We need a method to surface a message denoting if an issue requires a certain level of expertise in order to be resolved
-# **Who does it impact**: Open Source and Hubbers
+# Surface contributor expertise requirements directly on labeled github/docs issues.
 
 on:
   issues:

.github/workflows/feedback-prompt.yml

@@ -10,9 +10,8 @@ permissions:
 
 jobs:
   comment-on-pr:
-    # This workflow should only run on the 'github/docs-internal' repository because it posts a feedback request
-    # to non-Docs team contributors when their PR is merged into the main branch.
-    # The feedback request asks contributors to leave feedback on their contributing experience in Slack.
+    # Ask merged main-branch pull request authors for feedback when they are outside
+    # the docs-content team.
     if: github.repository == 'github/docs-internal' && github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main'
 
     runs-on: ubuntu-latest
@@ -26,16 +25,13 @@ jobs:
           script: |
             try {
               const pr = context.payload.pull_request;
-              // Team is addressed by numeric ID (org github = 9919, team docs-content = 2796154)
-              // because IDs survive team renames and slugs do not.
+              // Numeric IDs survive team renames; slugs do not. GitHub org 9919, docs-content team 2796154.
               await github.request('GET /organizations/{org_id}/team/{team_id}/memberships/{username}', {
                 org_id: 9919,
                 team_id: 2796154,
                 username: pr.user.login,
               });
-              // Author is in the team. Do nothing!
             } catch(err) {
-              // Author not in team
               core.exportVariable('NON_DOCS_HUBBER', 'true');
             }
 
@@ -66,7 +62,6 @@ jobs:
                 " - Thanks for your contribution! " +
                 "If you think something could be improved about the contributor experience, please post in `#docs-contributor-feedback` on Slack.";
             } else {
-              // nobody to mention!
               commentBody =
                 "👋 Thanks for your contribution! " +
                 "If you think something could be improved about the contributor experience, please post in `#docs-contributor-feedback` on Slack.";

.github/workflows/first-responder-v2-prs-collect.yml

@@ -1,8 +1,6 @@
 name: Add maintenance PRs to the docs-content FR project v2
 
-# **What it does**: Adds docs-internal pull requests authored by docs-bot to the docs-content FR project v2
-# **Why we have it**: So we don't lose track of maintenance pull requests for docs-content to review
-# **Who does it impact**: Docs content
+# The docs-content FR project is the review queue for docs-bot maintenance pull requests.
 
 on:
   pull_request:
@@ -25,10 +23,6 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-
-      # Add to the FR project
-      # and set type to "Maintenance"
-      # and set date to now
       - name: Triage to docs-content FR project
         env:
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}

.github/workflows/generate-code-scanning-query-lists.yml

@@ -1,11 +1,7 @@
 name: Generate code scanning query lists
 
-# **What it does**: This workflow is currently run manually approximately every two weeks as part
-#      of the release process for the CodeQL CLI. We hope to automate this in the future
-#   When run, this workflow generates updated query lists with data from the codeql
-#   repository, and creates a pull request if there are updates.
-# **Why we have it**: So we can automate CodeQL query tables and show code scanning users the built in queries.
-# **Who does it impact**: Anyone making CodeQL query suite changes in `github/codeql`, and wanting to get them published on the docs site.
+# Manual CodeQL CLI release runs, about every two weeks, generate query table reusables
+# from github/codeql and open a pull request when they change.
 
 on:
   workflow_dispatch:
@@ -53,16 +49,14 @@ jobs:
           echo "Copied files from github/codeql repo. Commit SHA: $OPENAPI_COMMIT_SHA"
 
       - name: Download CodeQL CLI
-        # Look under the `codeql` directory, as this is where we checked out the `github/codeql` repo
+        # fetch-codeql lives in the checked-out github/codeql repository.
         uses: ./codeql/.github/actions/fetch-codeql
 
       - name: Test CodeQL CLI Download
         shell: bash
         run: codeql --version
 
-      # "Server for running multiple commands while avoiding repeated JVM initialization."
-      # Having started this should speed up the execution of the various
-      # CLI calls of the executable.
+      # Start the CodeQL CLI server once so later CodeQL commands avoid repeated JVM initialization.
       - name: Start CodeQL CLI server in the background
         shell: bash
         run: |
@@ -72,10 +66,8 @@ jobs:
 
       - uses: ./.github/actions/install-cocofix
         with:
-          # The Docs Engineering Bot app cannot read the org-scoped
-          # @github/cocofix package (its Packages permission is repo-level
-          # only), so this step keeps using the PAT until the app is granted
-          # organization package read access.
+          # The Docs Engineering Bot app has repo-level Packages permission and cannot
+          # read org-scoped packages, so cocofix installation requires the PAT.
           token: ${{ secrets.DOCS_BOT_PAT_BASE }}
 
       - name: Build code scanning security query lists
@@ -123,16 +115,14 @@ jobs:
           echo "Copied files from github/codeql repo. Commit SHA: $OPENAPI_COMMIT_SHA"
 
       - name: Download CodeQL CLI
-        # Look under the `codeql` directory, as this is where we checked out the `github/codeql` repo
+        # fetch-codeql lives in the checked-out github/codeql repository.
         uses: ./codeql/.github/actions/fetch-codeql
 
       - name: Test CodeQL CLI Download
         shell: bash
         run: codeql --version
 
-      # "Server for running multiple commands while avoiding repeated JVM initialization."
-      # Having started this should speed up the execution of the various
-      # CLI calls of the executable.
+      # Start the CodeQL CLI server once so later CodeQL commands avoid repeated JVM initialization.
       - name: Start CodeQL CLI server in the background
         shell: bash
         run: |
@@ -210,12 +200,10 @@ jobs:
         shell: bash
         run: |
 
-          # When we started, we downloaded the CodeQL CLI here in this workflow.
-          # We have no intention of checking that in but we also don't want
-          # `git status ...` to show it as an untracked file.
+          # Git status must only report generated query tables, so remove the
+          # checked-out CodeQL repository.
           rm -fr ./codeql
 
-          # If nothing to commit, exit now. It's fine. No orphans.
           changes=$(git diff --name-only | wc -l)
           untracked=$(git status --untracked-files --short | wc -l)
           if [[ $changes -eq 0 ]] && [[ $untracked -eq 0 ]]; then
@@ -228,12 +216,10 @@ jobs:
 
           branchname=codeql-query-tables-${{ steps.codeql.outputs.OPENAPI_COMMIT_SHA }}
 
-          # Exit if the branch already exists. Since the actions/checkout fetch-depth is 1,
-          # it doesn't "know" about branches locally, so we need to manually list them.
+          # Query the remote because actions/checkout with fetch-depth 1 omits other remote-tracking branches.
           branchExists=$(git ls-remote --heads origin refs/heads/$branchname | wc -l)
 
-          # When run on a pull_request, we're just testing the tooling.
-          # Exit before it actually pushes the possible changes.
+          # Pull request runs validate generated files without pushing branches.
           if [ "$DRY_RUN" = "true" ]; then
             echo "Dry-run mode when run in a pull request"
             echo "See the 'Insight into diff' step for the changes it would create PR about."

.github/workflows/headless-tests.yml

@@ -1,10 +1,6 @@
 name: Headless Tests
 
-# **What it does**: This runs our browser tests to test things that depend
-#                   on client-side JavaScript.
-# **Why we have it**: Because most automated vitest tests only test static
-#                     input and outputs.
-# **Who does it impact**: Docs engineering, open-source engineering contributors.
+# Browser tests cover client-side JavaScript behavior that static Vitest tests miss.
 
 on:
   workflow_dispatch:
@@ -14,7 +10,7 @@ on:
 permissions:
   contents: read
 
-# This allows a subsequently queued workflow run to interrupt previous runs
+# Cancel older runs for the same ref to save runner time.
 concurrency:
   group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
   cancel-in-progress: true
@@ -27,8 +23,7 @@ jobs:
     if: github.repository == 'github/docs-internal' || github.repository == 'github/docs'
     runs-on: ubuntu-latest
     strategy:
-      # When we're comfortable a11y tests aren't generating false positives and helping,
-      # let's remove the matrix and just run playwright in a single job.
+      # Keep Playwright variants as separate checks while a11y false-positive rates settle.
       matrix:
         node:
           - playwright-rendering
@@ -58,11 +53,9 @@ jobs:
       - name: Run Playwright tests
         env:
           PLAYWRIGHT_WORKERS: ${{ fromJSON('[1, 4]')[github.repository == 'github/docs-internal'] }}
-          # workaround for https://github.com/nodejs/node/issues/59364 as of 22.18.0
+          # Supported Node runtimes can hit https://github.com/nodejs/node/issues/59364 without this flag.
           NODE_OPTIONS: '--no-experimental-strip-types'
           PLAYWRIGHT_TIMEOUT: ${{ matrix.node == 'playwright-a11y' && '60000' || '' }}
 
-        # Run playwright rendering tests and a11y tests (axe scans) as distinct checks
-        # so that we can run them without blocking merges until we can be confident
-        # results for a11y tests are meaningul and scenarios we're testing are correct.
+        # Keep a11y scans in a distinct check so branch protection can leave them non-blocking.
         run: npm run playwright-test -- ${{ matrix.node }} --reporter list

.github/workflows/hubber-contribution-help.yml

@@ -1,8 +1,6 @@
 name: Hubber contribution help
 
-# **What it does**: When a PR is opened by a non-Docs team Hubber, adds a bot comment with helpful links
-# **Why we have it**: To help non–Docs Hubbers navigate how to get a PR reviewed by the Docs team
-# **Who does it impact**: docs-internal contributors
+# Help non-Docs Hubbers route content pull requests to the Docs Content review board.
 
 on:
   pull_request:
@@ -31,8 +29,7 @@ jobs:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             try {
-              // Team is addressed by numeric ID (org github = 9919, team docs = 325922)
-              // because IDs survive team renames and slugs do not.
+              // Numeric IDs survive team renames; slugs do not. GitHub org 9919, docs team 325922.
               await github.request('GET /organizations/{org_id}/team/{team_id}/memberships/{username}', {
                 org_id: 9919,
                 team_id: 325922,

.github/workflows/index-autocomplete-search.yml

@@ -1,13 +1,11 @@
 name: Index autocomplete search in Elasticsearch
 
-# **What it does**: Indexes AI search autocomplete data into Elasticsearch.
-# **Why we have it**: So we can power the APIs for AI search autocomplete.
-# **Who does it impact**: docs-engineering
+# Keep Elasticsearch autocomplete data current for AI search APIs.
 
 on:
   workflow_dispatch:
   schedule:
-    - cron: '20 16 * * 1-5' # Run Mon-Fri at 16:20 UTC / 8:20 PST
+    - cron: '20 16 * * 1-5'
   pull_request:
     paths:
       - .github/workflows/index-autocomplete-search.yml

.github/workflows/index-general-search-pr.yml

@@ -1,33 +1,30 @@
 name: Index general search in Elasticsearch on PR
 
-# **What it does**: This does what `index-general-search-elasticsearch.yml` does but
-#                   with a localhost Elasticsearch and only for English.
-# **Why we have it**: To test that the script works and the popular pages json is valid.
-# **Who does it impact**: Docs engineering
+# Test general search indexing against local Elasticsearch and validate popular pages JSON
+# before merge.
 
 on:
   workflow_dispatch:
   pull_request:
     paths:
       - 'src/search/**'
       - 'package*.json'
-      # For debugging this workflow
+      # Debugging changes to this workflow need the same PR index test.
       - .github/workflows/index-general-search-pr.yml
-      # Make sure we run this if the composite action changes
+      # Setup changes can break the local Elasticsearch path this workflow tests.
       - .github/actions/setup-elasticsearch/action.yml
 
 permissions:
   contents: read
 
-# This allows a subsequently queued workflow run to interrupt previous runs
+# Cancel older runs for the same ref to save runner time.
 concurrency:
   group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
   cancel-in-progress: true
 
 env:
   ELASTICSEARCH_URL: http://localhost:9200
-  # Since we'll run in NDOE_ENV=production, we need to be explicit that
-  # we don't want Hydro configured.
+  # Empty Hydro credentials keep production-mode test runs from sending analytics.
   HYDRO_ENDPOINT: ''
   HYDRO_SECRET: ''
 
@@ -43,7 +40,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           repository: github/docs-internal-data
-          # This works because user `docs-bot` has read access to that private repo.
+          # docs-bot can read the private github/docs-internal-data repository.
           token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           path: docs-internal-data
 
@@ -62,7 +59,6 @@ jobs:
         run: |
           npm run general-search-scrape-server > /tmp/stdout.log 2> /tmp/stderr.log &
 
-          # first sleep to give it a chance to start
           sleep 6
           curl --retry-connrefused --retry 6 -I http://localhost:4002/
 
@@ -76,13 +72,9 @@ jobs:
 
       - name: Scrape records into a temp directory
         env:
-          # If a reusable, or anything in the `data/*` directory is deleted
-          # you might get a
-          #
-          #   RenderError: Can't find the key 'site.data.reusables...' in the scope
-          #
-          # But that'll get fixed in the next translation pipeline. For now,
-          # let's just accept an empty string instead.
+          # Deleting a reusable or data/* entry can leave translations pointing at missing
+          # site.data keys and trigger RenderError. Accept empty strings until the next
+          # translation pipeline removes those references.
           THROW_ON_EMPTY: false
 
           DOCS_INTERNAL_DATA: docs-internal-data