Merge branch 'github:main' into main

Author: Trustinbtc999-hue

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

@@ -10,6 +10,11 @@ inputs:
     default: github/docs-engineering
     required: false
 
+outputs:
+  issue_url:
+    description: URL of the created or updated workflow-failure issue (empty if creation failed).
+    value: ${{ steps.create-new.outputs.issue_url || steps.comment-existing.outputs.issue_url }}
+
 runs:
   using: composite
   steps:
@@ -31,6 +36,7 @@ runs:
         echo "existing_issue=$existing" >> "$GITHUB_OUTPUT"
 
     - name: Comment on existing issue
+      id: comment-existing
       if: steps.check-existing.outputs.existing_issue != ''
       shell: bash
       env:
@@ -57,8 +63,10 @@ runs:
         gh issue comment "$ISSUE_NUMBER" \
           --repo "$ISSUE_REPO" \
           --body "$body"
+        echo "issue_url=$GITHUB_SERVER_URL/$ISSUE_REPO/issues/$ISSUE_NUMBER" >> "$GITHUB_OUTPUT"
 
     - name: Create workflow failure issue
+      id: create-new
       if: steps.check-existing.outputs.existing_issue == ''
       shell: bash
       env:
@@ -86,9 +94,10 @@ runs:
         This issue was automatically created by the create-workflow-failure-issue action to enable automated diagnosis.
         EOF
         )
-        gh issue create \
+        url=$(gh issue create \
           --repo "$ISSUE_REPO" \
           --label "workflow-failure" \
           --label "workflow-generated" \
           --title "[Workflow Failure] $WORKFLOW_NAME" \
-          --body "$body"
+          --body "$body")
+        echo "issue_url=$url" >> "$GITHUB_OUTPUT"

.github/actions/slack-alert/action.yml

@@ -10,13 +10,61 @@ inputs:
     default: CG5MJHMB2 # docs-alerts
     required: false
   message:
-    description: The message to send to Slack
-    default: The last '${{ github.workflow }}' run failed. See ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+    description: >-
+      Optional message override. When set, it is sent verbatim. When empty (the
+      default), a standard multi-line failure message is built from the run
+      context, plus a link to the failure issue if issue_url is provided.
+    default: ''
+    required: false
+  issue_url:
+    description: >-
+      Optional link to the tracking failure issue (e.g. the output of the
+      create-workflow-failure-issue action). Appended to the default message.
+      Ignored when a custom message is provided.
+    default: ''
     required: false
 
 runs:
   using: composite
   steps:
+    # Build the Slack text here so the default message can be multi-line (real
+    # newlines) and conditionally include the issue link. A caller-supplied
+    # message is passed through verbatim for backward compatibility.
+    - name: Build Slack message
+      id: build
+      shell: bash
+      env:
+        MESSAGE: ${{ inputs.message }}
+        ISSUE_URL: ${{ inputs.issue_url }}
+        SOURCE_REPO: ${{ github.repository }}
+        WORKFLOW_NAME: ${{ github.workflow }}
+        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: |
+        # Escape Slack mrkdwn control chars in interpolated context fields so a
+        # crafted branch/ref (e.g. containing <!channel>) can't inject mentions.
+        esc() { printf '%s' "$1" | sed -e 's/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/g'; }
+        # Unique heredoc delimiter so a custom message can't collide with it.
+        delim="SLACK_EOF_${RANDOM}${RANDOM}"
+        {
+          printf 'text<<%s\n' "$delim"
+          if [ -n "$MESSAGE" ]; then
+            printf '%s\n' "$MESSAGE"
+          else
+            printf ':actions: *Workflow failure* in %s: %s\n' "$(esc "$SOURCE_REPO")" "$(esc "$WORKFLOW_NAME")"
+            printf 'on %s · %s · by %s\n' "$(esc "$EVENT_NAME")" "$(esc "$GIT_REF")" "$(esc "$ACTOR")"
+            printf 'Run: %s\n' "$RUN_URL"
+            if [ -n "$ISSUE_URL" ]; then
+              printf 'Issue: %s\n' "$ISSUE_URL"
+            else
+              printf ':warning: No issue created\n'
+            fi
+          fi
+          printf '%s\n' "$delim"
+        } >> "$GITHUB_OUTPUT"
+
     - name: Send Slack notification if workflow fails
       uses: slackapi/slack-github-action@45a88b9581bfab2566dc881e2cd66d334e621e2c # v3.0.3
       with:
@@ -25,4 +73,4 @@ runs:
         errors: true
         payload: |
           channel: ${{ toJSON(inputs.slack_channel_id) }}
-          text: ${{ toJSON(inputs.message) }}
+          text: ${{ toJSON(steps.build.outputs.text) }}

.github/instructions/content-guidelines.instructions.md

@@ -19,6 +19,20 @@ The strategic priority is simplification: create less content and remove content
 * Would a typical internet user figure this out on their own by exploring the UI?
 * Is the information presented at the moment the reader actually needs it?
 
+## Give opinionated, actionable guidance
+
+This applies whenever you give the reader advice or present ways to accomplish a task.
+
+* Be opinionated when there is a better way: when several approaches exist, recommend the best one and explain why, rather than presenting all options as equally valid. When they are genuinely equivalent, stay neutral.
+* Tell users the best practice AND how to follow it: whenever you state a best practice, pair it with concrete steps or an example so the reader can act on it, never the advice alone.
+
+## Focus on the reader's purpose, not the product
+
+Frame an article around what the reader is trying to accomplish, not the product or feature they use to do it. This applies when naming an article or deciding what a new or substantially reworked article should cover; do not use it to justify restructuring an article during a small edit.
+
+* Title articles by the reader's goal, not the product or feature. For example, "Secure your enterprise", not "Use GitHub Advanced Security".
+* Scope articles around a task, not a product. When a task naturally spans multiple features or products, look for the opportunity to cover them together in one task-focused article or tutorial rather than splitting into per-product articles. Keep each article to a single purpose (the task): combine features only when they serve that same task, not to bundle unrelated capabilities.
+
 ## Intros: pull people in
 
 This section applies mainly to the `intro` frontmatter field and, for conceptual articles, section openings.

