` | Merged—repository overrides user for same key | Plugin marketplaces available in this repository. Each entry's `source` is required. An `autoUpdate: true` on an entry is accepted at the repository level but currently ignored—the auto-update opt-in is only honored when set in the user's own settings or in managed (MDM/server) settings. |
| `hooks` | `object` | Merged—repository overrides user for same key | Hook definitions scoped to this repository. See [AUTOTITLE](https://funcoding.ai/agents/github-copilot/how-tos/copilot-cli/customize-copilot/use-hooks/). |
| `includeCoAuthoredBy` | `boolean` | Replaced—repository takes precedence | Add a `Co-authored-by` trailer to commits. |
| `mergeStrategy` | `"rebase"` \| `"merge"` | Replaced—repository takes precedence | Conflict resolution strategy for `/pr fix conflicts`. |
| `model` | `string` | Replaced—repository takes precedence | Pin the default model for this repo. |
| `respectGitignore` | `boolean` | Tighten-only—repository can enable, never disable | Exclude gitignored files from the `@` file mention picker. |
`model`, `effortLevel`, and `contextTier` overrides only apply when the working directory is [trusted](https://funcoding.ai/agents/github-copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools/).
A plugin enabled only through a repository's `enabledPlugins` is scoped to that repository: it auto-installs and activates in the declaring repository, but stays disabled globally, so it never activates in unrelated projects. Leaving the repository, or the repository disabling the plugin, tears down its MCP server and deactivates its agents and skills for the session.
### Repository-level models allowlist (`.github/allowed_models.txt`)
Restrict which built-in models a repository can use with a plain-text allowlist at `.github/allowed_models.txt`, resolved from the current working directory's repository root (or the working directory itself outside a repository).
Each line is a glob pattern matched against model IDs, or a `fallback:` directive naming the model to use when the configured or requested model isn't allowed:
```text
# .github/allowed_models.txt
fallback: gpt-6-astra
gpt-6-astra
gpt-5.4
claude-sonnet-*
```
| Rule | Description |
|------|-------------|
| `*` | Allow all models (default when no file is present). |
| `MODEL-ID` | Allow an exact model ID. |
| `GLOB-PATTERN` | Allow model IDs matching the glob (for example, `claude-sonnet-*`). |
| `fallback: MODEL-ID` | Required exactly once. The model Copilot uses when the active model isn't allowed. |
| `#` | Comment line. |
Negated patterns (`!pattern`) aren't supported, the fallback model must be an exact ID (not a glob), and the fallback model must itself match one of the configured globs. Copilot CLI re-evaluates the policy on `/cd` and rejects an invalid file with an error before running.
The allowlist governs only Copilot's built-in models. It cannot filter out custom models added using the bring your own API keys (BYOK) method. BYOK models remain listed and selectable regardless of the patterns you configure, and the `fallback:` directive never applies to them. For more information, see [AUTOTITLE](https://funcoding.ai/agents/github-copilot/how-tos/administer-copilot/manage-for-enterprise/enable-custom-models/) and [AUTOTITLE](https://funcoding.ai/agents/github-copilot/how-tos/administer-copilot/manage-for-organization/enable-custom-models/).
### Local settings (`.github/copilot/settings.local.json`)
Create `.github/copilot/settings.local.json` in the repository for personal overrides that should not be committed. Add this file to `.gitignore`.
The local configuration file uses the same schema as the repository configuration file (`.github/copilot/settings.json`) and takes precedence over it.
## MDM managed settings
IT administrators can push baseline policy using Mobile Device Management (MDM) managed settings instead of requiring per-user configuration. These settings apply device-level defaults for supported keys and load before user settings.
Managed settings apply uniformly across every session-hosting mode—interactive, `-p`, `--acp`, `--ahp-host`, and `--server`—so enterprise MCP, permission, and plugin policy can't be bypassed by starting a session through a different entry point.
Copilot CLI also loads server-managed settings at startup, in addition to MDM. Device-managed (MDM) and server-managed settings are resolved **per key**: MDM's value wins for any key it sets, and the server's value fills in keys MDM leaves unset. This lets an organization set some policy via MDM (for example, `permissions`) while still receiving other managed defaults (for example, `model`) from the server.
Long-running sessions re-fetch and re-apply managed settings hourly, so policy changes—for example, an organization enabling `permissions.disableBypassPermissionsMode`—take effect without restarting the session.
### MDM managed settings sources
Copilot CLI reads managed settings from platform-specific MDM or file-based locations.
| Platform | Source type | Location |
|----------|-------------|---------|
| macOS | MDM plist | `com.github.copilot` |
| macOS | File | `/Library/Application Support/GitHubCopilot/managed-settings.json` |
| Windows | MDM registry | `HKLM\SOFTWARE\Policies\GitHubCopilot` |
| Windows | File | `%ProgramFiles%\GitHubCopilot\managed-settings.json` |
| Linux | File | `/etc/github-copilot/managed-settings.json` |
On POSIX systems, Copilot CLI rejects file-based managed settings that are symlinks, not owned by root, or world-writable.
### File format
Write file-based managed settings as JSON.
```json
{
"model": "auto",
"permissions": {
"disableBypassPermissionsMode": "disable"
}
}
```
`model` is a top-level key. Older configurations that nested it as `permissions.model` still work—the runtime falls back to that location when the top-level `model` key is absent—but write new configurations with `model` at the top level.
### Supported keys
Only the following keys are supported in MDM managed settings.
| Key | Description |
|-----|-------------|
| `allowedMcpServers` | Allowlist of MCP servers users may load, matched by `serverUrl`, `serverCommand`, or `serverName`. Trusted first-party servers (for example, the built-in GitHub MCP server) are always exempt. Leaving this key unset allows all non-default servers; an empty array denies all of them. See [Managed MCP server allow/deny list](#managed-mcp-server-allowdeny-list). |
| `autoTier` | Set a default Auto routing tier (`"efficiency"`, `"balance"`, or `"intelligence"`) for sessions with `model` set to `auto`. A bare string strictly locks the tier, overriding user and repository settings and hiding it from `/settings`. Use `{"overridable": "TIER"}` instead to set an organization default that users and repositories may still override. `"fast"` is no longer selectable and falls back to `"balance"` with a warning. |
| `deniedMcpServers` | Denylist of MCP servers that must never load, matched the same way as `allowedMcpServers`. A matching non-default server is blocked regardless of the allowlist—deny always wins. See [Managed MCP server allow/deny list](#managed-mcp-server-allowdeny-list). |
| `enabledPlugins` | Enable or disable specific plugins |
| `extraKnownMarketplaces` | Add trusted plugin marketplaces |
| `forceLoginOrgs` | Pin sign-in to an approved set of GitHub organizations (an array of organization logins, matched case-insensitively). Copilot only runs for an account belonging to at least one listed organization; a personal account, an account that belongs only to some other enterprise, or BYOK/API-key authentication is refused with an actionable error. Set an empty array to turn the pin off without deleting the key. Deploy this key through the device channel (MDM plist/registry, or `managed-settings.json`) since it must be able to redirect a developer's first sign-in—the server-managed channel only reaches accounts that have already authenticated into the organization. This key fails closed: an unusable value, or a managed policy that can't be read on a known-managed device, blocks all sign-in until fixed. |
| `forceRemoteSettingsRefresh` | Require a fresh server-managed settings fetch on startup, even when a fresh cached policy exists. The cached entry is still kept as a fallback if the fetch fails. The device (MDM) value takes precedence over a cached server value. |
| `model` | Set a default model for all users (overridden by the `--model` flag or a resumed-session model). `effortLevel` and `contextTier` set alongside `model` apply the same managed reasoning effort and context tier as the corresponding [repository settings](#repository-settings-githubcopilotsettingsjson) keys, but only when the managed model supports explicit effort/context options. |
| `permissions` | Set managed permissions, including `disableBypassPermissionsMode`, `deny` / `ask` / `allow` rule arrays, and the `limitTo` domain boundary array. See [Managed permission rules](#managed-permission-rules) and [Domain boundary (`limitTo`)](#domain-boundary-limitto). |
| `policyHelper` | Register an executable that supplies the lowest-priority managed-settings layer. Fields: `path` (required), plus optional `args`, `timeoutMs`, and `refreshIntervalMs`. If both a device (MDM) and a server policy register a `policyHelper`, the device registration wins. |
| `remoteControl` | Control whether sessions on this device can be controlled from other devices. `mode` is `"enabled"`, `"disabled"`, or `"requireSSO"` (requires `githubDotComOrganizations` when set). |
| `sandbox` | Set a sandbox policy floor that users cannot relax. Supported settings include `enabled`, `failIfUnavailable`, `allowBypass`, `addCurrentWorkingDirectory`, `sandboxMcpServers`, `sandboxLspServers`, `auth.git`, `auth.gh`, `allowDevToolAccess`, `learningMode`, and the `userPolicy.*` filesystem and network rules. The managed value always takes precedence over a user's own value in the safer direction. Turning the sandbox on, requiring it to succeed, and sandboxing MCP and LSP servers cannot be turned off. Disabling bypass or credential injection cannot be re-enabled. Filesystem allow lists can only be narrowed, and denied paths can only be added to. `failIfUnavailable` can only be set by an administrator and blocks the session when the sandbox cannot be established. For the settings users can set themselves, see [User settings](#user-settings-copilotsettingsjson) or run `copilot help sandbox`. |
| `shellShortcut` | Force-enable or force-disable the `$` interactive shell shortcut for all users. A managed value always overrides the user's own `shellShortcut` setting. |
| `strictKnownMarketplaces` | Restrict plugins to an allowlist of known marketplaces (a JSON array of marketplace specs). The allowlist also governs built-in marketplaces once set—an empty array (`[]`) hides and blocks every marketplace, including built-ins, not just user- or repository-added ones. |
| `telemetry` | Push baseline OpenTelemetry export configuration: `enabled`, `endpoint`, `protocol`, `headers`, `resourceAttributes`, `captureContent`, `lockCaptureContent`, and `serviceName`. See [AUTOTITLE](https://funcoding.ai/agents/github-copilot/reference/copilot-cli-reference/cli-command-reference/#opentelemetry-monitoring). |
* `policyHelper.path` accepts an absolute path, a home-relative path (`~/...`), or a bare program name resolved from `PATH`. Other relative forms are rejected. The registration is accepted and validated, but the runtime doesn't yet invoke the helper—helper execution ships in a future release.
* When `remoteControl.mode` is `"requireSSO"`, list the allowed organizations in `remoteControl.githubDotComOrganizations`. The client must be SSO-authorized for at least one listed GitHub.com organization—it no longer needs to be authorized for all of them.
* Set `permissions.disableBypassPermissionsMode` to `"disable"` in MDM managed settings to enforce the restriction at the device level. Account switches cannot override this policy. Set it to `"allow-auto-only"` to block full allow-all escalation while still permitting `/permissions assisted` (LLM-assisted permission approval). If an unrecognized value is set, the CLI logs the issue and enforces `"disable"` as a fail-closed default, so a malformed managed policy still restricts the allow-all options instead of silently allowing them. See [AUTOTITLE](https://funcoding.ai/agents/github-copilot/reference/copilot-cli-reference/cli-command-reference/#restricting-the---allow-all-options).
* Most managed keys lock the entire row: a local edit is silently overridden by the managed value on the next load. `enabledPlugins` and `extraKnownMarketplaces` are the exception—the managed layer merges these maps with your own entries field-by-field instead of replacing them outright. This means the lock applies **per entry**, not to the whole key: a plugin or marketplace pinned by a managed policy can't be re-enabled, disabled, or repointed locally, but other entries in the same map remain fully user-controlled.
* `sandbox.learningMode` is Windows-only and can only be set through native MDM (for example, through Intune or the registry)—a `managed-settings.json` file value is ignored. On a host with denial capture, set it to `"allow"` to start sandboxed shell commands in record-and-allow mode instead of the default record-and-deny mode, recording each filesystem or process access and allowing it rather than refusing it (network policy is still enforced). This lets an administrator observe what a cohort's commands need before locking them down; it is not a containment mode. The status line shows `sandbox relaxed` and shell calls show `(sandbox relaxed)` while it applies. A `deny` value (the default), or removing the key, returns the cohort to the ordinary enforced sandbox, and `deny` from any managed channel always wins over `allow`. User settings and SDK hosts cannot set this key.
### Managed permission rules
Add `deny`, `ask`, and `allow` rule lists under the managed `permissions` key to enforce a permission policy for everyone. This works whether or not `permissions.disableBypassPermissionsMode` is set.
```json
{
"permissions": {
"deny": ["Shell(rm -rf *)", "Domain(*.evil.example)"],
"ask": ["Shell(git push *)"],
"allow": ["Read(**)"]
}
}
```
| Rule family | Matches |
|-------------|---------|
| `Bash(...)`, `Shell(...)` | Shell commands. Use ` *` (for example, `git push *`) to match a command prefix; otherwise the rule matches exact text. |
| `PowerShell(...)` | PowerShell commands, matched the same way as `Shell(...)`. |
| `Read(...)` | File read/view paths. Supports glob patterns: `/` for the workspace root, `~/` for the home directory, and `./` for the current working directory. |
| `Edit(...)`, `Write(...)` | File write/edit paths, matched the same way as `Read(...)`. |
| `Domain(...)` | URL hostnames, matched like [URL rules](https://funcoding.ai/agents/github-copilot/reference/copilot-cli-reference/cli-command-reference/#tool-permission-patterns). |
Rules are combined across managed sources with a fixed precedence: deny always wins, then ask, then allow—matching a `deny` rule blocks the request even if an `allow` rule also matches. `deny` and `ask` are unioned across every managed source (server, MDM). `allow` requires every source that declares an `allow` list to admit the operation—an intersection, not a union. When any of `deny`, `ask`, or `allow` is set, an operation that matches none of them defaults to `ask` rather than falling through silently.
`Edit(...)` and `Write(...)` rules apply to more than the built-in file tools. They also cover files written directly by a shell command. Copilot CLI recognizes a fixed set of these writes. It covers Bash output redirections (`>`, `>>`, `>|`, `&>`, `&>>`), PowerShell output redirections (`>`, `>>`, `*>`, `*>>`), and a small set of in-place `sed` edits (`sed -i` or `--in-place`, and the BSD forms `-i ''` and `-I ''`). When Copilot CLI can work out the target file from the command, a matching `deny` rule blocks the write and a matching `ask` rule prompts you first. This applies even when a broad rule like `Shell(*)` would otherwise allow the command. Sometimes the target file cannot be worked out ahead of time, for example when the path comes from a variable. In that case these path rules do not apply, and the command is checked by the normal shell command rules instead.
### Domain boundary (`limitTo`)
Add a `limitTo` array alongside `deny`, `ask`, and `allow` under the managed `permissions` key to enforce a closed-world domain allowlist:
```json
{
"permissions": {
"limitTo": ["github.com", "*.github.com"]
}
}
```
Only `Domain(...)` entries are supported in `limitTo`. Any agent network request to a domain outside the list is denied without prompting, and user rules, saved approvals, and allow-all modes can't widen it. URLs detected in shell requests are treated as `Domain` requests and must also satisfy the boundary. `limitTo` doesn't restrict `shell`, `read`, or `write` operations by themselves.
An empty `limitTo` list denies every domain request. An invalid list, or an invalid entry, is enforced as an empty list (and reported as a configuration error) rather than discarding the rest of the managed policy.
`deny` still takes precedence over `limitTo`. `ask` and `allow` only refine requests that are already inside the boundary. Like `allow`, `limitTo` is an intersection across managed sources—every managed source that declares a `limitTo` list must admit the request.
## Managed MCP server allow/deny list
Administrators can govern MCP servers directly through MDM managed settings, independent of the [enterprise MCP allowlist](https://funcoding.ai/agents/github-copilot/reference/copilot-cli-reference/cli-command-reference/#enterprise-mcp-allowlist).
Set `allowedMcpServers` and/or `deniedMcpServers` in a managed settings source:
```json
{
"allowedMcpServers": [
{ "serverUrl": "https://mcp.example.com/*" },
{ "serverCommand": ["npx", "-y", "@example/mcp-server"] }
],
"deniedMcpServers": [
{ "serverName": "untrusted-server" }
]
}
```
Each entry identifies a server by exactly one of the following matchers.
| Matcher | Matches | Notes |
|---------|---------|-------|
| `serverUrl` | A remote (HTTP/SSE) server by URL | Supports `*` wildcards; scheme and host match case-insensitively, path case-sensitively. `${VAR}` references expand before matching. |
| `serverCommand` | A stdio server by its exact command and arguments, in order | `${VAR}` references expand before matching. |
| `serverName` | A server by its assigned label | Allowlist entries are restricted to `[A-Za-z0-9_-]+` (no wildcards); denylist entries accept any non-empty string. |
Rules:
* **Trusted first-party servers** (for example, the built-in GitHub MCP server) are always exempt from both lists.
* **Unset `allowedMcpServers`** allows all non-default servers; an **empty array** blocks all of them (deny-all).
* **Unset or empty `deniedMcpServers`** blocks nothing.
* **Deny always wins**—a server matching `deniedMcpServers` is blocked even if it also matches `allowedMcpServers`.
* For remote servers, a match must come from a `serverUrl` entry; `serverName` only counts when no `serverUrl` entries exist. For stdio servers, a match must come from a `serverCommand` entry; `serverName` only counts when no `serverCommand` entries exist.
## Further reading
* [AUTOTITLE](https://docs.github.com/copilot/how-tos/copilot-cli)
* [AUTOTITLE](https://funcoding.ai/agents/github-copilot/reference/copilot-cli-reference/cli-command-reference/)
* [AUTOTITLE](https://funcoding.ai/agents/github-copilot/reference/copilot-cli-reference/cli-programmatic-reference/)
* [AUTOTITLE](https://funcoding.ai/agents/github-copilot/reference/copilot-cli-reference/cli-plugin-reference/)
* [AUTOTITLE](https://funcoding.ai/agents/github-copilot/reference/hooks-reference/)