Merge pull request #45314 from github/repo-sync

Repo sync

Author: docs-bot

content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md

@@ -26,6 +26,7 @@ You can add MCP servers in the following ways:
 * [Using the `/mcp add` command](#using-the-mcp-add-command)
 * [Using the `copilot mcp add` subcommand](#using-the-copilot-mcp-add-subcommand)
 * [Editing the configuration file](#editing-the-configuration-file)
+* [Adding per-repository MCP servers](#adding-per-repository-mcp-servers)
 * [Searching and installing from the registry (experimental)](#searching-and-installing-from-the-registry)
 
 For installation instructions, available tools, and URLs for specific MCP servers, see the [{% data variables.product.github %} MCP Registry](https://github.com/mcp).
@@ -138,6 +139,52 @@ The following example shows a configuration file with a local server and a remot
 
 For more information on MCP server configuration, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers#writing-a-json-configuration-for-mcp-servers).
 
+### Adding per-repository MCP servers
+
+You can configure MCP servers for a specific project by adding a JSON file to the repository. This is useful when you want servers to be available only when working in that project, or when you want to share an MCP setup with collaborators by committing it to the repository.
+
+{% data variables.copilot.copilot_cli_short %} looks for project-level configuration in the following locations:
+
+| Path | Recommended use |
+|------|-----------------|
+| `.mcp.json` (in any directory from your working directory up to the repository root) | Local or per-checkout configuration; commonly placed at the project root |
+| `.github/mcp.json` | Shared configuration that is committed to the repository |
+
+When you start {% data variables.copilot.copilot_cli_short %} inside a Git repository, the CLI walks from your current working directory up to the repository root, loading MCP configuration files along the way. If both `.mcp.json` and `.github/mcp.json` exist in the same directory, `.mcp.json` takes precedence. When server names conflict, definitions in files closer to your working directory take precedence. Project-level definitions also take precedence over those in `~/.copilot/mcp-config.json`. For more information on relative trust, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#mcp-server-trust-levels).
+
+Project-level files can use either the `mcpServers` top-level object shown in `~/.copilot/mcp-config.json`, or the bare top-level format where each key is an MCP server name. For example, this configuration uses the `mcpServers` object:
+
+```json copy
+{
+  "mcpServers": {
+    "playwright": {
+      "type": "local",
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+The same server can also be configured with the bare top-level format:
+
+```json copy
+{
+  "playwright": {
+    "type": "local",
+    "command": "npx",
+    "args": ["@playwright/mcp@latest"]
+  }
+}
+```
+
+> [!NOTE]
+> Project-level MCP servers are loaded only after you confirm folder trust on first launch. They are silently skipped in untrusted directories. For more information on folder trust, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-copilot-cli#trusted-directories).
+
+In prompt mode (`copilot -p`), project-level MCP servers are loaded automatically if the current directory is already trusted. If the directory is not trusted, project-level MCP servers are skipped by default. To load them anyway, set the `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP` environment variable to `true`, since prompt mode cannot show an interactive trust prompt. For more information, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#environment-variables).
+
+The `.vscode/mcp.json` file for {% data variables.product.prodname_vscode_shortname %} is not read by {% data variables.copilot.copilot_cli_short %}. It uses the unsupported top-level key `servers`. To migrate an existing `.vscode/mcp.json` to a format the CLI accepts, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#migrating-from-vscodemcpjson).
+
 ### Searching and installing from the registry
 
 > [!NOTE]

content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md

@@ -480,8 +480,11 @@ These settings apply across all your sessions and repositories. You can use the
 | `renderMarkdown` | `boolean` | `true` | Render Markdown in terminal output. |
 | `remoteExport` | `boolean` | `true` | Export sessions remotely when session sync is available. Set to `false` to opt out of remote export by default. The `remoteSessions` setting when set to `true`, or the `--remote` flag, still enables export and steering regardless of this setting. |
 | `respectGitignore` | `boolean` | `true` | Exclude gitignored files from the `@` file mention picker. When `false`, the picker includes files normally excluded by `.gitignore`. |
-| `sandbox.gitAuth` | `boolean` | `false` | Inject Git credentials into the sandbox so commands running inside it can authenticate with Git. |
-| `sandbox.ghAuth` | `boolean` | `false` | Inject {% data variables.product.prodname_cli %} (`gh`) credentials into the sandbox so commands running inside it can authenticate with the {% data variables.product.prodname_cli %}. |
+| `sandbox.allowBypass` | `boolean` | `true` | Allow sandboxed commands to request a bypass for specific operations (surfaces a permission prompt) so tools like `grep` and `glob` keep working when the sandbox would otherwise block them. Set to `false` to opt out. |
+| `sandbox.enabled` | `boolean` | `false` | Restrict shell commands, MCP/LSP servers, and built-in file/web tools to a sandboxed environment with limited file system and network access. Enable it from the `/sandbox` dialog or with `/sandbox enable`. |
+| `sandbox.gitAuth` | `boolean` | `true` | Inject Git credentials into the sandbox so commands running inside it can authenticate with Git. Set to `false` to opt out. |
+| `sandbox.ghAuth` | `boolean` | `true` | Inject {% data variables.product.prodname_cli %} (`gh`) credentials into the sandbox so commands running inside it can authenticate with the {% data variables.product.prodname_cli %}. Set to `false` to opt out. |
+| `sandbox.userPolicy.network.allowLocalNetwork` | `boolean` | `true` | Allow sandboxed commands to reach local network addresses (for example, local dev servers). Set to `false` to opt out. |
 | `sandbox.userPolicy.seatbelt.keychainAccess` | `boolean` | `false` | macOS only. Grant sandboxed commands access to the system keychain. Can also be toggled from the `/sandbox` dialog. |
 | `screenReader` | `boolean` | `false` | Enable screen reader optimizations. |
 | `scrollbar` | `boolean` | `true` | Show the scrollbar in scrollable views. Set to `false` to hide it and use the full terminal width. |

src/content-pipelines/state/copilot-cli.sha

@@ -1 +1 @@
-00598e76021b5e4f4ba2903053c69c6010fa7190
+7a9cc333248da994abe48d847f18a313db0d56f6

src/frame/middleware/cache-control.ts

@@ -3,43 +3,43 @@ import type { Response } from 'express'
 import { createLogger } from '@/observability/logger'
 const logger = createLogger(import.meta.url)
 
+type CacheControlKey = 'cache-control' | 'surrogate-control'
+
 interface CacheControlOptions {
-  key?: string
-  public_?: boolean
+  key?: CacheControlKey
   immutable?: boolean
-  maxAgeZero?: boolean
+  staleWhileRevalidate?: number
+  staleIfError?: number
 }
 
-// Return a function you can pass a Response object to and it will
-// set the `Cache-Control` header.
-//
-// For example:
-//
-//    const cacheControlYear = getCacheControl(60 * 60 * 24 * 365)
-//    ...
-//    cacheControlYear(res)
-//    res.send(body)
-//
-// Max age is in seconds
-// Max age should not be greater than 31536000 https://www.ietf.org/rfc/rfc2616.txt
+const ONE_MINUTE = 60
+const TEN_MINUTES = 10 * ONE_MINUTE
+const ONE_HOUR = 60 * ONE_MINUTE
+const ONE_DAY = 24 * ONE_HOUR
+const ONE_WEEK = 7 * ONE_DAY
+const ONE_YEAR = 365 * ONE_DAY
+
+// Return a function you can pass a Response object to and it will set the `Cache-Control` header.
+// Max age is in seconds.
+// Max age should not be greater than 31536000, per <https://www.ietf.org/rfc/rfc2616.txt>.
 function cacheControlFactory(
-  maxAge: number = 60 * 60,
+  maxAge: number = 0,
   {
     key = 'cache-control',
-    public_ = true,
     immutable = false,
-    maxAgeZero = false,
+    staleWhileRevalidate = 0,
+    staleIfError = 0,
   }: CacheControlOptions = {},
 ): (res: Response) => void {
   const directives = [
-    maxAge && public_ && 'public',
-    maxAge && `max-age=${maxAge}`,
-    maxAge && immutable && 'immutable',
-    !maxAge && 'private',
-    !maxAge && 'no-store',
-    maxAge >= 60 * 60 && `stale-while-revalidate=${60 * 60}`,
-    maxAge >= 60 * 60 && `stale-if-error=${24 * 60 * 60}`,
-    (maxAgeZero || maxAge === 0) && 'max-age=0',
+    maxAge > 0 && 'public',
+    maxAge > 0 && `max-age=${maxAge}`,
+    maxAge <= 0 && 'max-age=0',
+    maxAge > 0 && immutable && 'immutable',
+    maxAge <= 0 && 'private',
+    maxAge <= 0 && 'no-store',
+    maxAge > 0 && staleWhileRevalidate > 0 && `stale-while-revalidate=${staleWhileRevalidate}`,
+    maxAge > 0 && staleIfError > 0 && `stale-if-error=${staleIfError}`,
   ]
     .filter(Boolean)
     .join(', ')
@@ -53,64 +53,73 @@ function cacheControlFactory(
   }
 }
 
-// These are roughly in order from shortest to longest
+// ### These are roughly in order from shortest to longest. ###
 
-// If you do not want caching
+// If you do not want caching.
 export const noCacheControl = cacheControlFactory(0)
 
-// Short cache for 4xx errors
-export const errorCacheControl = cacheControlFactory(60) // 1 minute
-
-// This means we tell the browser to cache the XHR request for 1h
-const searchBrowserCacheControl = cacheControlFactory(60 * 60)
-// This tells the CDN to cache the response for 24 hours
-const searchCdnCacheControl = cacheControlFactory(60 * 60 * 24, {
-  key: 'surrogate-control',
-})
-export function searchCacheControl(res: Response): void {
-  searchBrowserCacheControl(res)
-  searchCdnCacheControl(res)
-}
+// Short cache for 4xx errors.
+export const errorCacheControl = cacheControlFactory(ONE_MINUTE)
 
-// 24 hours for CDN, we soft-purge this with each deploy
-const defaultCDNCacheControl = cacheControlFactory(60 * 60 * 24, {
+// For default cache control, up to one week in cache but much shorter in browser.
+// Most responses are under the default cache control policy.
+const browserCacheControl = cacheControlFactory(ONE_MINUTE)
+const defaultCDNCacheControl = cacheControlFactory(TEN_MINUTES, {
   key: 'surrogate-control',
+  staleWhileRevalidate: ONE_WEEK,
+  staleIfError: ONE_WEEK,
 })
-// Shorter because between deployments and their (sort) purges,
-// we don't want the browser to overly cache because with them we
-// can't control purging.
-const defaultBrowserCacheControl = cacheControlFactory(60)
-// A general default configuration that is useful to almost all responses
-// that can be cached.
 export function defaultCacheControl(res: Response): void {
+  browserCacheControl(res)
   defaultCDNCacheControl(res)
-  defaultBrowserCacheControl(res)
 }
+export const searchCacheControl = defaultCacheControl
 
-// Vary on content type for pages that support content negotiation (HTML vs markdown)
+// For requests where the response can vary between a HTML and Markdown response
+// using the accept header.
 export function contentTypeCacheControl(res: Response): void {
   defaultCacheControl(res)
   res.append('vary', 'accept')
 }
 
-// Vary on language when needed
-// x-user-language is a custom request header derived from req.cookie:user_language
-// accept-language is truncated to one of our available languages
+// Vary on language when needed.
+// `x-user-language` is a custom request header derived from `req.cookie:user_language`.
+// `accept-language` is truncated to one of our available languages.
 // https://bit.ly/3u5UeRN
 export function languageCacheControl(res: Response): void {
   defaultCacheControl(res)
   res.append('vary', 'accept-language, x-user-language')
 }
 
-// Vary on both language and version for homepage redirects
-// x-user-version is a custom request header derived from req.cookie:user_version
+// Vary on both language and version for homepage redirects.
+// `x-user-version` is a custom request header derived from `req.cookie:user_version`.
 export function languageAndVersionCacheControl(res: Response): void {
   defaultCacheControl(res)
   res.append('vary', 'accept-language, x-user-language, x-user-version')
 }
 
-// Long cache control for versioned assets: images, CSS, JS...
-export const assetCacheControl = cacheControlFactory(60 * 60 * 24 * 7, { immutable: true })
+// Long cache control for versioned assets: such as images, CSS, prebuilt JS.
+const assetBrowserCacheControl = cacheControlFactory(TEN_MINUTES)
+const assetCDNCacheControl = cacheControlFactory(ONE_WEEK, {
+  key: 'surrogate-control',
+  immutable: true,
+  staleWhileRevalidate: ONE_WEEK,
+  staleIfError: ONE_WEEK,
+})
+export function assetCacheControl(res: Response): void {
+  assetBrowserCacheControl(res)
+  assetCDNCacheControl(res)
+}
 
-// Long caching for archived pages and assets
-export const archivedCacheControl = cacheControlFactory(60 * 60 * 24 * 365)
+// Long caching for archived pages and assets.
+const archivedBrowserCacheControl = cacheControlFactory(TEN_MINUTES)
+const archivedCDNCacheControl = cacheControlFactory(ONE_YEAR, {
+  key: 'surrogate-control',
+  immutable: true,
+  staleWhileRevalidate: ONE_WEEK,
+  staleIfError: ONE_WEEK,
+})
+export function archivedCacheControl(res: Response): void {
+  archivedBrowserCacheControl(res)
+  archivedCDNCacheControl(res)
+}

src/frame/tests/favicons.ts

@@ -3,6 +3,24 @@ import { describe, expect, test, vi } from 'vitest'
 import { SURROGATE_ENUMS } from '@/frame/middleware/set-fastly-surrogate-key'
 import { get } from '@/tests/helpers/e2etest'
 
+function getMaxAge(header: string | undefined): number {
+  return Number(String(header).match(/(?:^|[ ,])max-age=(\d+)/)?.[1])
+}
+
+// The CDN holds favicons for a long time because we can purge it on demand with
+// the manual surrogate key. The browser gets a shorter window because we can't.
+function expectAggressiveCaching(headers: Record<string, string>) {
+  const cdnMaxAge = getMaxAge(headers['surrogate-control'])
+  expect(headers['surrogate-control']).toContain('public')
+  expect(headers['surrogate-control']).toContain('immutable')
+  expect(cdnMaxAge).toBeGreaterThanOrEqual(60 * 60)
+
+  const browserMaxAge = getMaxAge(headers['cache-control'])
+  expect(headers['cache-control']).toContain('public')
+  expect(browserMaxAge).toBeGreaterThan(0)
+  expect(browserMaxAge).toBeLessThan(cdnMaxAge)
+}
+
 describe('favicon assets', () => {
   vi.setConfig({ testTimeout: 60 * 1000 })
 
@@ -12,16 +30,7 @@ describe('favicon assets', () => {
     expect(parseInt(res.headers['content-length'], 10)).toBeGreaterThan(0)
     expect(res.headers['content-type']).toBe('image/x-icon')
     expect(res.headers['set-cookie']).toBeUndefined()
-    expect(res.headers['cache-control']).toContain('public')
-    expect(res.headers['cache-control']).toContain('immutable')
-    expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
-    const maxAgeSeconds = parseInt(
-      (res.headers['cache-control'] || '').match(/max-age=(\d+)/)?.[1] || '',
-      10,
-    )
-    // Let's not be too specific in the tests, just as long as it's testing
-    // that it's a reasonably large number of seconds.
-    expect(maxAgeSeconds).toBeGreaterThanOrEqual(60 * 60)
+    expectAggressiveCaching(res.headers)
     expect(res.headers['surrogate-key']).toBe(SURROGATE_ENUMS.MANUAL)
   })
 
@@ -31,16 +40,7 @@ describe('favicon assets', () => {
     expect(parseInt(res.headers['content-length'] || '', 10)).toBeGreaterThan(0)
     expect(res.headers['content-type']).toBe('image/png')
     expect(res.headers['set-cookie']).toBeUndefined()
-    expect(res.headers['cache-control']).toContain('public')
-    expect(res.headers['cache-control']).toContain('immutable')
-    expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
-    const maxAgeSeconds = parseInt(
-      (res.headers['cache-control'] || '').match(/max-age=(\d+)/)?.[1] || '',
-      10,
-    )
-    // Let's not be too specific in the tests, just as long as it's testing
-    // that it's a reasonably large number of seconds.
-    expect(maxAgeSeconds).toBeGreaterThanOrEqual(60 * 60)
+    expectAggressiveCaching(res.headers)
     expect(res.headers['surrogate-key']).toBe(SURROGATE_ENUMS.MANUAL)
   })
 

src/frame/tests/server.ts

@@ -75,10 +75,25 @@ describe('server', () => {
     expect(surrogateKeySplit.includes(makeLanguageSurrogateKey('en'))).toBeTruthy()
   })
 
+  test('caches responses with short edge freshness and a week-long stale window', async () => {
+    const week = 60 * 60 * 24 * 7
+    for (const path of ['/en/get-started', '/robots.txt']) {
+      const res = await get(path)
+      expect(res.statusCode).toBe(200)
+      const surrogate = res.headers['surrogate-control']
+      expect(surrogate).toContain(`stale-while-revalidate=${week}`)
+      expect(surrogate).toContain(`stale-if-error=${week}`)
+      // Edge freshness is short (well under the week-long stale window).
+      const maxAge = Number(surrogate.match(/(?:^|[ ,])max-age=(\d+)/)?.[1])
+      expect(maxAge).toBeGreaterThan(0)
+      expect(maxAge).toBeLessThan(week)
+    }
+    // Browser cache stays short: 60s, unpurgeable.
+    const res = await get('/en/get-started')
+    expect(res.headers['cache-control']).toMatch(/(^|[ ,])max-age=60([ ,]|$)/)
+  })
+
   test('sets fine-grained product and version surrogate keys on content pages', async () => {
-    // docs-engineering#6719: content pages emit language, product, version, and
-    // a product,language compound key so per-deploy purges can target the
-    // tightest key instead of a whole language.
     const res = await get('/en/get-started')
     expect(res.statusCode).toBe(200)
     const keys = res.headers['surrogate-key'].split(/\s/g)

src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh

@@ -32,18 +32,34 @@ gh api -X PUT "/orgs/github/teams/docs-engineering/repos/github/docs-ghes-$versi
         -f 'permission=admin' --silent
 echo "--- github/employees as read"
 gh api -X PUT "/orgs/github/teams/employees/repos/github/docs-ghes-$version" --silent
-echo "--- Require a pull request review before merging"
-repositoryId="$(gh api graphql -f query="{repository(owner:\"github\",name:\"docs-ghes-$version\"){id}}" -q .data.repository.id)"
-gh api graphql -f query='
-mutation($repositoryId:ID!,$branch:String!,$requiredReviews:Int!) {
-  createBranchProtectionRule(input: {
-    repositoryId: $repositoryId
-    pattern: $branch
-    requiresApprovingReviews: true
-    requiredApprovingReviewCount: $requiredReviews
-    requiresCodeOwnerReviews: true
-  }) { clientMutationId }
-}' -f repositoryId="$repositoryId" -f branch=main -F requiredReviews=1 --silent
+echo "--- Protect main with a repository ruleset (1 review + code owners, no force-push or deletion)"
+gh api -X POST "/repos/github/docs-ghes-$version/rulesets" --input - --silent <<'RULESET'
+{
+  "name": "main branch protection",
+  "target": "branch",
+  "enforcement": "active",
+  "bypass_actors": [
+    { "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always" }
+  ],
+  "conditions": {
+    "ref_name": { "include": ["refs/heads/main"], "exclude": [] }
+  },
+  "rules": [
+    { "type": "deletion" },
+    { "type": "non_fast_forward" },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 1,
+        "dismiss_stale_reviews_on_push": false,
+        "require_code_owner_review": true,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": false
+      }
+    }
+  ]
+}
+RULESET
 echo "--- Enable GitHub Pages, set source to main in root directory, and make the pages site public"
 gh api -X POST "/repos/github/docs-ghes-$version/pages" \
   -f "source[branch]=main" -f "source[path]=/" -F "public=true" --silent