Merge branch 'main' into am-stead/20429

Author: am-stead

.github/actions/create-workflow-failure-issue/action.yml

@@ -0,0 +1,93 @@
+name: Create workflow failure issue
+description: Create or update a GitHub issue in docs-engineering when a workflow fails, for automated diagnosis by an agentic workflow.
+
+inputs:
+  token:
+    description: A token with issues write permission on the target repo
+    required: true
+  repo:
+    description: The repository to create the issue in
+    default: github/docs-engineering
+    required: false
+
+runs:
+  using: composite
+  steps:
+    - name: Check for existing open issue
+      id: check-existing
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        ISSUE_REPO: ${{ inputs.repo }}
+        WORKFLOW_NAME: ${{ github.workflow }}
+      run: |
+        existing=$(gh issue list \
+          --repo "$ISSUE_REPO" \
+          --label "workflow-failure" \
+          --search "in:title [Workflow Failure] $WORKFLOW_NAME" \
+          --state open \
+          --json number \
+          --jq '.[0].number // empty' 2>/dev/null || true)
+        echo "existing_issue=$existing" >> "$GITHUB_OUTPUT"
+
+    - name: Comment on existing issue
+      if: steps.check-existing.outputs.existing_issue != ''
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        ISSUE_REPO: ${{ inputs.repo }}
+        ISSUE_NUMBER: ${{ steps.check-existing.outputs.existing_issue }}
+        WORKFLOW_NAME: ${{ github.workflow }}
+        SOURCE_REPO: ${{ github.repository }}
+        RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        EVENT_NAME: ${{ github.event_name }}
+        GIT_REF: ${{ github.ref }}
+      run: |
+        body=$(cat <<EOF
+        ### Repeat failure
+
+        **Workflow:** \`$WORKFLOW_NAME\`
+        **Repository:** \`$SOURCE_REPO\`
+        **Run:** $RUN_URL
+        **Event:** \`$EVENT_NAME\`
+        **Ref:** \`$GIT_REF\`
+        **Timestamp:** $(date -u +%Y-%m-%dT%H:%M:%SZ)
+        EOF
+        )
+        gh issue comment "$ISSUE_NUMBER" \
+          --repo "$ISSUE_REPO" \
+          --body "$body"
+
+    - name: Create workflow failure issue
+      if: steps.check-existing.outputs.existing_issue == ''
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        ISSUE_REPO: ${{ inputs.repo }}
+        WORKFLOW_NAME: ${{ github.workflow }}
+        SOURCE_REPO: ${{ github.repository }}
+        RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        EVENT_NAME: ${{ github.event_name }}
+        GIT_REF: ${{ github.ref }}
+        ACTOR: ${{ github.actor }}
+      run: |
+        body=$(cat <<EOF
+        ### Workflow failure
+
+        **Workflow:** \`$WORKFLOW_NAME\`
+        **Repository:** \`$SOURCE_REPO\`
+        **Run:** $RUN_URL
+        **Event:** \`$EVENT_NAME\`
+        **Ref:** \`$GIT_REF\`
+        **Triggered by:** \`$ACTOR\`
+        **Timestamp:** $(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+        ---
+        This issue was automatically created by the create-workflow-failure-issue action to enable automated diagnosis.
+        EOF
+        )
+        gh issue create \
+          --repo "$ISSUE_REPO" \
+          --label "workflow-failure" \
+          --title "[Workflow Failure] $WORKFLOW_NAME" \
+          --body "$body"

.github/instructions/all.instructions.md

@@ -29,4 +29,12 @@ When you create a pull request:
 3. Label with "llm-generated". 
 4. If an issue exists, include "fixes owner/repo#issue" or "towards owner/repo#issue" as appropriate. 
 5. Always create PRs in **draft mode** using `--draft` flag.
-6. When you are using gh cli, always _escape backticks_.
+
+## Accessing docs.github.com content programmatically
+
+When you need to read GitHub Docs, use these endpoints on `docs.github.com` in order of preference:
+
+1. `/llms.txt` — Start here. Returns a structured overview of the site with links to pagelist endpoints for each product version.
+2. `/api/pagelist/:lang/:version` — Returns a list of all pages for a given language and version (e.g., `/api/pagelist/en/free-pro-team@latest`). Use `/api/pagelist/versions` and `/api/pagelist/languages` for available options.
+3. `/api/search/v1?query=...&language=...&version=...&client_name=...` — Search docs content (e.g., `/api/search/v1?query=actions&language=en&version=free-pro-team@latest&client_name=copilot`).
+4. `/api/article/body?pathname=...` — Returns the rendered markdown body of a page. Handles all page types including REST, GraphQL, and webhook reference pages.

.github/instructions/code.instructions.md

@@ -9,14 +9,16 @@ For code reviews, follow guidelines, tests, and validate instructions. For creat
 ## Guidelines
 
 - If available, use ripgrep (`rg`) instead of `grep`.
-- When using gh cli, always _escape backticks_.
+- When using gh cli in double-quoted strings, escape backticks to prevent bash command substitution. In single-quoted strings, backticks do not need escaping.
 - All scripts should be listed in `package.json` and use `tsx`.
 - Whenever you create or comment on an issue or pull request, indicate you are GitHub Copilot.
 - Be careful fetching full HTML pages off the internet. Prefer to use MCP or gh cli whenever possible for github.com. Limit the number of tokens when grabbing HTML.
 - Avoid pull requests with over 300 lines of code changed. When significantly larger, offer to split up into smaller pull requests if possible.
 - All new code should be written in TypeScript and not JavaScript.
 - We use absolute imports, relative to the `src` directory, using the `@` symbol. For example, `getRedirect` which lives in `src/redirects/lib/get-redirect.ts` can be imported with `import getRedirect from '@/redirects/lib/get-redirect'`. The same rule applies for TypeScript (`.ts`) imports, e.g. `import type { GeneralSearchHit } from '@/search/types'`
 - For updates to the content linter, read important information in `src/content-linter/README.md`.
+- Do not commit to `main` branch.
+- Do not use git force push, and avoid git rebase.
 
 ## Tests
 

.github/instructions/content.instructions.md

@@ -72,6 +72,14 @@ Examples:
 * ❌ Incorrect: `For more information, see [Using GitHub Copilot](/copilot/using-github-copilot).`
 * ❌ Incorrect: `For more information, see {% link /copilot/using-github-copilot %}.`
 
+## RAI application and platform cards
+
+Articles with `contentType: rai` in their frontmatter are **application or platform cards**—legally mandated documents describing the responsible use of AI-powered features. The content linter enforces the required section structure (GHD064) and reusable isolation (GHD035).
+
+* **Template**: See `content/contributing/writing-for-github-docs/templates.md` for the full application/platform card template with all required sections and boilerplate reusables.
+* **Reusables**: RAI articles must only reference reusables from `data/reusables/rai/`. Place new RAI reusables there too.
+* **Frontmatter**: New application cards use `contentType: rai`. The older `type: rai` is for legacy transparency notes not yet migrated.
+
 ## Parenthetical dashes
 
 Where a sentence of normal body text contains a parenthetical dash, the dash should always be an em dash without spaces at either side. This rule does not apply to text within code blocks.

.github/workflows/codeql.yml

@@ -41,3 +41,8 @@ jobs:
         with:
           slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+      - uses: ./.github/actions/create-workflow-failure-issue
+        if: ${{ failure() && github.event_name != 'pull_request' }}
+        with:
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

.github/workflows/content-pipelines.yml

@@ -62,8 +62,10 @@ jobs:
           echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
 
       - name: Setup branch
+        id: setup-branch
         env:
           UPDATE_BRANCH: ${{ steps.branch.outputs.update_branch }}
+          PR_NUMBER: ${{ steps.check-pr.outputs.pr_number }}
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
@@ -76,14 +78,20 @@ jobs:
               git merge --abort 2>/dev/null || true
               git checkout main
               git branch -D "$UPDATE_BRANCH"
-              git push origin --delete "$UPDATE_BRANCH" || true
+              if [ -z "$PR_NUMBER" ]; then
+                git push origin --delete "$UPDATE_BRANCH" || true
+              else
+                echo "Skipping remote branch delete — PR #$PR_NUMBER is open"
+                echo "force_push=true" >> "$GITHUB_OUTPUT"
+              fi
               git checkout -b "$UPDATE_BRANCH"
             }
           else
             git checkout -b "$UPDATE_BRANCH"
           fi
 
       - name: Run content pipeline update script
+        id: update
         env:
           GH_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -111,44 +119,78 @@ jobs:
         if: steps.commit.outputs.has_changes == 'true'
         env:
           UPDATE_BRANCH: ${{ steps.branch.outputs.update_branch }}
-        run: git push origin "$UPDATE_BRANCH"
+          FORCE_PUSH: ${{ steps.setup-branch.outputs.force_push }}
+        run: |
+          if [ "$FORCE_PUSH" = "true" ]; then
+            echo "Force-pushing to align branch after merge conflict reset"
+            git push --force-with-lease origin "$UPDATE_BRANCH"
+          else
+            git push origin "$UPDATE_BRANCH"
+          fi
 
       - name: Create or update PR
         if: steps.commit.outputs.has_changes == 'true'
         env:
-          GH_TOKEN: ${{ github.token }}
+          GH_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
           UPDATE_BRANCH: ${{ steps.branch.outputs.update_branch }}
           PIPELINE_ID: ${{ matrix.id }}
+          COMPARE_URL: ${{ steps.update.outputs.compare_url }}
+          SHORT_RANGE: ${{ steps.update.outputs.short_range }}
         run: |
           PR_NUMBER="${{ steps.check-pr.outputs.pr_number }}"
           PR_TITLE="docs: update ${PIPELINE_ID} content from source docs"
-
-          PR_BODY="_GitHub Copilot generated this pull request._"$'\n\n'
-          PR_BODY+="> [!NOTE]"$'\n'
-          PR_BODY+="> This PR is **automatically generated** by the [content pipeline update workflow](${{ github.server_url }}/${{ github.repository }}/actions/workflows/content-pipelines.yml). Each run adds a new commit with any documentation changes detected."$'\n\n'
-          PR_BODY+="## What this does"$'\n\n'
-          PR_BODY+="Runs the \`content-pipeline-update\` agent (${PIPELINE_ID}) against the latest source docs and updates official articles under \`content/\` that have fallen out of sync."$'\n\n'
-          PR_BODY+="## Review"$'\n\n'
-          PR_BODY+="* Review each commit for accuracy — the agent uses AI, so spot-check important changes"$'\n'
-          PR_BODY+="* To adjust agent behavior, see [Modifying results](${{ github.server_url }}/${{ github.repository }}/blob/main/src/content-pipelines/README.md#modifying-results)"$'\n'
-          PR_BODY+="* Once satisfied, merge to keep docs up to date"$'\n'
-          PR_BODY+="* A new PR will be created on the next run if there are further changes"
+          NEW_ITEM="* [\`${SHORT_RANGE}\`](${COMPARE_URL})"
 
           if [ -n "$PR_NUMBER" ]; then
-            echo "PR #$PR_NUMBER already exists — new commit pushed"
+            echo "PR #$PR_NUMBER already exists — appending source changes to body"
+
+            EXISTING_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body')
+
+            # Append a new bullet before the SOURCE_CHANGES end marker
+            # Uses bash parameter expansion for safe literal string replacement
+            MARKER="<!-- /SOURCE_CHANGES -->"
+            INSERTION="${NEW_ITEM}"$'\n'
+            INSERTION+="${MARKER}"
+            UPDATED_BODY="${EXISTING_BODY/$MARKER/$INSERTION}"
+
+            gh pr edit "$PR_NUMBER" --body "$UPDATED_BODY"
+
+            echo "Ensuring PR #$PR_NUMBER is marked ready for review"
+            gh pr ready "$PR_NUMBER" || echo "Unable to mark PR #$PR_NUMBER as ready (it may already be ready)"
           else
             echo "Creating new PR"
+
+            PR_BODY="_GitHub Copilot generated this pull request._"$'\n\n'
+            PR_BODY+="> [!NOTE]"$'\n'
+            PR_BODY+="> This PR is **automatically generated** by the [content pipeline update workflow](${{ github.server_url }}/${{ github.repository }}/actions/workflows/content-pipelines.yml). Each run adds a new commit with any documentation changes detected."$'\n\n'
+            PR_BODY+="## What this does"$'\n\n'
+            PR_BODY+="Runs the \`content-pipeline-update\` agent (${PIPELINE_ID}) against the latest source docs and updates official articles under \`content/\` that have fallen out of sync."$'\n\n'
+            PR_BODY+="## Source changes"$'\n\n'
+            PR_BODY+="Changes in the source repo that triggered this update:"$'\n\n'
+            PR_BODY+="<!-- SOURCE_CHANGES -->"$'\n'
+            PR_BODY+="${NEW_ITEM}"$'\n'
+            PR_BODY+="<!-- /SOURCE_CHANGES -->"$'\n\n'
+            PR_BODY+="## Review"$'\n\n'
+            PR_BODY+="* Review each commit for accuracy — the agent uses AI, so spot-check important changes"$'\n'
+            PR_BODY+="* To adjust agent behavior, see [Modifying results](${{ github.server_url }}/${{ github.repository }}/blob/main/src/content-pipelines/README.md#modifying-results)"$'\n'
+            PR_BODY+="* Once satisfied, merge to keep docs up to date"$'\n'
+            PR_BODY+="* A new PR will be created on the next run if there are further changes"
+
             gh pr create \
               --title "$PR_TITLE" \
               --body "$PR_BODY" \
               --base main \
               --head "$UPDATE_BRANCH" \
-              --label "workflow-generated,content-pipeline-update" \
-              --draft
+              --label "workflow-generated,content-pipeline-update,ready-for-doc-review"
           fi
 
       - uses: ./.github/actions/slack-alert
         if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
         with:
           slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+      - uses: ./.github/actions/create-workflow-failure-issue
+        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
+        with:
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

.github/workflows/create-changelog-pr.yml

@@ -164,3 +164,8 @@ jobs:
         with:
           slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+      - uses: ./.github/actions/create-workflow-failure-issue
+        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
+        with:
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

.github/workflows/delete-orphan-translation-files.yml

@@ -14,7 +14,7 @@ name: Delete orphan translation files
 on:
   workflow_dispatch:
   schedule:
-    - cron: '20 16 * * 3' # Run every Wednesday at 16:20 UTC / 8:20 PST — orphan & hygiene cleanup theme
+    - cron: '20 16 * * 1' # Run every Monday at 16:20 UTC / 8:20 PST
 
 permissions:
   contents: write
@@ -140,3 +140,8 @@ jobs:
         with:
           slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+      - uses: ./.github/actions/create-workflow-failure-issue
+        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
+        with:
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

.github/workflows/docs-review-collect.yml

@@ -47,3 +47,8 @@ jobs:
         with:
           slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+      - uses: ./.github/actions/create-workflow-failure-issue
+        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
+        with:
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

.github/workflows/enterprise-dates.yml

@@ -11,7 +11,7 @@ name: Enterprise date updater
 on:
   workflow_dispatch:
   schedule:
-    - cron: '20 16 * * 4' # Run every Thursday at 16:20 UTC / 8:20 PST — infrastructure & releases theme
+    - cron: '20 16 * * 1' # Run every Monday at 16:20 UTC / 8:20 PST
 
 permissions:
   contents: write
@@ -74,3 +74,8 @@ jobs:
         with:
           slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+      - uses: ./.github/actions/create-workflow-failure-issue
+        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
+        with:
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}