Configuring enterprise-managed settings

With enterprise managed settings, enterprise owners can centrally define and distribute configuration settings to supported clients for users on your enterprise's Copilot plan, ensuring every member works within the guardrails you define, while letting teams tailor the settings you allow.

The following clients are supported, although not every client supports every property:

Copilot CLI
VS Code
The GitHub Copilot app
Copilot cloud agent

These settings apply enterprise-wide and enterprises can customize specific keys to enterprise teams. For most supported keys, the managed-settings.json value takes precedence over any file-based configuration a user sets in their client. In Copilot CLI, managed sandbox settings instead define minimum restrictions that users can further tighten but cannot loosen.

MDM-managed and file-based settings are loaded from the device, so they can apply before sign in or a server round trip and remain active when users switch accounts. Server-managed settings are associated with the user's signed-in account.

Defining settings

For detailed information on the available properties and syntax, see Enterprise managed settings.

Use copilot/team-mappings.json and the copilot/teams/ directory when you need one or more enterprise teams to use settings that differ from the defaults in copilot/managed-settings.json. For more information, see Configuring enterprise-managed settings.

Choosing a deployment method

There are multiple ways to deploy enterprise managed settings. Use the following guidelines to choose the right method for you. For any method, pilot on a small device group before broad deployment.

Server-managed: Default for most enterprises and best for review workflows and audit history. Applies to all clients, including Copilot cloud agent.
MDM-managed: Best when IT teams need device-group targeting through existing MDM tooling on macOS and Windows. Local clients only.
File-based: Available on all platforms, and useful when server-managed and MDM-managed deployment are not available, including developer environments such as containers and Codespaces. Local clients only.

In Copilot CLI, if a request for server-managed settings fails and no cached response is available, the server-managed policy is unavailable for that session. For restrictions that must remain available without a server response, use MDM-managed or file-based settings.

There are additional considerations if you use a dedicated enterprise for Copilot Business. See Guidance for dedicated Copilot Business enterprises.

Deploying server-managed settings

Create and configure your .github-private repository. See Creating a .github-private repository.
In the repository, create or update copilot/managed-settings.json.
Add your enterprise policy keys and values in JSON format.
Commit and push your changes to the default branch.
Confirm that enterprise users are running a supported client. Updated settings are applied automatically within about an hour. Restarting the client or signing in again triggers an immediate refresh.

Overriding settings for specific teams

For server-managed deployments, use copilot/team-mappings.json and the copilot/teams/ directory when one or more enterprise teams should use settings that differ from your default copilot/managed-settings.json values. enabledPlugins and extraKnownMarketplaces work additively. The enterprise managed-settings.json sets a baseline, and an enterprise team file can add more plugins and marketplaces on top of it.

In your enterprise's copilot/managed-settings.json file, mark each key you want to make eligible for override using the { "overridable": <VALUE> } syntax. The json files you map to teams can only send different values for keys you mark overridable. An overridable value you provide in managed-settings.json is the default when teams files do not declare a different value for a given key. For example, to defer both model and disableBypassPermissionsMode:
```
{
  "model": { "overridable": "auto" },
  "permissions": {
    "disableBypassPermissionsMode": { "overridable": "disable" }
  }
}
```
In your enterprise's .github-private repository, create copilot/team-mappings.json. Map each team settings file to one or more enterprise team slugs. The key is the settings file name and the value is an array of team slugs, so you can apply one file across multiple teams.
```
{
  "devs.json": ["developers-all", "finops-dev"],
  "ai-users.json": ["ai-baseline-trained"],
  "frontier.json": ["ai-pioneers"]
}
```
Create the team settings file under copilot/teams/. Include only the keys you marked as overridable. Every other key stays governed by your enterprise default.
```
{
  "model": "unmanaged",
  "permissions": {
    "disableBypassPermissionsMode": "unmanaged"
  }
}
```
Commit and push your changes to the default branch.

GitHub evaluates enterprise team membership and applies matching settings for each person. If a user belongs to multiple teams, their team files are combined using the least restrictive value for each key, then applied beneath the enterprise settings, where platform decisions always win.

Deploying MDM-managed settings

Native MDM delivery uses the same logical keys and values as server-managed settings, but it does not deploy a managed-settings.json file. Instead, your MDM platform deploys individual settings as operating-system-managed string values.

