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 1a688226b..c4c323cc4 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-02-26 +lastUpdated: 2026-03-21 estimatedReadingTime: '8 minutes' tags: - hooks @@ -93,11 +93,29 @@ Hooks can trigger on several lifecycle events: | `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 | | `agentStop` | Main agent finishes responding to a prompt | Run final linters/formatters, validate complete changes | +| `subagentStart` | A subagent is spawned by the main agent | Inject additional context into the subagent's prompt, log subagent creation | | `subagentStop` | A subagent completes before returning results | Audit subagent outputs, log subagent activity | | `errorOccurred` | An error occurs during agent execution | Log errors for debugging, send notifications, track error patterns | > **Key insight**: The `preToolUse` hook is the most powerful — it can **approve or deny** individual tool executions. This enables fine-grained security policies like blocking specific shell commands or requiring approval for sensitive file operations. +### Cross-Platform Event Names + +Hook event names support both `camelCase` and `PascalCase` — for example, both `postToolUse` and `PostToolUse` are valid. This ensures the same `hooks.json` file works without modification across GitHub Copilot CLI, VS Code, and Claude Code. + +### Where to Define Hooks + +Hooks can be defined in several locations, loaded in this order: + +| Location | Scope | Example | +|----------|-------|---------| +| `.github/hooks/*.json` | Repository (shared via version control) | `.github/hooks/linting.json` | +| `settings.json` | User or workspace settings | `~/.copilot/settings.json` | +| `settings.local.json` | Local overrides (not version-controlled) | `.github/settings.local.json` | +| `config.json` | Legacy config format | `~/.copilot/config.json` | + +For most teams, `.github/hooks/` is the right place — configuration is version-controlled and shared automatically. Use `settings.local.json` for hooks that should only run on your machine (e.g., personal notification scripts). + ### Event Configuration Each hook entry supports these fields: @@ -327,7 +345,7 @@ echo "Pre-commit checks passed ✅" **Q: Where do I put hooks configuration files?** -A: Place them in the `.github/hooks/` directory in your repository (e.g., `.github/hooks/my-hook.json`). You can have multiple hook files — all are loaded automatically. This makes hooks available to all team members. +A: The primary location is `.github/hooks/` in your repository (e.g., `.github/hooks/my-hook.json`). All JSON files in that directory are loaded automatically, making hooks available to every team member. You can also define hooks in `settings.json`, `settings.local.json`, or `config.json` for user-scoped or local-only hooks. See the "Where to Define Hooks" table above for details. **Q: Can hooks access the user's prompt text?** 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 f6eb65df9..1d977dbea 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: 2025-11-28 +lastUpdated: 2026-03-21 estimatedReadingTime: '10 minutes' tags: - configuration @@ -147,6 +147,29 @@ Prevent Copilot from accessing specific files or directories. **Why it matters**: Exclude sensitive files, generated code, or dependencies from Copilot's context to improve suggestion relevance and protect confidential information. +### File Search and Gitignore + +By default, Copilot's `@` file search omits files listed in `.gitignore`. You can opt in to include them using the `includeGitignored` config option in GitHub Copilot CLI: + +```json +{ + "includeGitignored": true +} +``` + +**Why it matters**: Useful in monorepos or projects where generated or gitignored files (e.g., compiled outputs, build artifacts) contain important context that Copilot should be able to reference. + +### Config Settings: camelCase Names (CLI) + +In GitHub Copilot CLI, config settings use **camelCase** names. Older snake_case names still work for backward compatibility, but camelCase is the preferred form going forward: + +| Old Name (still works) | New Preferred Name | +|------------------------|-------------------| +| `include_co_authored_by` | `includeCoAuthoredBy` | +| `effort_level` | `effortLevel` | +| `auto_updates_channel` | `autoUpdatesChannel` | +| `status_line` | `statusLine` | + ## Repository-Level Configuration The `.github/` directory in your repository enables team-wide customizations that are version-controlled and shared across all contributors. @@ -335,15 +358,27 @@ Settings: File → Settings → Tools → GitHub Copilot ### GitHub Copilot CLI -Configuration file: `~/.copilot-cli/config.json` +GitHub Copilot CLI stores configuration in `~/.copilot/settings.json`. Key CLI-specific settings: ```json { - "editor": "vim", - "suggestions": true + "effortLevel": "medium", + "includeCoAuthoredBy": true, + "autoUpdatesChannel": "stable", + "statusLine": true } ``` +> **Note**: Config setting names use camelCase (e.g., `effortLevel`). Older snake_case names (e.g., `effort_level`) still work for backward compatibility but camelCase is the preferred form going forward. + +**Useful CLI commands for session management**: + +| Command | What It Does | +|---------|-------------| +| `/undo` | Undo the last turn and revert all file changes made in that turn | +| `--effort` | Shorthand alias for `--reasoning-effort` (set the reasoning budget) | +| `--resume` | Resume a previous session by session ID or task ID | + ## Common Questions **Q: How do I disable Copilot for specific files?** diff --git a/website/src/content/docs/learning-hub/installing-and-using-plugins.md b/website/src/content/docs/learning-hub/installing-and-using-plugins.md index 28bc87955..6bf9855ae 100644 --- a/website/src/content/docs/learning-hub/installing-and-using-plugins.md +++ b/website/src/content/docs/learning-hub/installing-and-using-plugins.md @@ -3,7 +3,7 @@ title: 'Installing and Using Plugins' description: 'Learn how to find, install, and manage plugins that extend GitHub Copilot CLI with reusable agents, skills, hooks, and integrations.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-02-26 +lastUpdated: 2026-03-21 estimatedReadingTime: '8 minutes' tags: - plugins @@ -177,6 +177,8 @@ copilot plugin update my-plugin copilot plugin uninstall my-plugin ``` +`/plugin list` in an interactive session organizes plugins into sections: marketplace-installed plugins are listed by marketplace, and plugins loaded via `--plugin-dir` appear under a separate **External Plugins** section. + ### Where Plugins Are Stored - **Marketplace plugins**: `~/.copilot/installed-plugins/MARKETPLACE/PLUGIN-NAME/` 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 482b9181d..6ab7a7ec0 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-02-26 +lastUpdated: 2026-03-21 estimatedReadingTime: '8 minutes' tags: - mcp @@ -61,7 +61,15 @@ GitHub Copilot provides several **built-in tools** that are always available: ## Configuring MCP Servers -MCP servers are configured per-workspace in `.vscode/mcp.json`: +MCP servers are configured per-workspace. GitHub Copilot CLI looks for server definitions in the following files (all are supported): + +- `.vscode/mcp.json` — VS Code workspace configuration +- `.mcp.json` — project-root configuration (portable across editors) +- `devcontainer.json` — Dev Container configuration + +> **Note**: Workspace MCP servers from all three locations are loaded only after folder trust is confirmed. + +A typical `.vscode/mcp.json` or `.mcp.json` looks like this: ```json { @@ -193,8 +201,9 @@ MCP server SDKs are available in [Python](https://github.com/modelcontextprotoco - **Principle of least privilege**: Only give MCP servers the minimum access they need. Use read-only database connections for analysis agents. - **Keep secrets out of config files**: Use `${input:variableName}` for API keys and connection strings, or load from environment variables. - **Document your servers**: Add comments or a README explaining which MCP servers your project uses and why. -- **Version control carefully**: Commit `.vscode/mcp.json` for shared server configurations, but use `.gitignore` for any files containing credentials. +- **Version control carefully**: Commit `.vscode/mcp.json` or `.mcp.json` for shared server configurations, but use `.gitignore` for any files containing credentials. - **Test server connectivity**: Verify MCP servers start correctly before relying on them in agent workflows. +- **Validate against a registry (experimental)**: Use the `MCP_ALLOWLIST` feature flag to validate MCP servers against configured registries before loading them. This is useful in enterprise environments where only approved servers should run. Enable it via the `experimentalFeatures` config or the `MCP_ALLOWLIST` environment variable. ## Common Questions