Merge branch 'main' into fix/manage-access-links

Author: Sharra-writes

.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/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({
@@ -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 }}