From 5f3d66c3801f8b8d7ac4ebf8395414e5d0d8f848 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 2 Apr 2026 10:03:56 +1100 Subject: [PATCH] docs(learning-hub): document Copilot CLI v1.0.15 new features (#1258) - Add postToolUseFailure hook event to automating-with-hooks.md: clarify that postToolUse now only fires on success, add new event to the events table, and add a practical example with migration note - Add /mcp auth command and device code flow (RFC 8628) to understanding-mcp-servers.md authentication section - Add mcp.config.list/add/update/remove server RPCs section to understanding-mcp-servers.md - Add /share html command to copilot-configuration-basics.md CLI Session Commands section - Update lastUpdated dates to 2026-04-01 Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../learning-hub/automating-with-hooks.md | 29 +++++++++++++++++-- .../copilot-configuration-basics.md | 10 ++++++- .../learning-hub/understanding-mcp-servers.md | 19 +++++++++++- 3 files changed, 54 insertions(+), 4 deletions(-) diff --git a/website/src/content/docs/learning-hub/automating-with-hooks.md b/website/src/content/docs/learning-hub/automating-with-hooks.md index 0ab45a32..6e1b7c7a 100644 --- a/website/src/content/docs/learning-hub/automating-with-hooks.md +++ b/website/src/content/docs/learning-hub/automating-with-hooks.md @@ -3,7 +3,7 @@ title: 'Automating with Hooks' description: 'Learn how to use hooks to automate lifecycle events like formatting, linting, and governance checks during Copilot agent sessions.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-03-28 +lastUpdated: 2026-04-01 estimatedReadingTime: '8 minutes' tags: - hooks @@ -91,7 +91,8 @@ Hooks can trigger on several lifecycle events: | `sessionEnd` | Agent session completes or is terminated | Clean up temp files, generate reports, send notifications | | `userPromptSubmitted` | User submits a prompt | Log requests for auditing and compliance | | `preToolUse` | Before the agent uses any tool (e.g., `bash`, `edit`) | **Approve or deny** tool executions, block dangerous commands, enforce security policies | -| `postToolUse` | After a tool completes execution | Log results, track usage, format code after edits, send failure alerts | +| `postToolUse` | After a tool **successfully** completes execution | Log results, track usage, format code after edits | +| `postToolUseFailure` | When a tool call **fails with an error** | Log errors for debugging, send failure alerts, track error patterns | | `agentStop` | Main agent finishes responding to a prompt | Run final linters/formatters, validate complete changes | | `preCompact` | Before the agent compacts its context window | Save a snapshot, log compaction event, run summary scripts | | `subagentStart` | A subagent is spawned by the main agent | Inject additional context into the subagent's prompt, log subagent launches | @@ -206,6 +207,30 @@ automatically before the agent commits changes. ## Practical Examples +### Handling Tool Failures with postToolUseFailure + +The `postToolUseFailure` hook fires when a tool call fails with an error — distinct from `postToolUse`, which only fires on success. Use it to log errors, send failure alerts, or implement retry logic: + +```json +{ + "version": 1, + "hooks": { + "postToolUseFailure": [ + { + "type": "command", + "bash": "./scripts/notify-tool-failure.sh", + "cwd": ".", + "timeoutSec": 10 + } + ] + } +} +``` + +The hook receives JSON input describing which tool failed and the error message. This separation lets you write targeted failure-handling logic without adding conditional checks to your `postToolUse` hooks. + +> **Note**: Before v1.0.15, `postToolUse` fired for both successful and failed tool calls. If you have existing `postToolUse` hooks that handle failures, migrate that logic to `postToolUseFailure`. + ### Auto-Format After Edits Ensure all code is formatted after the agent edits files: diff --git a/website/src/content/docs/learning-hub/copilot-configuration-basics.md b/website/src/content/docs/learning-hub/copilot-configuration-basics.md index c4dffae9..6e080d51 100644 --- a/website/src/content/docs/learning-hub/copilot-configuration-basics.md +++ b/website/src/content/docs/learning-hub/copilot-configuration-basics.md @@ -3,7 +3,7 @@ title: 'Copilot Configuration Basics' description: 'Learn how to configure GitHub Copilot at user, workspace, and repository levels to optimize your AI-assisted development experience.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-03-30 +lastUpdated: 2026-04-01 estimatedReadingTime: '10 minutes' tags: - configuration @@ -449,6 +449,14 @@ The `/cd` command changes the working directory for the current session. Each se This is useful when you have multiple backgrounded sessions each focused on a different project directory. +The `/share html` command exports the current session — including conversation history and any research reports — as a **self-contained interactive HTML file**: + +``` +/share html +``` + +The exported file contains everything needed to view the session without a network connection and can be shared with teammates or stored for later reference. This complements `/share` (which shares via URL) for cases where an offline or attached format is preferred. + The `/allow-all` command (also accessible as `/yolo`) enables autopilot mode, where the agent runs all tools without asking for confirmation. It now supports `on`, `off`, and `show` subcommands: ``` diff --git a/website/src/content/docs/learning-hub/understanding-mcp-servers.md b/website/src/content/docs/learning-hub/understanding-mcp-servers.md index 9a6b9911..72af15f3 100644 --- a/website/src/content/docs/learning-hub/understanding-mcp-servers.md +++ b/website/src/content/docs/learning-hub/understanding-mcp-servers.md @@ -3,7 +3,7 @@ title: 'Understanding MCP Servers' description: 'Learn how Model Context Protocol servers extend GitHub Copilot with access to external tools, databases, and APIs.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-03-30 +lastUpdated: 2026-04-01 estimatedReadingTime: '8 minutes' tags: - mcp @@ -99,6 +99,21 @@ Example `.mcp.json` or `.vscode/mcp.json`: **env**: Environment variables passed to the server process. Use these for connection strings, API keys, and configuration—never hardcode secrets in the JSON file. +### Managing Persistent MCP Configuration via Server RPCs + +In addition to file-based configuration, GitHub Copilot CLI exposes **server RPCs** that let MCP servers and tooling scripts manage the persistent MCP server registry at runtime. This enables programmatic setup — for example, an installer script that registers a server without requiring you to hand-edit a JSON file. + +The available RPCs are: + +| RPC | Description | +|-----|-------------| +| `mcp.config.list` | List all currently registered persistent MCP servers | +| `mcp.config.add` | Add a new MCP server to the persistent configuration | +| `mcp.config.update` | Update an existing registered server | +| `mcp.config.remove` | Remove a server from the persistent configuration | + +These are especially useful for plugins and installer scripts that need to self-register or de-register their MCP server as part of install/uninstall flows, without requiring the user to manually edit config files. + ### Common MCP Server Configurations **PostgreSQL** — Query databases and inspect schemas: @@ -144,6 +159,8 @@ Example `.mcp.json` or `.vscode/mcp.json`: Some MCP servers require authentication to connect to protected resources. GitHub Copilot CLI supports several authentication approaches: - **OAuth**: MCP servers can use the OAuth flow to authenticate with external services. The CLI handles the browser redirect and token storage automatically. This also works when running in ACP (Agent Coordination Protocol) mode. +- **Device code flow (RFC 8628)**: When the CLI runs in a **headless or CI environment** where a browser redirect is not possible, it automatically falls back to the device code flow. You'll see a URL and a code to enter on another device to complete authentication. +- **`/mcp auth`**: If a token expires or you need to switch accounts, run `/mcp auth` inside a session. This opens the re-authentication UI for any OAuth-enabled MCP server and supports account switching. You can re-authenticate without restarting the session. - **Microsoft Entra ID (Azure AD)**: MCP servers that authenticate via Microsoft Entra ID are fully supported. Once you complete the initial login, the CLI caches the authentication and **will not show the consent screen on subsequent connections** — you authenticate once per session rather than every time the server reconnects. - **API keys via environment variables**: Pass secrets through the `env` field in the MCP server configuration (see examples above). Never hardcode credentials in `.mcp.json`. - **`${input:variableName}` prompts**: VS Code will prompt for these values at runtime, keeping secrets out of committed files.