Merge branch 'main' into patch-404-wrong-method

Author: Sharra-writes

.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

@@ -115,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 }}

.github/workflows/changelog-agent.yml

@@ -45,20 +45,11 @@ jobs:
       )
     runs-on: ubuntu-latest
     steps:
-      - 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-internal,docs-content,docs-engineering
-
       - name: Resolve PR data
         id: resolve_pr
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             let pr;
             if (context.eventName === 'workflow_dispatch') {
@@ -86,7 +77,7 @@ jobs:
         id: check_team
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             const author = '${{ steps.resolve_pr.outputs.pr_author }}';
 
@@ -124,7 +115,7 @@ jobs:
         env:
           PR_BODY: ${{ steps.resolve_pr.outputs.pr_body }}
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             const body = process.env.PR_BODY || '';
 
@@ -159,7 +150,7 @@ jobs:
         id: check_parent
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             const issueNumber = parseInt('${{ steps.extract_issue.outputs.issue_number }}', 10);
 
@@ -240,7 +231,7 @@ jobs:
           PR_BODY: ${{ steps.resolve_pr.outputs.pr_body }}
           PR_URL: ${{ steps.resolve_pr.outputs.pr_url }}
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             const prNumber = parseInt('${{ steps.resolve_pr.outputs.pr_number }}', 10);
             const prAuthor = '${{ steps.resolve_pr.outputs.pr_author }}';
@@ -281,7 +272,7 @@ jobs:
         id: check_existing
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             const branchName = `changelog-agent-${{ steps.resolve_pr.outputs.pr_number }}`;
             const { data: pulls } = await github.rest.pulls.list({
@@ -304,7 +295,7 @@ jobs:
         id: read_examples
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             // Fetch changelog-internal.md from docs-content
             const { data } = await github.rest.repos.getContent({
@@ -415,13 +406,13 @@ jobs:
 
       - name: Set up Node.js for Copilot CLI
         if: steps.check_parent.outputs.has_parent == 'true' && steps.check_existing.outputs.exists == 'false'
-        uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
 
       - name: Install GitHub Copilot CLI
         if: steps.check_parent.outputs.has_parent == 'true' && steps.check_existing.outputs.exists == 'false'
-        run: npm install -g @github/copilot
+        run: npm install -g @github/copilot@1.0.71
 
       - name: Generate changelog draft via Copilot
         if: steps.check_parent.outputs.has_parent == 'true' && steps.check_existing.outputs.exists == 'false'
@@ -474,7 +465,7 @@ jobs:
           PARENT_AUTHOR: ${{ steps.check_parent.outputs.parent_author }}
           PARENT_ASSIGNEES: ${{ steps.check_parent.outputs.parent_assignees }}
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             const branchName = `changelog-agent-${{ steps.resolve_pr.outputs.pr_number }}`;
             const filePath = 'docs-content-docs/docs-content-workflows/changelog-internal.md';
@@ -635,7 +626,7 @@ jobs:
           PARENT_AUTHOR: ${{ steps.check_parent.outputs.parent_author }}
           PARENT_ASSIGNEES: ${{ steps.check_parent.outputs.parent_assignees }}
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             const author = process.env.PR_AUTHOR;
             const changelogPrUrl = process.env.CHANGELOG_PR_URL;
@@ -730,7 +721,7 @@ jobs:
         if: steps.create_pr.outputs.changelog_pr_url != '' && inputs.dry_run != true
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             const changelogPrUrl = '${{ steps.create_pr.outputs.changelog_pr_url }}';
             await github.rest.issues.createComment({
@@ -745,12 +736,14 @@ jobs:
         if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      - 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 }}