Repo sync

.github/workflows/send-to-triage-board.yml

@@ -1,8 +1,7 @@
 name: Add new issues and PRs to central triage board
 
-# **What it does**: Adds newly opened or reopened issues and pull requests in github/docs to the right place for triage, and stamps the item with today's date.
-# **Why we have it**: To ensure incoming work in the public docs repo is triaged properly.
-# **Who does it impact**: Writers, FRs.
+# Adds new, reopened, and ready-for-review github/docs work to the Central Triage Group board.
+# Sets today's date so first responders can triage it.
 
 on:
   issues:
@@ -22,7 +21,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
           ITEM_URL: ${{ github.event.issue.html_url || github.event.pull_request.html_url }}
-          # Add to the Central Triage Group project board and set date to now
+          # These IDs point to the Central Triage Group board and its date field.
           PROJECT_NUMBER: '19598'
           PROJECT_ID: 'PVT_kwDNJr_OAJ4AfQ'
           DATE_FIELD_ID: 'PVTF_lADNJr_OAJ4Afc4IAbbv'

.github/workflows/site-policy-reminder.yml

@@ -1,8 +1,7 @@
 name: Site Policy Reminder
 
-# **What it does**: Automated comment reminder on a PR to change the title for public consumption before merging and to run the Site Policy repo sync action
-# **Why we have it**: Titles of merged PRs to Site Policies are sent to the public site-policy repo when the repos are synced
-# **Who does it impact**: Everyone merging changes to Site Policies
+# Site Policy PR titles appear in github/site-policy after sync, so they need public wording.
+# The reminder tells admins when to run the sync action.
 
 on:
   pull_request:

.github/workflows/site-policy-sync.yml

@@ -1,12 +1,8 @@
 name: Site policy sync
 
-# **What it does**: Creates a branch in our site-policy repo with changes to site policy docs.
-# **Why we have it**: We want to keep the site-policy repo up to date.
-# **Who does it impact**: site-policy-admins and Developer Policy teams.
+# Keeps github/site-policy current with internal site policy docs.
 
-# Controls when the action will run.
 on:
-  # Triggers the workflow pull requests merged to the main branch
   pull_request:
     branches:
       - main

.github/workflows/sme-review-tracking-issue.yml

@@ -1,14 +1,12 @@
 name: Create SME review tracking issue
 
-# **What it does**: Creates an SME review tracking issue when the `needs SME` label is applied to a PR or issue
-# **Why we have it**: We do not want to manually create an SME review tracking issue when an SME review is needed
-# **Who does it impact**: Hubbers
+# Creates a technical-content tracking issue when a github/docs PR or issue gets the needs SME label.
 
 on:
   issues:
     types:
       - labeled
-  # Required in lieu of `pull_request` so that this workflow can query users in org to determine membership.
+  # pull_request_target gives fork PRs the DOCS_BOT_PAT_BASE secret to create the issue.
   pull_request_target:
     types:
       - labeled
@@ -31,7 +29,6 @@ jobs:
 
             const issueNo = context.number || context.issue.number
 