.github/instructions/content.instructions.md

@@ -16,6 +16,14 @@ Before committing content changes, always:
 3. **Verify [AUTOTITLE] links** point to existing articles
 4. **Run tests** on changed content: `npm run test -- src/content-render/tests/render-changed-and-deleted-files.ts`
 
+## Accuracy and flagging uncertainty
+
+AI assistants can produce plausible but incorrect information. To protect readers and writers:
+
+* Never fabricate product behavior, settings, permissions, API parameters, or limits. If you cannot verify a detail from the source material or the product itself, say so instead of guessing.
+* Flag uncertainty at the level of the specific claim, not the whole article. Identify the individual sentence, step, value, or setting you are unsure about, rather than labeling an entire article as "needs review."
+* After writing or editing, give the writer a checklist of each specific claim to verify, noting where it appears (the exact step or sentence) and why it needs checking. Prioritize claims where being wrong could have serious consequences, such as security, authentication, permissions, billing, or any irreversible action, and recommend confirming those with the relevant product or engineering team.
+
 ## Bullet lists
 
 The bulleted points in a bullet list should always be denoted in Markdown using an asterisk, not a hyphen.
@@ -107,6 +115,17 @@ For such content, DO NOT use in-article Liquid versioning such as `{% ifversion
 
 All articles that are ONLY for GitHub Enterprise Server (GHES) should be versioned in the frontmatter using feature-based versioning defined in `data/features/`. 
 
+### Versioning for GHES content: always use feature-based versioning
+
+If content is intended to ship to GitHub Enterprise Server, use **feature-based versioning (FBV)**.
+
+* Do **not** suggest removing GHES frontmatter versioning or hardcode version strings (for example, `free-pro-team@latest`) just to make links or tests pass.
+* If CI fails because a GHES link cannot be built, treat that as a versioning mismatch—not a signal to de-scope GHES.
+* Add or reuse the appropriate feature flag in `data/features/`. Use it in `versions.feature` frontmatter when an article's availability follows the feature, and use Liquid conditionals only for version-specific blocks within a broader article.
+* Keep frontmatter and in-article versioning aligned so links render for every supported version.
+
+For guidance, see [About feature-based versioning](https://docs.github.com/en/contributing/writing-for-github-docs/versioning-documentation#about-feature-based-versioning).
+
 ### FPT, GHEC, GHES articles
 
 All articles that are versioned for all of FPT, GHEC, and GHES in the frontmatter MAY require certain blocks of content to be versioned using in-article Liquid versioning. Before recommending this, check if this is really the case.

.github/instructions/instruction-architecture.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: ".github/instructions/**,.github/agents/**"
+---
+
+# Editing Copilot content instruction and agent files
+
+This applies when you add, edit, or remove a Copilot instruction or shared agent file that guides how **content** (articles, data files) is written. It does **not** apply to code instructions or agents owned by the engineering team (for example `code.instructions.md`).
+
+When it applies, you **must** first read the instruction-architecture doc in full and follow it:
+
+https://github.com/github/docs-team/blob/main/contributing-to-docs/docs-work/copilot-instruction-architecture.md
+
+Read the current version every time (from a local `github/docs-team` checkout if you have one, otherwise fetch the URL); do not rely on your memory of it, because it changes. If you cannot access it, say so and stop rather than guessing.

.github/instructions/style-guide-summary.instructions.md

@@ -59,7 +59,7 @@ For Liquid variable usage, reusables, linking conventions, bullet-list markers,
 
 ## Lists
 
-* Capitalize the first letter of each list item.
+* Capitalize the first letter of each list item, including the first letter after the colon in a term definition list (for example, `* **Filesystem**: Grant read-only access...`).
 * Use periods only if the item is a complete sentence.
 * Introduce lists with a descriptive sentence, not vague phrases like "the following" in isolation.
 

.github/workflows/auto-add-ready-for-doc-review.yml

@@ -27,18 +27,11 @@ jobs:
       - name: Check out repo
         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 }}
-
       - name: Check team membership
         id: membership_check
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             try {
               await github.rest.teams.getMembershipForUserInOrg({
@@ -55,7 +48,7 @@ jobs:
       - name: Add ready-for-doc-review label
         if: steps.membership_check.outputs.result == 'false'
         env:
-          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+          GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
           PR_URL: ${{ github.event.pull_request.html_url }}
         run: |
           gh pr edit $PR_URL --add-label ready-for-doc-review

.github/workflows/benchmark-pages.yml

@@ -24,15 +24,6 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: 'false'
-      - 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: Build
@@ -58,7 +49,7 @@ jobs:
       - name: Check results and create issue if needed
         if: always()
         env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
           RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
         run: |
           echo "Reading benchmark results..."
@@ -166,12 +157,14 @@ jobs:
             echo "Done creating issue"
           fi
 
-      - uses: ./.github/actions/slack-alert
+      - uses: ./.github/actions/create-workflow-failure-issue
+        id: create-failure-issue
         if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
         with:
-          slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}
 
-      - uses: ./.github/actions/create-workflow-failure-issue
+      - uses: ./.github/actions/slack-alert
         if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
         with:
-          token: ${{ steps.app-token.outputs.token }}
+          slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+          issue_url: ${{ steps.create-failure-issue.outputs.issue_url }}