GitHub Copilot
PlatformGitHub
The GitHub Copilot cloud agent (formerly coding agent) on github.com — an autonomous agent that works on issues and pull requests in an ephemeral Actions-powered environment, configured via repository files and repository settings.
MCP
SupportedRepository administrators configure MCP servers as JSON (mcpServers key) in the repository settings on github.com (Settings > Copilot > MCP servers). The config is shared by the cloud agent and Copilot code review; secrets are injected via COPILOT_MCP_-prefixed Agents secrets.
Fields
| Field | Type | Description |
|---|---|---|
type* | "local" | "stdio" | "http" | "sse" | Server transport. local and stdio are equivalent (local process); http and sse are remote. |
tools* | string[] | Allowlist of tools to enable from the server; use ["*"] for all tools. |
command | string | Command to start a local server (required for local/stdio). |
args | string[] | Arguments passed to the command (required for local/stdio). |
env | record<string, string> | Environment variables for a local server; values may reference COPILOT_MCP_-prefixed secrets/variables. |
url | string | The MCP server's URL (required for http/sse). |
headers | record<string, string> | Headers attached to requests to a remote server; values may reference COPILOT_MCP_-prefixed secrets/variables. |
Capabilities
Examples
{
"mcpServers": {
"sentry": {
"type": "local",
"command": "npx",
"args": ["@sentry/mcp-server@latest", "--host=$SENTRY_HOST"],
"env": {
"SENTRY_HOST": "https://contoso.sentry.io",
"SENTRY_ACCESS_TOKEN": "$COPILOT_MCP_SENTRY_ACCESS_TOKEN"
},
"tools": ["*"]
}
}
}{
"mcpServers": {
"cloudflare": {
"type": "sse",
"url": "https://docs.mcp.cloudflare.com/sse",
"tools": ["*"]
}
}
}- •The JSON configuration is entered directly in repository settings on github.com, not stored as a repo file.
- •The GitHub MCP server and Playwright MCP server are enabled by default; the built-in GitHub server uses a read-only token scoped to the current repository.
- •Only MCP tools are supported; resources and prompts are not. Remote servers using OAuth are not supported.
- •Configured tools run autonomously without per-call approval — allowlist specific read-only tools where possible.
- •env and headers values reference Agents secrets/variables prefixed with COPILOT_MCP_ using $VAR, ${VAR}, or ${VAR:-default} substitution.
- •Servers needing extra dependencies can install them via .github/workflows/copilot-setup-steps.yml.
- •Org/enterprise admins can also attach MCP servers to custom agents via the mcp-servers frontmatter property.
Skills
SupportedSKILL.md Agent Skills (open standard) stored in the repository; loaded automatically when relevant to the cloud agent's task and also used by Copilot code review.
Config files
| Path | Scope | Format | Key |
|---|---|---|---|
.github/skills/<name>/SKILL.md | Project | markdown | — |
.claude/skills/<name>/SKILL.mdClaude-compatible project location. | Project | markdown | — |
.agents/skills/<name>/SKILL.mdCross-agent project location. | Project | markdown | — |
Fields
| Field | Type | Description |
|---|---|---|
name* | string | Unique identifier: lowercase, hyphens for spaces, typically matching the skill directory name. |
description* | string | What the skill does and when Copilot should use it. |
license | string | License that applies to this skill. |
Examples
---
name: github-actions-failure-debugging
description: Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows.
---
1. Use the `list_workflow_runs` tool to look up recent workflow runs and their status
2. Use the `summarize_job_log_failures` tool to get an AI summary of failed job logs
3. Try to reproduce the failure and fix the failing build before committing- •The cloud agent runs in an ephemeral sandbox, so only project skills committed to the repository apply; personal skills (~/.copilot/skills, ~/.agents/skills) apply to local surfaces like Copilot CLI and VS Code.
- •Skills in .github/skills are also used automatically by Copilot code review when relevant (public preview).
- •Skills can bundle scripts and other resources referenced from SKILL.md.
- •Discover and install shared skills with gh skill in GitHub CLI or from the Awesome GitHub Copilot collection.
Rules
SupportedRepository custom instructions: repo-wide .github/copilot-instructions.md, path-specific .github/instructions/*.instructions.md with applyTo globs, and AGENTS.md files anywhere in the repo (nearest file wins).
Config files
| Path | Scope | Format | Key |
|---|---|---|---|
.github/copilot-instructions.mdRepository-wide instructions applied to all Copilot requests in the repo. | Project | markdown | — |
.github/instructions/**/*.instructions.mdPath-specific instructions with applyTo frontmatter; subdirectories allowed. | Project | markdown | — |
AGENTS.mdCan be stored anywhere in the repository; the nearest AGENTS.md in the directory tree takes precedence. | Project | markdown | — |
CLAUDE.mdAlternative single agent-instructions file in the repo root (GEMINI.md also accepted). | Project | markdown | — |
Fields
| Field | Type | Description |
|---|---|---|
applyTo* | string | Glob pattern(s), comma-separated, selecting the files the instructions apply to (path-specific files only). Example: "**/*.ts,**/*.tsx". |
excludeAgent | string | Exclude the file from one agent. Omit to apply to both the cloud agent and code review. |
Examples
---
applyTo: "app/models/**/*.rb"
excludeAgent: "code-review"
---
Use ActiveRecord validations for all model constraints.
Prefer scopes over class methods for query logic.- •Path-specific instructions on GitHub.com are supported for the cloud agent and Copilot code review.
- •The excludeAgent frontmatter key ('cloud-agent' or 'code-review') limits a path-specific file to one of the two agents.
- •A single CLAUDE.md or GEMINI.md in the repository root can be used instead of AGENTS.md.
- •Organization-level custom instructions can be defined on GitHub and apply across repositories (enterprise/org scope, configured in the org UI rather than a repo file).
- •Priority: personal instructions > repository instructions > organization instructions; all applicable sets are provided to Copilot.
- •The cloud agent can generate a copilot-instructions.md for you (onboarding prompt at github.com/copilot/agents).
- •For code review, Copilot uses the instructions in the base branch of the pull request.
Hooks
SupportedThe cloud agent runs .github/hooks/*.json hooks inside its ephemeral Linux sandbox. A subset of events fires; only bash (or the cross-platform command) entries are honored, and HTTP hooks must target firewall-allowed hosts.
Config files
| Path | Scope | Format | Key |
|---|---|---|---|
.github/hooks/*.json | Project | json | hooks |
Fields
| Field | Type | Description |
|---|---|---|
type | "command" | "http" | Hook handler type. Defaults to command. Prompt hooks may not fire because cloud agent jobs are non-interactive. |
bash | string | Shell command for the Linux sandbox. powershell entries are ignored under the cloud agent. |
command | string | Cross-platform fallback command, honored when bash is absent. |
cwd | string | Working directory. The sandbox workspace is /workspace when a repository is cloned. |
env | record<string, string> | Environment variables to set (supports variable expansion). |
timeoutSec | number | Timeout in seconds. Default 30. timeout is accepted as an alias. |
matcher | string | Optional regex (anchored ^(?:PATTERN)$) filtering by tool name (preToolUse/postToolUse), agent name (subagentStart), or trigger (preCompact). |
url | string | Target URL for http hooks; must be https and reachable through the cloud agent firewall. |
Examples
{
"version": 1,
"hooks": {
"preToolUse": [
{
"type": "command",
"matcher": "bash",
"bash": "./scripts/block-dangerous.sh",
"timeoutSec": 10
}
]
}
}- •Same JSON format ({ "version": 1, "hooks": { ... } }) as Copilot CLI; event names in camelCase, or PascalCase for the VS Code-compatible snake_case payloads.
- •In cloud agent jobs, only .github/hooks/*.json in the cloned repository is loaded — no user-level files, settings.json, or plugins exist in the sandbox.
- •notification and permissionRequest hooks do not apply (tool calls are pre-approved); a preToolUse decision of 'ask' is treated as 'deny'.
- •preCompact fires only with trigger 'auto'; sessionStart fires once per job as a new session.
- •The sandbox filesystem is ephemeral — persist hook output via an http hook to an admin-allowlisted host.
- •preToolUse command hooks are fail-closed: crashes, timeouts, and non-zero exits (other than 2) deny the tool call.
- •Set disableAllHooks: true at the top level of a hook file to skip its hooks without deleting it.
Commands
Not supportedPrompt files (.github/prompts/*.prompt.md) are not supported on GitHub.com; GitHub's customization cheat sheet marks prompt files as unsupported for the GitHub.com surface.
- •For reusable on-demand workflows with the cloud agent, use Agent Skills (.github/skills) or custom agents (.github/agents/*.md) instead.
Settings
SupportedThe cloud agent's environment is configured with a .github/workflows/copilot-setup-steps.yml Actions workflow (preinstall dependencies, choose runners) plus .github/copilot/settings.json for plugins. Remaining configuration (MCP, firewall, secrets, code review toggles) lives in repository settings on github.com.
Config files
| Path | Scope | Format | Key |
|---|---|---|---|
.github/workflows/copilot-setup-steps.ymlStandard GitHub Actions workflow syntax; runs as a normal workflow when changed so it can be validated. | Project | yaml | jobs.copilot-setup-steps |
.github/copilot/settings.jsonShared repository configuration; the cloud agent reads the plugin-related keys (enabledPlugins, extraKnownMarketplaces) and hooks-related keys. | Project | json | — |
Fields
| Field | Type | Description |
|---|---|---|
steps | step[] | Actions steps executed before the agent starts (checkout, toolchain setup, dependency install). A failing step skips the rest and the agent starts anyway. |
permissions | object | Workflow token permissions for the setup job (use least privilege; contents: read to clone). Copilot gets its own token for its work. |
runs-on | string | string[] | Runner selection: standard, larger GitHub-hosted, or self-hosted runner labels/groups. Ubuntu x64 and Windows only. |
services | object | Service containers available during the job. |
timeout-minutes | number | Setup job timeout. Maximum value 59. |
Examples
name: "Copilot Setup Steps"
on:
workflow_dispatch:
push:
paths: [.github/workflows/copilot-setup-steps.yml]
jobs:
copilot-setup-steps:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Checkout code
uses: actions/checkout@v6
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: Install JavaScript dependencies
run: npm ci- •copilot-setup-steps.yml must contain a single job named copilot-setup-steps and be present on the default branch to take effect; it runs before the agent starts work.
- •Only steps, permissions, runs-on, services, snapshot, and timeout-minutes (max 59) can be customized on the job; other job settings are ignored.
- •Supports larger GitHub-hosted runners, self-hosted runners (Ubuntu x64 or Windows only), Windows environments, and Git LFS via actions/checkout with lfs: true.
- •Agents secrets and variables (e.g. COPILOT_MCP_* for MCP servers) are configured in repository or organization settings on github.com.
- •The integrated firewall can be customized or disabled in repository settings; it must be disabled for self-hosted runners.
- •The enabledPlugins and extraKnownMarketplaces keys of .github/copilot/settings.json are read by both the cloud agent and Copilot CLI.