-            // Create an issue in technical-content repo
             await github.rest.issues.create({
               owner: 'github',
               repo: 'technical-content',

.github/workflows/stale.yml

@@ -1,8 +1,6 @@
 name: Stale check for stalled pull requests in the docs-internal repository
 
-# **What it does**: Identifies pull requests that have been inactive for 30 days.
-# **Why we have it**: We want to avoid pull requests that are stalled and not being reviewed.
-# **Who does it impact**: Everyone that works in the internal repository.
+# Marks internal PRs stale after 30 inactive days and closes them 14 days later without a response.
 
 on:
   schedule:

.github/workflows/sync-audit-logs.yml

@@ -1,8 +1,6 @@
 name: Sync Audit Log data
 
-# **What it does**: This updates our Audit Logs schema.
-# **Why we have it**: We want our Audit Logs up to date.
-# **Who does it impact**: Docs engineering, people reading Audit Logs.
+# Keeps Audit Logs schema docs current with github/audit-log-allowlists.
 
 on:
   workflow_dispatch:
@@ -13,7 +11,7 @@ permissions:
   contents: write
   pull-requests: write
 
-# This allows a subsequently queued workflow run to interrupt previous runs
+# Cancel older syncs so stale schema data does not open older PRs.
 concurrency:
   group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
   cancel-in-progress: true
@@ -29,7 +27,7 @@ jobs:
 
       - name: Run updater script
         env:
-          # need to use a token from a user with access to github/audit-log-allowlists for this step
+          # DOCS_BOT_PAT_BASE can read github/audit-log-allowlists.
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
         run: |
           npm run sync-audit-log
@@ -47,14 +45,12 @@ jobs:
 
       - name: Create and merge pull request
         env:
-          # Needed for gh
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
         run: |
           echo "Creating a new branch if needed..."
           branchname=audit-logs-schema-update-${{ steps.audit-log-allowlists.outputs.COMMIT_SHA }}
           remotesha=$(git ls-remote --heads origin $branchname)
           if [ -n "$remotesha" ]; then
-            # output is not empty, it means the remote branch exists
             echo "Branch $branchname already exists in 'github/docs-internal'. Exiting..."
             exit 0
           fi
@@ -94,14 +90,14 @@ jobs:
             --head=$branchname
           echo "Created pull request"
 
-          # can't approve your own PR, approve with Actions
+          # docs-bot cannot approve its own PR, so GITHUB_TOKEN approves it.
           echo "Approving pull request..."
           unset GITHUB_TOKEN
           gh auth login --with-token <<< "${{ secrets.GITHUB_TOKEN }}"
           gh pr review --approve
           echo "Approved pull request"
 
-          # Actions can't merge the PR so back to docs-bot to merge the PR
+          # GITHUB_TOKEN cannot enable auto-merge here, so docs-bot enables it.
           echo "Setting pull request to auto merge..."
           unset GITHUB_TOKEN
           gh auth login --with-token <<< "${{ secrets.DOCS_BOT_PAT_BASE }}"

.github/workflows/sync-codeql-cli.yml

@@ -1,10 +1,7 @@
 name: Sync CodeQL CLI
 
-# **What it does**: This workflow is run manually approximately every two weeks.
-#   When run, this workflow syncs the CodeQL CLI automated pipeline with the semmle-code
-#   repository, and creates a pull request if there are updates.
-# **Why we have it**: So we can automate CodeQL CLI documentation.
-# **Who does it impact**: Anyone making CodeQL CLI changes in `github/semmle-code`, and wanting to get them published on the docs site.
+# Updates CodeQL CLI docs from github/semmle-code and opens a PR when files change.
+# Run it manually about every two weeks to publish upstream changes.
 
 on:
   workflow_dispatch:
@@ -19,7 +16,7 @@ permissions:
   contents: write
   pull-requests: write
 
-# This allows a subsequently queued workflow run to interrupt previous runs
+# Cancel older syncs so stale CodeQL CLI data does not open older PRs.
 concurrency:
   group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
   cancel-in-progress: true
@@ -34,8 +31,6 @@ jobs:
       - name: Checkout semmle-code repo
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
-          # By default, only the most recent commit of the `main` branch
-          # will be checked out
           token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           repository: github/semmle-code
           path: semmle-code
@@ -53,13 +48,9 @@ jobs:
 
       - name: Install pandoc
         run: |
-          # Remove all previous pandoc versions
           sudo apt-get purge --auto-remove pandoc
-          # Download pandoc
           wget https://github.com/jgm/pandoc/releases/download/3.0.1/pandoc-3.0.1-1-amd64.deb
-          # Install pandoc
           sudo dpkg -i pandoc-3.0.1-1-amd64.deb
-          # Output the pandoc version installed
           pandoc -v
           rm pandoc-3.0.1-1-amd64.deb
 
@@ -72,10 +63,9 @@ jobs:
 
       - name: Create pull request
         env:
-          # Needed for gh
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
         run: |
-          # If nothing to commit, exit now. It's fine. No orphans.
+          # Exit before branch creation so a no-op sync does not leave an orphan branch.
           changes=$(git diff --name-only | wc -l)
           untracked=$(git status --untracked-files --short | wc -l)
           if [[ $changes -eq 0 ]] && [[ $untracked -eq 0 ]]; then
@@ -92,13 +82,10 @@ jobs:
           git add .
           git commit -m "Update CodeQL CLI data"
 
-          # Force-push to handle reruns where the branch already exists on the
-          # remote from a prior failed attempt. Plain --force is safe here
-          # because these branches are exclusively managed by this workflow.
+          # Force-push reruns over failed attempts; this workflow exclusively owns these branches.
           git push --force -u origin $branchname
 
-          # If a PR already exists for this branch (e.g. a previous run
-          # succeeded but the workflow still reported failure), skip creation.
+          # Skip PR creation when a prior run already opened one for this branch.
           existing_pr=$(gh pr list --repo github/docs-internal --head "$branchname" --json number --jq '.[0].number')
           if [[ -n "$existing_pr" ]]; then
             echo "Pull request #$existing_pr already exists for branch $branchname. Skipping PR creation."

.github/workflows/sync-graphql.yml

@@ -1,8 +1,6 @@
 name: Sync GraphQL schema
 
-# **What it does**: This updates our GraphQL schemas.
-# **Why we have it**: We want our GraphQL docs up to date.
-# **Who does it impact**: Docs engineering, people reading GraphQL docs.
+# Keeps GraphQL docs current with schema changes from github/github.
 
 on:
   workflow_dispatch:
@@ -30,21 +28,20 @@ jobs:
       - name: Run updater scripts
         id: sync
         env:
-          # need to use a token from a user with access to github/github for this step
+          # DOCS_BOT_PAT_BASE can read github/github.
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
           NODE_OPTIONS: '--max-old-space-size=8192'
         run: npm run sync-graphql
       - name: Create pull request
         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
+          # Disable Husky because create-pull-request commits inside Actions.
           HUSKY: '0'
         with:
-          # Need to use a token with repo and workflow scopes for this step.
-          # Token should be a PAT because actions performed with GITHUB_TOKEN
-          # don't trigger other workflows and this action force pushes updates
-          # from the default branch.
+          # DOCS_BOT_PAT_BASE has repo and workflow scopes.
+          # GITHUB_TOKEN does not trigger follow-up workflows.
+          # create-pull-request force-pushes updates from the default branch.
           token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           commit-message: 'Update GraphQL data files'
           title: GraphQL schema update

.github/workflows/sync-llms-txt.yml

@@ -1,12 +1,7 @@
 name: Sync llms.txt
 
-# **What it does**: Generates docs.github.com/llms.txt, github.com/llms.txt, and
-#   github.com/llms-full.txt from the page catalog and popularity data, then
-#   opens PRs to update them.
-# **Why we have it**: Agents discover docs through llms.txt; the page list keeps
-#   pace with what's actually popular without writers updating it by hand.
-# **Who does it impact**: Docs consumers via agents, and anyone landing on
-#   github.com/llms.txt, github.com/llms-full.txt, or docs.github.com/llms.txt.
+# Generates docs.github.com/llms.txt, github.com/llms.txt, and github.com/llms-full.txt.
+# Uses the page catalog and popularity data, then opens PRs to update them.
 
 on:
   workflow_dispatch:
@@ -59,8 +54,6 @@ jobs:
             --output /tmp/monolith-llms.txt
           echo "Generated monolith llms.txt ($(wc -l < /tmp/monolith-llms.txt) lines, $(wc -c < /tmp/monolith-llms.txt) bytes)"
 
-      # ---------- PR to docs-internal: update data/llms-txt/docs.md ----------
-
       - name: Diff docs llms.txt against committed copy
         id: diff_docs
         run: |
@@ -97,11 +90,8 @@ jobs:
           git config user.name "docs-bot"
           git config user.email "77750099+docs-bot@users.noreply.github.com"
           git add data/llms-txt/docs.md
-          # diff_docs compares against main, but the sync branch may already
-          # exist with this exact content (open PR from a prior run). In that
-          # case there is nothing new to stage, and `git commit` would exit 1
-          # and fail the whole workflow. Skip the commit and push when the
-          # branch is already up to date.
+          # diff_docs compares against main, but an open sync-branch PR can already hold this content.
+          # Skip commit and push because git commit exits 1 with nothing staged.
           if git diff --cached --quiet; then
             echo "Sync branch already has the latest generated docs.md; nothing to commit."
           else
@@ -135,8 +125,6 @@ jobs:
             --draft \
             --label "llm-generated"
 
-      # ---------- PR to github/github: update public/llms*.txt ----------
-
       - name: Fetch current public llms files from github/github
         id: fetch_monolith
         env:

.github/workflows/sync-openapi.yml

@@ -1,8 +1,7 @@
 name: Sync OpenAPI schema
 
-# **What it does**: Syncs the REST, Webhooks, and GitHub Apps automated pipelines with the github/rest-api-description repository, and creates a pull request if there are updates to any of the data files we generate from the OpenAPI. Runs on a weekday schedule or a `sync-openapi` repository dispatch.
-# **Why we have it**: So we can automate updates to REST, Webhooks, and GitHub Apps documentation
-# **Who does it impact**: Anyone making OpenAPI changes in `github/github`, and wanting to get them published on the docs site.
+# Updates REST, Webhooks, and GitHub Apps docs from github/rest-api-description.
+# Opens a PR when generated OpenAPI data files change.
 
 on:
   workflow_dispatch:
@@ -21,7 +20,7 @@ permissions:
   contents: write
   pull-requests: write
 
-# This allows a subsequently queued workflow run to interrupt previous runs
+# Cancel older syncs so stale OpenAPI data does not open older PRs.
 concurrency:
   group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
   cancel-in-progress: true
@@ -34,12 +33,9 @@ jobs:
       - name: Checkout repository code
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-        # Check out a nested repository inside of previous checkout
       - name: Checkout rest-api-description repo
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
-          # By default, only the most recent commit of the `main` branch
-          # will be checked out
           repository: github/rest-api-description
           path: rest-api-description
           ref: ${{ inputs.SOURCE_BRANCH || github.event.client_payload.ref || 'main' }}
@@ -48,7 +44,6 @@ jobs:
 
       - name: Sync the REST, Webhooks, and GitHub Apps schemas
         env:
-          # Needed for gh
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
           NODE_OPTIONS: '--max-old-space-size=8192'
         run: |
@@ -72,10 +67,9 @@ jobs:
 
       - name: Create pull request
         env:
-          # Needed for gh
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
         run: |
-          # If nothing to commit, exit now. It's fine. No orphans.
+          # Exit before branch creation so a no-op sync does not leave an orphan branch.
           changes=$(git diff --name-only | wc -l)
           if [[ $changes -eq 0 ]]; then
             echo "There are no changes to commit after running 'npm run sync-rest'. Exiting..."
@@ -89,7 +83,6 @@ jobs:
 
           remotesha=$(git ls-remote --heads origin $branchname)
           if [ -n "$remotesha" ]; then
-            # output is not empty, it means the remote branch exists
             echo "Branch $branchname already exists in 'github/docs-internal'. Exiting..."
             exit 0
           fi