Merge branch 'main' into main

Author: Gareth Kirman

.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/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..."
@@ -174,4 +165,4 @@ jobs:
       - uses: ./.github/actions/create-workflow-failure-issue
         if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
         with:
-          token: ${{ steps.app-token.outputs.token }}
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

.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({
@@ -753,4 +744,4 @@ jobs:
       - uses: ./.github/actions/create-workflow-failure-issue
         if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
         with:
-          token: ${{ steps.app-token.outputs.token }}
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

.github/workflows/changelog-prompt.yml

@@ -18,18 +18,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 }}
-
       - name: Check if PR author is in docs-content team
         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: |
             try {
               const pr = context.payload.pull_request;
@@ -50,7 +43,7 @@ jobs:
 
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             // Get PR author username
             const pr = context.payload.pull_request;

.github/workflows/check-for-spammy-issues.yml

@@ -17,16 +17,9 @@ jobs:
     if: github.repository == 'github/docs'
     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 }}
-
       - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
 
             const issue = context.payload.issue

.github/workflows/close-bad-repo-sync-prs.yml

@@ -21,17 +21,10 @@ jobs:
     name: Close if invalid repo-sync PR author
     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 }}
-
       - name: Close pull request if unwanted
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             const { owner, repo } = context.repo
             const prCreator = context.actor

.github/workflows/codeql.yml

@@ -42,17 +42,7 @@ jobs:
         with:
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
 
-      - name: Generate GitHub App token
-        if: ${{ failure() && github.event_name != 'pull_request' }}
-        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/create-workflow-failure-issue
         if: ${{ failure() && github.event_name != 'pull_request' }}
         with:
-          token: ${{ steps.app-token.outputs.token }}
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}