Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion website/src/content/docs/learning-hub/automating-with-hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-22
lastUpdated: 2026-03-24
estimatedReadingTime: '8 minutes'
tags:
- hooks
Expand Down Expand Up @@ -99,6 +99,26 @@ Hooks can trigger on several lifecycle events:

> **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.

### sessionStart additionalContext

The `sessionStart` hook supports an `additionalContext` field in its output. When your hook script writes JSON to stdout containing an `additionalContext` key, that text is **injected directly into the conversation** at the start of the session. This lets hooks dynamically provide environment-specific context—such as the current git branch, deployment environment, or team onboarding notes—without requiring the user to paste it manually.

Example hook script that surfaces context:

```bash
#!/usr/bin/env bash
# Output JSON with additionalContext to inject into the session
cat <<EOF
{
"additionalContext": "Current branch: $(git rev-parse --abbrev-ref HEAD). Open tickets: $(gh issue list --limit 3 --json number,title | jq -r '.[] | \"#\(.number) \(.title)\"' | tr '\n' '; ')"
}
EOF
Comment on lines +111 to +115
Copy link

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example sessionStart hook prints JSON that interpolates git branch names and issue titles directly into a JSON string. Since these values can contain quotes, backslashes, or newlines, the output can become invalid JSON and fail to parse. Consider generating the JSON with a proper JSON encoder (e.g., jq -n --arg ...), or otherwise escaping the interpolated values so the example always produces valid JSON.

Suggested change
cat <<EOF
{
"additionalContext": "Current branch: $(git rev-parse --abbrev-ref HEAD). Open tickets: $(gh issue list --limit 3 --json number,title | jq -r '.[] | \"#\(.number) \(.title)\"' | tr '\n' '; ')"
}
EOF
branch="$(git rev-parse --abbrev-ref HEAD)"
issues="$(gh issue list --limit 3 --json number,title \
| jq -r '.[] | "#\(.number) \(.title)"' \
| tr '\n' '; ')"
jq -n --arg branch "$branch" --arg issues "$issues" \
'{additionalContext: ("Current branch: " + $branch + ". Open tickets: " + $issues)}'

Copilot uses AI. Check for mistakes.
```

### Extension Hooks Merging

When multiple IDE extensions (or a mix of extensions and a `hooks.json` file) each define hooks, all hook definitions are **merged** rather than the last one overwriting the others. This means you can layer hooks from different sources—a project's `.github/hooks/` file, an extension you have installed, and a personal settings file—and all of them will fire for the relevant events.

### Cross-Platform Event Name Compatibility

Hook event names can be written in **camelCase** (e.g., `preToolUse`) or **PascalCase** (e.g., `PreToolUse`). Both are accepted, making hook configuration files compatible across GitHub Copilot CLI, VS Code, and Claude Code without modification. Hooks also support Claude Code's nested `matcher`/`hooks` structure alongside the standard flat format.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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-23
lastUpdated: 2026-03-24
estimatedReadingTime: '10 minutes'
tags:
- configuration
Expand Down Expand Up @@ -170,6 +170,43 @@ A well-organized Copilot configuration directory looks like this:
└── api-design.instructions.md
```

### Monorepo Support

In monorepos with multiple packages or services, GitHub Copilot CLI discovers customizations at **every directory level** from your working directory up to the git repository root. This means each package or service can have its own `.github/` folder with specialized agents, instructions, skills, and MCP servers, while still inheriting configuration from parent directories.

```
my-monorepo/
├── .github/
│ └── instructions/
│ └── shared-conventions.instructions.md ← applies everywhere
├── packages/
│ ├── api/
│ │ └── .github/
│ │ └── agents/
│ │ └── api-expert.agent.md ← applies in packages/api/
│ └── web/
│ └── .github/
│ └── instructions/
│ └── react-conventions.instructions.md ← applies in packages/web/
```

When you work inside `packages/api/`, Copilot loads configuration from `packages/api/.github/`, then `packages/.github/` (if it exists), then the root `.github/`. This layered discovery ensures the right context is active no matter where in the repository you're working.

### Personal Skills Directory

In addition to repository-level skills, GitHub Copilot CLI supports a **personal skills directory** at `~/.agents/skills/`. Skills you place here are discovered automatically across all your projects, making them ideal for personal workflows and reusable utilities that are not project-specific.

```
~/.agents/
└── skills/
├── my-review-style/
│ └── SKILL.md ← available in all sessions
└── cleanup-todos/
└── SKILL.md
```

This personal directory aligns with the VS Code GitHub Copilot for Azure extension's default skill discovery path, so skills defined here work consistently across tools.

### Custom Agents

Agents are specialized assistants for specific workflows. Place agent definition files in `.github/agents/`.
Expand Down Expand Up @@ -357,6 +394,25 @@ CLI settings use **camelCase** naming. Key settings added in recent releases:

> **Note**: Older snake_case names (e.g., `include_gitignored`, `auto_updates_channel`) are still accepted for backward compatibility, but camelCase is now the preferred format.

### CLI Session Commands

GitHub Copilot CLI has two commands for managing session state, with distinct behaviours:

| Command | Behaviour |
Comment on lines +399 to +401
Copy link

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spelling is inconsistent with the rest of this article (which uses American English "behavior"). Consider changing "behaviours" to "behaviors" for consistency.

Suggested change
GitHub Copilot CLI has two commands for managing session state, with distinct behaviours:
| Command | Behaviour |
GitHub Copilot CLI has two commands for managing session state, with distinct behaviors:
| Command | Behavior |

Copilot uses AI. Check for mistakes.
|---------|-----------|
| `/new [prompt]` | Starts a fresh conversation while keeping the current session backgrounded. You can switch back to backgrounded sessions. |
| `/clear [prompt]` | Abandons the current session entirely and starts a new one. Backgrounded sessions are not affected. |

Both commands accept an optional prompt argument to seed the new session with an opening message, for example `/new Add error handling to the login flow`.

The `/undo` command reverts the last turn—including any file changes the agent made—letting you course-correct without manually undoing edits:

```
/undo
```

Use `/undo` when the agent's last response went in an unwanted direction and you want to try a different approach from that point.

## Common Questions

**Q: How do I disable Copilot for specific files?**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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-23
lastUpdated: 2026-03-24
estimatedReadingTime: '8 minutes'
tags:
- mcp
Expand Down Expand Up @@ -207,6 +207,15 @@ MCP server SDKs are available in [Python](https://github.com/modelcontextprotoco
- **Test server connectivity**: Verify MCP servers start correctly before relying on them in agent workflows.
- **Use the MCP allowlist (experimental)**: In high-security environments, the `MCP_ALLOWLIST` feature flag lets you validate MCP servers against a configured registry, blocking unrecognized servers from loading. This is an experimental feature for enterprise environments requiring strict control over which MCP servers are permitted.

### Organization Policy for Third-Party MCP Servers

GitHub organizations can enforce a policy that restricts which third-party MCP servers members are permitted to use. When this policy is active:

- Copilot CLI **enforces** the policy for all users in the organization.
- A **warning is shown** if a configured MCP server is blocked by the policy, so you know which servers are restricted before expecting them to work.

If you see a warning that an MCP server is blocked, contact your organization administrator to find out which servers are on the allowlist, or switch to an approved alternative.

## Common Questions

**Q: Do MCP servers run in the cloud?**
Expand Down
Loading