From 3816ce34e9bc41e454accf2807e0d89f5e9ce294 Mon Sep 17 00:00:00 2001 From: Sunbrye Ly <56200261+sunbrye@users.noreply.github.com> Date: Wed, 9 Sep 2026 16:18:26 +0000 Subject: [PATCH 1/2] Move SDK quickstart to get started (#63036) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Jenni C <97056108+dihydroJenoxide@users.noreply.github.com> Copilot-Session: a8e2667d-7f41-4341-b1ca-58c0a42d3a73 --- .github/workflows/sync-sdk-docs.yml | 5 + content/copilot/get-started/index.md | 1 + .../sdk-quickstart.md} | 15 +- .../how-tos/copilot-sdk/auth/authenticate.md | 2 +- .../copilot/how-tos/copilot-sdk/auth/byok.md | 2 +- .../how-tos/copilot-sdk/features/hooks.md | 2 +- .../how-tos/copilot-sdk/features/mcp.md | 2 +- .../how-tos/copilot-sdk/features/skills.md | 4 +- .../features/steering-and-queueing.md | 2 +- .../copilot-sdk/hooks/hooks-overview.md | 4 +- content/copilot/how-tos/copilot-sdk/index.md | 1 - .../integrations/microsoft-agent-framework.md | 6 +- .../how-tos/copilot-sdk/setup/bundled-cli.md | 2 +- .../setup/choosing-a-setup-path.md | 2 +- .../how-tos/copilot-sdk/setup/local-cli.md | 2 +- .../troubleshooting/compatibility.md | 2 +- .../copilot-sdk/troubleshooting/debugging.md | 2 +- content/copilot/responsible-use/agents.md | 2 +- .../sync-sdk-docs/normalize-sdk-docs.ts | 143 +++++++++++++++++- 19 files changed, 174 insertions(+), 27 deletions(-) rename content/copilot/{how-tos/copilot-sdk/getting-started.md => get-started/sdk-quickstart.md} (99%) diff --git a/.github/workflows/sync-sdk-docs.yml b/.github/workflows/sync-sdk-docs.yml index b8d56344aaca..82a1b2d3a1b4 100644 --- a/.github/workflows/sync-sdk-docs.yml +++ b/.github/workflows/sync-sdk-docs.yml @@ -24,6 +24,7 @@ on: types: [opened, synchronize, reopened] paths: - '.github/workflows/sync-sdk-docs.yml' + - 'content/copilot/get-started/sdk-quickstart.md' - 'src/workflows/sync-sdk-docs/**' concurrency: @@ -77,6 +78,10 @@ jobs: - name: Copy SDK docs run: | mkdir -p "$SDK_DOCS_TARGET" + # Pages relocated out of this tree into hand-authored content are not + # excluded here — they are removed by the RELOCATED_PAGES map in + # src/workflows/sync-sdk-docs/normalize-sdk-docs.ts, which also + # repoints inbound links at their new URLs. rsync -av --exclude='.validation/' --exclude='developer-docs/' "$SDK_TMP/docs/" "$SDK_DOCS_TARGET/" echo "Copied $(find "$SDK_DOCS_TARGET" -name '*.md' | wc -l | tr -d ' ') markdown files" diff --git a/content/copilot/get-started/index.md b/content/copilot/get-started/index.md index 04fd99c3a261..62e71e31c8f0 100644 --- a/content/copilot/get-started/index.md +++ b/content/copilot/get-started/index.md @@ -8,6 +8,7 @@ children: - /quickstart - /cli-quickstart - /quickstart-copilot-app + - /sdk-quickstart - /what-is-github-copilot - /plans - /features diff --git a/content/copilot/how-tos/copilot-sdk/getting-started.md b/content/copilot/get-started/sdk-quickstart.md similarity index 99% rename from content/copilot/how-tos/copilot-sdk/getting-started.md rename to content/copilot/get-started/sdk-quickstart.md index 0b14f781ee31..33db9d2e1cab 100644 --- a/content/copilot/how-tos/copilot-sdk/getting-started.md +++ b/content/copilot/get-started/sdk-quickstart.md @@ -1,21 +1,22 @@ --- title: Build your first Copilot-powered app -shortTitle: Getting Started +shortTitle: Copilot SDK quickstart +allowTitleToDifferFromFilename: true intro: >- In this tutorial, you'll use the Copilot SDK to build a command-line assistant. You'll start with the basics, add streaming responses, then add custom tools - giving Copilot the ability to call your code. versions: - fpt: '*' - ghec: '*' + feature: copilot redirect_from: - /copilot/how-tos/copilot-sdk/sdk-getting-started -contentType: how-tos + - /copilot/how-tos/copilot-sdk/getting-started +contentType: get-started +category: + - Quickstarts + - Integrate Copilot with your tools --- - - - **What you'll build:** ```text diff --git a/content/copilot/how-tos/copilot-sdk/auth/authenticate.md b/content/copilot/how-tos/copilot-sdk/auth/authenticate.md index 7b6068443725..efd6654f5bb8 100644 --- a/content/copilot/how-tos/copilot-sdk/auth/authenticate.md +++ b/content/copilot/how-tos/copilot-sdk/auth/authenticate.md @@ -404,5 +404,5 @@ const client = new CopilotClient({ ## Next steps * [AUTOTITLE](/copilot/how-tos/copilot-sdk/auth/byok) - Learn how to use your own API keys -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started) - Build your first Copilot-powered app +* [AUTOTITLE](/copilot/get-started/sdk-quickstart) - Build your first Copilot-powered app * [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/mcp) - Connect to external tools diff --git a/content/copilot/how-tos/copilot-sdk/auth/byok.md b/content/copilot/how-tos/copilot-sdk/auth/byok.md index a5ec405399ee..6624808ec975 100644 --- a/content/copilot/how-tos/copilot-sdk/auth/byok.md +++ b/content/copilot/how-tos/copilot-sdk/auth/byok.md @@ -594,4 +594,4 @@ foundry model run phi-4-mini ## Next steps * [AUTOTITLE](/copilot/how-tos/copilot-sdk/auth) - Learn about all authentication methods -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started) - Build your first Copilot-powered app +* [AUTOTITLE](/copilot/get-started/sdk-quickstart) - Build your first Copilot-powered app diff --git a/content/copilot/how-tos/copilot-sdk/features/hooks.md b/content/copilot/how-tos/copilot-sdk/features/hooks.md index 3958e751636a..172c78fd7633 100644 --- a/content/copilot/how-tos/copilot-sdk/features/hooks.md +++ b/content/copilot/how-tos/copilot-sdk/features/hooks.md @@ -890,7 +890,7 @@ For full type definitions, input/output field tables, and additional examples fo ## See also -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started) +* [AUTOTITLE](/copilot/get-started/sdk-quickstart) * [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/custom-agents) * [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/streaming-events) * [AUTOTITLE](/copilot/how-tos/copilot-sdk/troubleshooting/debugging) diff --git a/content/copilot/how-tos/copilot-sdk/features/mcp.md b/content/copilot/how-tos/copilot-sdk/features/mcp.md index d23b054c0bb9..9569df0f34d1 100644 --- a/content/copilot/how-tos/copilot-sdk/features/mcp.md +++ b/content/copilot/how-tos/copilot-sdk/features/mcp.md @@ -340,7 +340,7 @@ For detailed debugging guidance, see the **[AUTOTITLE](/copilot/how-tos/copilot- * [Model Context Protocol Specification](https://modelcontextprotocol.io/) * [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Community MCP servers * [GitHub MCP Server](https://github.com/github/github-mcp-server) - Official GitHub MCP server -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started) - SDK basics and custom tools +* [AUTOTITLE](/copilot/get-started/sdk-quickstart) - SDK basics and custom tools * [AUTOTITLE](/copilot/how-tos/copilot-sdk/troubleshooting/debugging) - SDK-wide debugging ## See also diff --git a/content/copilot/how-tos/copilot-sdk/features/skills.md b/content/copilot/how-tos/copilot-sdk/features/skills.md index 17676dc35f94..71fa9121dc63 100644 --- a/content/copilot/how-tos/copilot-sdk/features/skills.md +++ b/content/copilot/how-tos/copilot-sdk/features/skills.md @@ -373,6 +373,6 @@ If multiple skills provide conflicting instructions: ## See also -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started#create-custom-agents) - Define specialized AI personas -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started#step-4-add-a-custom-tool) - Build your own tools +* [AUTOTITLE](/copilot/get-started/sdk-quickstart#create-custom-agents) - Define specialized AI personas +* [AUTOTITLE](/copilot/get-started/sdk-quickstart#step-4-add-a-custom-tool) - Build your own tools * [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/mcp) - Connect external tool providers diff --git a/content/copilot/how-tos/copilot-sdk/features/steering-and-queueing.md b/content/copilot/how-tos/copilot-sdk/features/steering-and-queueing.md index b1576cef0332..3669f9c5c2ca 100644 --- a/content/copilot/how-tos/copilot-sdk/features/steering-and-queueing.md +++ b/content/copilot/how-tos/copilot-sdk/features/steering-and-queueing.md @@ -546,7 +546,7 @@ class InteractiveChat { ## See also -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started): Set up a session and send messages +* [AUTOTITLE](/copilot/get-started/sdk-quickstart): Set up a session and send messages * [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/custom-agents): Define specialized agents with scoped tools * [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/hooks-overview): React to session lifecycle events * [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/session-persistence): Resume sessions across restarts diff --git a/content/copilot/how-tos/copilot-sdk/hooks/hooks-overview.md b/content/copilot/how-tos/copilot-sdk/hooks/hooks-overview.md index 2a5df49b0ab7..58541e6eeb89 100644 --- a/content/copilot/how-tos/copilot-sdk/hooks/hooks-overview.md +++ b/content/copilot/how-tos/copilot-sdk/hooks/hooks-overview.md @@ -277,6 +277,6 @@ const session = await client.createSession({ ## See also -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started) -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started#step-4-add-a-custom-tool) +* [AUTOTITLE](/copilot/get-started/sdk-quickstart) +* [AUTOTITLE](/copilot/get-started/sdk-quickstart#step-4-add-a-custom-tool) * [AUTOTITLE](/copilot/how-tos/copilot-sdk/troubleshooting/debugging) diff --git a/content/copilot/how-tos/copilot-sdk/index.md b/content/copilot/how-tos/copilot-sdk/index.md index 094b1f3411a1..2285a39ff9fa 100644 --- a/content/copilot/how-tos/copilot-sdk/index.md +++ b/content/copilot/how-tos/copilot-sdk/index.md @@ -9,7 +9,6 @@ versions: ghec: '*' contentType: how-tos children: - - /getting-started - /auth - /features - /hooks diff --git a/content/copilot/how-tos/copilot-sdk/integrations/microsoft-agent-framework.md b/content/copilot/how-tos/copilot-sdk/integrations/microsoft-agent-framework.md index 2bc40d5b2b24..ce4a8769c230 100644 --- a/content/copilot/how-tos/copilot-sdk/integrations/microsoft-agent-framework.md +++ b/content/copilot/how-tos/copilot-sdk/integrations/microsoft-agent-framework.md @@ -33,7 +33,7 @@ The Microsoft Agent Framework is the unified successor to Semantic Kernel and Au Before you begin, ensure you have: -* A working [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started) in your language of choice +* A working [AUTOTITLE](/copilot/get-started/sdk-quickstart) in your language of choice * A GitHub Copilot subscription (Individual, Business, or Enterprise) * The Copilot CLI installed or available via the SDK's bundled CLI @@ -593,7 +593,7 @@ client.stop().get(); ### Copilot SDK options (passed through) -All standard [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started) options are still available when creating the underlying Copilot client. The MAF wrapper delegates to the SDK under the hood: +All standard [AUTOTITLE](/copilot/get-started/sdk-quickstart) options are still available when creating the underlying Copilot client. The MAF wrapper delegates to the SDK under the hood: | SDK Feature | MAF Support | |-------------|-------------| @@ -661,7 +661,7 @@ catch (AgentException ex) ## See also -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started): initial Copilot SDK setup +* [AUTOTITLE](/copilot/get-started/sdk-quickstart): initial Copilot SDK setup * [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/custom-agents): define specialized sub-agents within the SDK * [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/skills): reusable prompt modules * [Microsoft Agent Framework documentation](https://learn.microsoft.com/en-us/agent-framework/agents/providers/github-copilot): official MAF docs for the Copilot provider diff --git a/content/copilot/how-tos/copilot-sdk/setup/bundled-cli.md b/content/copilot/how-tos/copilot-sdk/setup/bundled-cli.md index 7f9f3b012772..51076cb21120 100644 --- a/content/copilot/how-tos/copilot-sdk/setup/bundled-cli.md +++ b/content/copilot/how-tos/copilot-sdk/setup/bundled-cli.md @@ -215,4 +215,4 @@ Session state persists at `~/.copilot/session-state/{sessionId}/`. * **[AUTOTITLE](/copilot/how-tos/copilot-sdk/auth/byok)**: Use your own model provider keys * **[AUTOTITLE](/copilot/how-tos/copilot-sdk/features/session-persistence)**: Advanced session management -* **[AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started)**: Build a complete app +* **[AUTOTITLE](/copilot/get-started/sdk-quickstart)**: Build a complete app diff --git a/content/copilot/how-tos/copilot-sdk/setup/choosing-a-setup-path.md b/content/copilot/how-tos/copilot-sdk/setup/choosing-a-setup-path.md index 79d5e41f9608..34c16e7d36cd 100644 --- a/content/copilot/how-tos/copilot-sdk/setup/choosing-a-setup-path.md +++ b/content/copilot/how-tos/copilot-sdk/setup/choosing-a-setup-path.md @@ -101,7 +101,7 @@ All guides assume you have: * Go: `go get github.com/github/copilot-sdk/go` (requires separate CLI installation) * .NET: `dotnet add package GitHub.Copilot.SDK` -If you're brand new, start with the **[AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started)** first, then come back here for production configuration. +If you're brand new, start with the **[AUTOTITLE](/copilot/get-started/sdk-quickstart)** first, then come back here for production configuration. ## Next steps diff --git a/content/copilot/how-tos/copilot-sdk/setup/local-cli.md b/content/copilot/how-tos/copilot-sdk/setup/local-cli.md index 541c481c4038..8efe570391ed 100644 --- a/content/copilot/how-tos/copilot-sdk/setup/local-cli.md +++ b/content/copilot/how-tos/copilot-sdk/setup/local-cli.md @@ -177,5 +177,5 @@ Session state is stored locally at `~/.copilot/session-state/{sessionId}/`. ## Next steps * **[AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/bundled-cli)**: Use the SDK's built-in CLI (recommended for most use cases) -* **[AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started)**: Build a complete interactive app +* **[AUTOTITLE](/copilot/get-started/sdk-quickstart)**: Build a complete interactive app * **[AUTOTITLE](/copilot/how-tos/copilot-sdk/auth/authenticate)**: All auth methods in detail diff --git a/content/copilot/how-tos/copilot-sdk/troubleshooting/compatibility.md b/content/copilot/how-tos/copilot-sdk/troubleshooting/compatibility.md index 4499e127ded7..5a1f9a6cd656 100644 --- a/content/copilot/how-tos/copilot-sdk/troubleshooting/compatibility.md +++ b/content/copilot/how-tos/copilot-sdk/troubleshooting/compatibility.md @@ -308,7 +308,7 @@ console.log("Protocol version:", status.protocolVersion); ## See also -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started) +* [AUTOTITLE](/copilot/get-started/sdk-quickstart) * [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/hooks-overview) * [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/mcp) * [AUTOTITLE](/copilot/how-tos/copilot-sdk/troubleshooting/debugging) diff --git a/content/copilot/how-tos/copilot-sdk/troubleshooting/debugging.md b/content/copilot/how-tos/copilot-sdk/troubleshooting/debugging.md index bcd88f945ae6..5f99af3540d1 100644 --- a/content/copilot/how-tos/copilot-sdk/troubleshooting/debugging.md +++ b/content/copilot/how-tos/copilot-sdk/troubleshooting/debugging.md @@ -538,7 +538,7 @@ If you're still stuck: ## See also -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started) +* [AUTOTITLE](/copilot/get-started/sdk-quickstart) * [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/mcp) - MCP configuration and setup * [AUTOTITLE](/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) - Detailed MCP troubleshooting * [API Reference](https://github.com/github/copilot-sdk) diff --git a/content/copilot/responsible-use/agents.md b/content/copilot/responsible-use/agents.md index 6ccf2ca743bb..9c744465e944 100644 --- a/content/copilot/responsible-use/agents.md +++ b/content/copilot/responsible-use/agents.md @@ -285,7 +285,7 @@ For additional guidance on the responsible use of Copilot agentic features, we r * [AUTOTITLE](/copilot/tutorials/cloud-agent/get-the-best-results) * [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment) * [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/customize-the-firewall) -* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started) +* [AUTOTITLE](/copilot/get-started/sdk-quickstart) * [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers) * [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-copilot-cli) * [AUTOTITLE](/copilot/concepts/agents/github-copilot-app) diff --git a/src/workflows/sync-sdk-docs/normalize-sdk-docs.ts b/src/workflows/sync-sdk-docs/normalize-sdk-docs.ts index 37bf35d3af3c..a4a1ec29566f 100644 --- a/src/workflows/sync-sdk-docs/normalize-sdk-docs.ts +++ b/src/workflows/sync-sdk-docs/normalize-sdk-docs.ts @@ -4,6 +4,8 @@ * Normalizes Copilot SDK docs for publishing on docs.github.com. * * For every .md file in the SDK docs directory, this script: + * - Removes pages that have been relocated out of the synced tree + * (see RELOCATED_PAGES) and repoints inbound links at their new URLs * - Renames README.md files to index.md (the SDK repo uses README.md as the * landing page for each docs directory; docs-internal requires index.md) * - Adds YAML frontmatter (title, intro, shortTitle, versions, contentType) @@ -41,6 +43,35 @@ const { values: args } = parseArgs({ const CONTENT_DIR = path.resolve(args['content-dir'] as string) const SDK_DOCS_DIR = path.resolve(args['sdk-docs-dir'] as string) +/** + * Pages that have been relocated OUT of the synced SDK docs tree into + * hand-authored content elsewhere in docs-internal. + * + * Keys are paths relative to the SDK docs root, exactly as they appear upstream + * in github/copilot-sdk's `docs/` directory. Values are the docs.github.com URL + * the page now lives at. + * + * Each entry does two inseparable things on every sync: + * 1. Deletes the upstream copy after it is rsynced in (Step 0a), so the page + * is not republished at its old URL — that URL is now a `redirect_from` on + * the hand-authored page and must stay vacant. + * 2. Teaches the internal-link rewriter (Step 3) to point inbound relative + * links at the new URL, instead of logging "target missing" and leaving a + * raw `../getting-started.md` link in published content. + * + * Both halves must stay together, which is why this lives here rather than as an + * rsync `--exclude` in .github/workflows/sync-sdk-docs.yml: excluding the file + * at copy time without remapping its links would ship ~17 broken links. + * + * Destinations are validated on every run; see validateRelocatedDestinations(). + */ +const RELOCATED_PAGES: Record = { + 'getting-started.md': '/copilot/get-started/sdk-quickstart', +} + +/** Relocated pages whose upstream source file was not found during this sync. */ +const missingRelocatedSources: string[] = [] + if (!fs.existsSync(CONTENT_DIR)) { console.error(`Content directory not found: ${CONTENT_DIR}`) process.exit(1) @@ -142,6 +173,98 @@ function convertReadmesToIndex(): void { } } +/** + * Return the new URL for a relocated page, given an absolute path inside the + * SDK docs tree. Returns undefined for pages that have not been relocated. + */ +function relocatedUrlFor(absPath: string): string | undefined { + return RELOCATED_PAGES[path.relative(SDK_DOCS_DIR, absPath)] +} + +/** + * Step 0a: Delete pages that have been relocated out of the synced tree. + * + * The sync `rm -rf`s and re-rsyncs this whole directory every run, so a page + * moved into hand-authored content elsewhere in docs-internal would otherwise + * reappear at its old URL on the next sync and collide with the `redirect_from` + * that now claims it. (Redirect compilation resolves that collision by dropping + * the redirect, so the deletion is a hard invariant, not a tidiness measure.) + * + * This runs before every other step, so keys stay expressed in upstream terms: + * before Step 0 renames `README.md` to `index.md`, and before Step 1 so that + * `getChildren()` never sees the file and the parent index.md's `children` + * array is free of dangling entries. + * + * A missing source is reported rather than ignored: it usually means upstream + * renamed the file, in which case the page silently republishes under a new URL + * and the vacated URL may be reclaimed. It does not fail the sync, because + * github/copilot-sdk is a separate repo that may legitimately delete the page + * once docs-internal is canonical. + */ +function removeRelocatedPages(): void { + for (const [relPath, newUrl] of Object.entries(RELOCATED_PAGES)) { + const absPath = path.join(SDK_DOCS_DIR, relPath) + if (!fs.existsSync(absPath)) { + missingRelocatedSources.push(relPath) + console.log(` WARN (relocated source missing upstream): ${relPath}`) + continue + } + fs.rmSync(absPath) + console.log(` RELOCATED: ${relPath} -> ${newUrl}`) + } +} + +/** + * Validate that every relocated page's destination actually exists in the + * hand-authored content tree. A typo or an unrelated rename would otherwise + * silently repoint every inbound link at a 404. + * + * Unlike a missing upstream source, this is entirely within docs-internal's + * control, so it fails the sync. It runs before anything mutates the tree. + */ +function validateRelocatedDestinations(): void { + const broken: string[] = [] + + for (const [relPath, newUrl] of Object.entries(RELOCATED_PAGES)) { + const base = path.join(CONTENT_DIR, newUrl) + if (!fs.existsSync(`${base}.md`) && !fs.existsSync(path.join(base, 'index.md'))) { + broken.push(`${relPath} -> ${newUrl}`) + } + } + + if (broken.length === 0) return + + console.error('RELOCATED_PAGES points at destinations that do not exist in the content tree:') + for (const entry of broken) console.error(` ${entry}`) + console.error('Update RELOCATED_PAGES in src/workflows/sync-sdk-docs/normalize-sdk-docs.ts.') + process.exit(1) +} + +/** + * Report relocated pages whose upstream source vanished, to the Actions job + * summary linked from the generated PR. Mirrors reportUnbalancedMarkers(): the + * run log alone is not something a PR reviewer will see. + */ +function reportMissingRelocatedSources(): void { + const summaryPath = process.env.GITHUB_STEP_SUMMARY + if (missingRelocatedSources.length === 0 || !summaryPath) return + + const lines = [ + '### ⚠️ Relocated page missing from upstream', + '', + 'These pages are listed in `RELOCATED_PAGES` but no longer exist in', + '[copilot-sdk docs](https://github.com/github/copilot-sdk/tree/main/docs).', + 'If upstream **renamed** the file, it is now republishing under a new URL and may have', + 'reclaimed the URL this move vacated — update `RELOCATED_PAGES`. If upstream', + '**deleted** it deliberately, remove the entry instead.', + '', + ...missingRelocatedSources.map((source) => `* \`${source}\``), + '', + ] + + fs.appendFileSync(summaryPath, lines.join('\n')) +} + /** Convert a filename slug to a title-case short title. */ function slugToTitle(slug: string): string { const ACRONYMS: Record = { @@ -303,6 +426,16 @@ function rewriteInternalLinks(filePath: string): void { const resolved = path.resolve(dir, rawPath) if (!resolved.startsWith(CONTENT_DIR)) return _match + + // Pages relocated out of the synced tree no longer exist on disk, so the + // existence check below would leave a raw relative link. Repoint them at + // their new home instead. + const relocatedUrl = relocatedUrlFor(resolved) + if (relocatedUrl) { + changed = true + return `[AUTOTITLE](${relocatedUrl}${anchor ? `#${anchor}` : ''})` + } + if (!fs.existsSync(resolved)) { console.log(` WARN (target missing): ${href} in ${path.relative(SDK_DOCS_DIR, filePath)}`) return _match @@ -896,9 +1029,17 @@ function suppressSdkLintRules(filePath: string): void { console.log(`Normalizing SDK docs in: ${SDK_DOCS_DIR}`) console.log(`Content directory: ${CONTENT_DIR}\n`) +// Step 0a: Remove pages relocated out of the synced tree (see RELOCATED_PAGES). +// Runs first so keys stay expressed in upstream terms (before README->index +// renaming) and so getChildren() never lists a relocated page. +validateRelocatedDestinations() +console.log('--- Removing relocated pages ---\n') +removeRelocatedPages() +reportMissingRelocatedSources() + // Step 0: Rename README.md files to index.md (copilot-sdk uses README.md as // directory landing pages; docs-internal requires index.md). -console.log('--- Renaming README.md files to index.md ---\n') +console.log('\n--- Renaming README.md files to index.md ---\n') convertReadmesToIndex() // Step 1: Add frontmatter From 68515935588310da3ff587b6c9de53d666909877 Mon Sep 17 00:00:00 2001 From: Steve Ward Date: Wed, 9 Sep 2026 16:57:20 +0000 Subject: [PATCH 2/2] Document the ability to delegate any PR comment to Copilot (#62901) Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> --- .../cloud-agent/use-cloud-agent-on-github.md | 21 ++++++++++++++++++- ...rporating-feedback-in-your-pull-request.md | 6 ++++++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/content/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-on-github.md b/content/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-on-github.md index dd6f4579c433..1be6dcd31f13 100644 --- a/content/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-on-github.md +++ b/content/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-on-github.md @@ -138,11 +138,30 @@ When an {% data variables.product.prodname_actions %} workflow run fails on a pu ## Continuing work on a pull request +You can ask {% data variables.product.prodname_copilot_short %} to make changes or address review comments on an existing pull request. You can then track the resulting session and provide follow-up instructions. + +### Asking {% data variables.product.prodname_copilot_short %} to make changes + You can mention `@copilot` in a comment on any pull request to ask {% data variables.product.prodname_copilot_short %} to make changes. This works on pull requests created by {% data variables.product.prodname_copilot_short %} and on pull requests you or others created. By default, {% data variables.product.prodname_copilot_short %} pushes commits directly to the pull request branch. To create a separate pull request instead, describe that in your comment. You can also check out the branch and push changes yourself. -Batch review comments instead of submitting them individually. When submitting a pull request comment (not a review or review comment) through the {% data variables.product.github %} web interface, select a model with the model picker. {% data variables.product.prodname_copilot_short %} uses the model from the original pull request by default. +When submitting a pull request comment (not a review or review comment) through the {% data variables.product.github %} web interface, select a model with the model picker. {% data variables.product.prodname_copilot_short %} uses the model from the original pull request by default. + +### Delegating review comments + +You can delegate review comments to have {% data variables.product.prodname_copilot_short %} implement feedback from human reviewers and {% data variables.copilot.copilot_code-review %}. + +1. In the pull request, open the **Files changed** tab. +1. Navigate to the first review comment you want {% data variables.product.prodname_copilot_short %} to implement. + * To delegate one comment, click **Fix with {% data variables.product.prodname_copilot_short %}**. + * To delegate multiple comments, click **Add to batch**. Continue to add the comments you want {% data variables.product.prodname_copilot_short %} to work on. +1. In the **Manage batch** panel, add any additional instructions, and optionally select a model with the model picker. +1. Choose how you want {% data variables.product.prodname_copilot_short %} to apply the changes: + * To commit the changes directly to the branch, click **{% octicon "agent" aria-label="The Agents icon" %} Fix and commit**. + * To have {% data variables.product.prodname_copilot_short %} create a new pull request with the changes, click **Fix and open pull request** from the dropdown menu. + +### Tracking and continuing a session {% data reusables.copilot.cloud-agent.write-access-required %} diff --git a/content/pull-requests/how-tos/review-pull-requests/incorporating-feedback-in-your-pull-request.md b/content/pull-requests/how-tos/review-pull-requests/incorporating-feedback-in-your-pull-request.md index 2ec8f7488301..e42cdc06da06 100644 --- a/content/pull-requests/how-tos/review-pull-requests/incorporating-feedback-in-your-pull-request.md +++ b/content/pull-requests/how-tos/review-pull-requests/incorporating-feedback-in-your-pull-request.md @@ -40,6 +40,12 @@ Each person who suggested a change included in the commit will be a co-author of 1. In the commit message field, type a short, meaningful commit message that describes the change you made to the file or files. 1. Click **Commit changes**. +{% ifversion fpt or ghec %} +## Delegating review comments to {% data variables.product.prodname_copilot_short %} + +If you have access to {% data variables.copilot.copilot_cloud_agent %}, you can delegate review comments to have {% data variables.product.prodname_copilot_short %} implement the feedback. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-on-github#delegating-review-comments). +{% endif %} + ## Re-requesting a review For example, you can re-request a review after you've made substantial changes to your pull request.