Native MDM delivery is available on Windows and macOS:

Operating system	Native policy location
Windows	String (`REG_SZ`) values under `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\GitHubCopilot`
macOS	String values in forced managed preferences for the `com.github.copilot` preference domain
Linux	Native MDM delivery is not supported. Use file-based settings instead.

All native MDM values must be strings. For nested settings, use a dot-separated key such as permissions.disableBypassPermissionsMode or sandbox.enabled. Store ordinary string values directly. Store booleans, arrays, and objects as JSON text within a string value.

For example:

Key	Native string value
`permissions.disableBypassPermissionsMode`	`disable`
`sandbox.enabled`	`true`
`enabledPlugins`	`{"PLUGIN-NAME@MARKETPLACE-NAME":true}`

Choose the settings you want to enforce. See Enterprise managed settings.
Convert each setting to the native key and string value representation.
Deploy the settings to the native policy location using your enterprise MDM platform and standard rollout process.
Assign the policy to the target device groups.

Clients do not need to restart, and check for updated policies on an hourly basis. In VS Code, an administrator can force a check for testing by running the Developer: Sync Account Policy command.
Confirm the settings took effect. See Verifying the configuration has applied.

Deploying file-based settings

Place managed-settings.json in the following location:

Operating system	File location
macOS	`/Library/Application Support/GitHubCopilot/managed-settings.json`
Windows	`%ProgramFiles%\GitHubCopilot\managed-settings.json`
Linux	`/etc/github-copilot/managed-settings.json`

Create or update a managed-settings.json file with the policy keys and values you want to enforce.
Distribute the file to the platform-specific location using your standard device management process. Machines that don't receive the file are not restricted by this policy.
For Copilot CLI on macOS and Linux, make the file a regular file owned by root, and ensure it is not group-writable or world-writable. Do not use a symbolic link. The CLI rejects files that do not meet these requirements.
Ask users to restart supported clients so the updated policy is loaded at startup.
Confirm the settings took effect. See Verifying the configuration has applied.

Verifying the configuration has applied

For server-managed deployments, users on a supported client see the specified settings within about an hour. This includes copilot/managed-settings.json, copilot/team-mappings.json, and files in copilot/teams/. Restarting the client or signing in again triggers an immediate refresh.

For MDM-managed deployments, clients check for updated policies hourly. For file-based deployments, restart the client to load an updated file.

If a user does not see these settings, ensure they receive access to Copilot through your enterprise or one of its organizations. If a user receives a license from multiple billing entities, ensure they have selected your enterprise in the "Usage billed to" dropdown in their personal Copilot settings.

Guidance for dedicated Copilot Business enterprises

If you have a dedicated enterprise for Copilot Business (sometimes called Copilot Standalone), you can still use enterprise managed settings. The deployment method you choose determines what you need to set up first.

Using server-managed settings

Server-managed settings require an organization and a .github-private repository. To create these, one user in your enterprise needs a GitHub Enterprise license. With that license, the user can:

Create an organization and a .github-private repository. See Creating a .github-private repository.
Add settings to the repository in a copilot/managed-settings.json file.
Set that organization as the source of governance for your enterprise's AI standards. See Creating a .github-private repository.

From that point on, any user on your enterprise's Copilot plan using Copilot CLI or VS Code is governed by those settings, whether or not they have access to the .github-private repository.

The main limitation of this method is the GitHub Enterprise license requirement to create the organization and repository.

Using MDM-managed or file-based settings

If you don't want to add a GitHub Enterprise license or create an organization, you can deploy the same logical settings through MDM (such as Intune or Jamf) or a file-based deployment. File-based delivery uses the JSON schema directly. Native MDM delivery uses flat keys and string-encoded values. Neither method requires an organization or .github-private repository. See Deploying MDM-managed settings and Deploying file-based settings. For VS Code-specific guidance, see Deploy Copilot managed settings in the VS Code documentation.

Plugin access considerations

Users don't need access to the .github-private repository for clients to pull in managed settings. However, if managed settings define a plugin using enabledPlugins, the client automatically tries to install it for each user. The user needs access to where the plugin files are hosted. If the plugin is hosted in a private repository on GitHub, the user needs authorization to that repository, which may require a license.

Who can use this feature?

In this article