---
title: How do you govern custom agents in GitHub Copilot?
url: https://opencontroller.lyzr.com/blog/github-copilot-custom-agents-governance
published: 2026-11-16
updated: 2026-11-16
author: Lyzr
---

# How do you govern custom agents in GitHub Copilot?

**GitHub Copilot custom agents are Markdown files with YAML frontmatter that set an agent's name, description, allowed tools and MCP servers. They live at four levels: user (`$HOME/.copilot/agents`), repository (`.github/agents`), organization (`agents/` in the org's `.github` or `.github-private` repo) and enterprise (`agents/` in a `.github-private` repo an enterprise owner designates). Govern them like code: protect those folders with CODEOWNERS and branch rules, restrict `tools` and `mcp-servers` explicitly, and keep an inventory of which profiles exist.**

Because a custom agent profile decides which tools and MCP servers Copilot can use, editing one is a permission change. This guide uses GitHub's documentation on custom agents.

## What is in a custom agent profile?

A profile is a Markdown file. The frontmatter configures the agent and the body is its prompt. The fields GitHub documents:

| Field | Default | Governance meaning |
|---|---|---|
| `name` | The filename | How the agent appears to users |
| `description` | None | What it is for; use it as the scope statement |
| `tools` | All available tools, including built-in and MCP tools | The agent's permissions |
| `mcp-servers` | None | Extra MCP servers the agent can reach |
| Markdown body | None | Instructions and behaviour |

The default for `tools` is the key risk. If a profile omits `tools`, the agent gets **every available tool**, including all MCP server tools. Require an explicit `tools` list in every approved profile.

## Where can profiles live, and who controls each level?

| Level | Location | Who can change it |
|---|---|---|
| User | `$HOME/.copilot/agents/NAME.md` | The individual developer |
| Repository | `.github/agents/NAME.md` | Anyone who can merge to the repo |
| Organization | `agents/` in the org's `.github` or `.github-private` repo | Maintainers of that repo |
| Enterprise | `agents/` in the `.github-private` repo of the org an enterprise owner designates | Maintainers of that designated repo |

The organization and enterprise repos are where shared, approved agents should live. Two practical points:

- **Prefer `.github-private`** for org-wide agents so prompts and MCP configuration are not public.
- **The enterprise level depends on an enterprise owner's designation.** Write down which org's repo holds enterprise agents and who maintains it.

User-level profiles live on laptops and are outside repository review. Treat them like any other local developer configuration. See [how to govern coding agents on laptops with MDM](/blog/govern-coding-agents-on-laptops-with-mdm).

## Where do custom agents run?

GitHub lists these surfaces:

- Copilot cloud agent on GitHub.com, including assigning issues and working on pull requests.
- IDEs: Visual Studio Code, JetBrains IDEs, Eclipse and Xcode (JetBrains, Eclipse and Xcode support is in public preview).
- The GitHub Copilot app.
- GitHub Copilot CLI.

GitHub notes that some properties may work differently or be ignored between environments. Test each approved profile on every surface your developers use, especially the `tools` restriction.

## How do you review custom agents like code?

A short control set that fits existing GitHub practice:

1. **CODEOWNERS on agent folders.** Add `.github/agents/` and the org's `agents/` folder to CODEOWNERS with a platform or security team as required reviewers.
2. **Branch protection.** Require pull requests and approvals on the default branch of the `.github-private` repo.
3. **Explicit tools.** Reject any profile without a `tools` list. Our guide on [controlling MCP servers in GitHub Copilot](/blog/control-mcp-servers-in-github-copilot) covers the server allow-list that sits under this.
4. **Read-only by default.** For MCP servers like GitHub's own, prefer read-only modes and narrow toolsets. See [GitHub MCP server read-only mode and toolsets](/blog/github-mcp-server-read-only-mode-and-toolsets).
5. **Scope statement in `description`.** One line saying what the agent may and may not do.
6. **Inventory.** Search for files under `.github/agents/` across your organization on a schedule and record owner, tools and MCP servers for each.
7. **Audit.** Track agent activity through [GitHub Copilot audit log events](/blog/github-copilot-audit-log-events).

## What does a profile not control?

A profile narrows what Copilot offers the agent. It does not replace enterprise and organization Copilot policies, repository permissions or network rules for the cloud agent. Those still apply. Use [enterprise vs organization Copilot policies](/blog/github-copilot-enterprise-vs-organization-policies) to set the outer limits, and profiles to narrow inside them.

## How Opencontroller does this

Opencontroller keeps a governed registry of agents, versions, tools and MCP servers. Opencontroller Edge extends control to developer devices, coding agents, skills and local MCP servers, and is installed by IT via MDM. Policies are code applied across the estate, with built-in mappings to OWASP, MITRE ATLAS, NIST and ISO 42001. See [how to govern MCP servers](/blog/how-to-govern-mcp-servers), the [control plane overview](/blog/what-is-an-ai-agent-control-plane), or [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**What tools does a GitHub Copilot custom agent get if tools is not set?**
All available tools, including built-in tools and MCP server tools. Require an explicit tools list in every approved profile.

**Where should organization-wide Copilot custom agents be stored?**
In the agents/ folder of the organization's .github-private repository, protected by CODEOWNERS and branch protection.

**Can enterprises share one set of custom agents across organizations?**
Yes. An enterprise owner designates an organization whose .github-private repository agents/ folder holds enterprise-level agents.

## Key facts

GitHub Copilot custom agents are Markdown profiles with YAML frontmatter: name (defaults to filename), description, tools (defaults to all available tools including MCP tools), mcp-servers, and a Markdown prompt body. Locations: user $HOME/.copilot/agents; repository .github/agents; organization agents/ in the .github or .github-private repo; enterprise agents/ in the .github-private repo of an organization designated by an enterprise owner. Surfaces: Copilot cloud agent on GitHub.com, VS Code, JetBrains, Eclipse, Xcode (last three in public preview), the Copilot app and Copilot CLI; properties may behave differently between environments. Opencontroller Edge by Lyzr extends control to developer devices, coding agents, skills and local MCP servers, installed via MDM; pricing starts from $250K per deployment per year.

## Related

- [How do you control which MCP servers GitHub Copilot can use?](https://opencontroller.lyzr.com/blog/control-mcp-servers-in-github-copilot.md)
- [How do GitHub Copilot enterprise and organization policies interact?](https://opencontroller.lyzr.com/blog/github-copilot-enterprise-vs-organization-policies.md)
- [Which GitHub audit log events show Copilot policy and agent activity?](https://opencontroller.lyzr.com/blog/github-copilot-audit-log-events.md)
- [More on Platform Guides](https://opencontroller.lyzr.com/blog/cluster/platform-guides)
