Skip to content

Commit 9434639

Browse files
jc-clarkCopilotsophiethekingdigitaraldsaritai
authored
Add MDM and file-based deployment docs for enterprise managed settings (#61937)
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Sophie <29382425+sophietheking@users.noreply.github.com> Co-authored-by: Harald Kirschner <hkirschner@microsoft.com> Co-authored-by: Sarita Iyer <66540150+saritai@users.noreply.github.com>
1 parent 01ba79d commit 9434639

4 files changed

Lines changed: 154 additions & 18 deletions

File tree

‎content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings.md‎

Lines changed: 62 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
2-
title: Configuring enterprise managed settings
2+
title: Configuring enterprise-managed settings
33
shortTitle: Enterprise managed settings
44
allowTitleToDifferFromFilename: true
5-
intro: Configure enterprise managed settings by defining a `{% data variables.copilot.managed_setting_file %}` file in your enterprise's `.github-private` repository to centrally control {% data variables.product.prodname_copilot_short %} client configurations.
5+
intro: Configure enterprise managed settings to centrally control {% data variables.product.prodname_copilot_short %} client behavior across your enterprise using server-managed, MDM-managed, or file-based deployment.
66
permissions: Enterprise owners
77
redirect_from:
88
- /copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/disable-automatic-commands
@@ -15,7 +15,45 @@ category:
1515
- Manage Copilot for a team
1616
---
1717

18-
With enterprise managed settings, enterprise owners can centrally define and distribute configuration settings to {% data variables.copilot.copilot_cli_short %} and {% data variables.product.prodname_vscode_shortname %} for users on your enterprise's {% data variables.product.prodname_copilot_short %} plan, ensuring every member works within the same guardrails. Additional client support will follow. The `{% data variables.copilot.managed_setting_file %}` takes precedence over file-based configuration set by users in their clients for the supported keys.
18+
With enterprise managed settings, enterprise owners can centrally define and distribute configuration settings to {% data variables.copilot.copilot_cli_short %} and {% data variables.product.prodname_vscode_shortname %} for users on your enterprise's {% data variables.product.prodname_copilot_short %} plan, ensuring every member works within the same guardrails. Additional client support will follow.
19+
20+
These settings apply enterprise-wide, with no organization-level override. For each supported key, the `{% data variables.copilot.managed_setting_file %}` value takes precedence over any file-based configuration a user sets in their client.
21+
22+
Managed settings are loaded locally when the client starts, even if the device has no network connection. This means controls such as disabled bypass mode and restricted plugin configuration still apply before sign in or any server round trip, and remain active when users switch accounts.
23+
24+
## Choosing a deployment method
25+
26+
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.
27+
28+
* **Server-managed**: Default for most enterprises and best for review workflows and audit history
29+
* **MDM-managed**: Best when IT teams need device-group targeting through existing MDM tooling on macOS and Windows
30+
* **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 {% data variables.product.prodname_codespaces %}
31+
32+
## Deploying server-managed settings
33+
34+
1. Create and configure your `.github-private` repository. See [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/create-github-private-repo).
35+
1. In the repository, create or update `copilot/{% data variables.copilot.managed_setting_file %}`.
36+
1. Add your enterprise policy keys and values in JSON format.
37+
1. Commit and push your changes to the default branch.
38+
1. Confirm that enterprise users are running a supported client. Updated settings are applied automatically within about an hour, or immediately after the client restarts or the user signs in again.
39+
40+
## Deploying MDM-managed settings
41+
42+
1. Create or update your `{% data variables.copilot.managed_setting_file %}` payload using the same JSON schema used for server-managed settings.
43+
1. Deploy the payload using your enterprise MDM platform and standard rollout process.
44+
1. Assign the policy to the target device groups.
45+
46+
Clients do not need to restart, and check for updated policies on an hourly basis. In {% data variables.product.prodname_vscode_shortname %}, an administrator can force a check for testing by running the `Developer: Sync Account Policy` command.
47+
48+
1. Confirm the settings took effect. See [Verifying the configuration has applied](#verifying-the-configuration-has-applied).
49+
50+
## Deploying file-based settings
51+
52+
1. Create or update a `{% data variables.copilot.managed_setting_file %}` file with the policy keys and values you want to enforce.
53+
1. Distribute the file to managed machines using your standard device management process. Machines that don't receive the file are not restricted by this policy, so file-based deployment only provides coverage for the machines you actively distribute to.
54+
1. Apply file permissions according to your enterprise security requirements.
55+
1. Ask users to restart supported clients so the updated policy is loaded at startup.
56+
1. Confirm the settings took effect. See [Verifying the configuration has applied](#verifying-the-configuration-has-applied).
1957

2058
## Consolidated schema reference
2159

@@ -41,25 +79,24 @@ The `{% data variables.copilot.managed_setting_file %}` file supports the follow
4179
"PLUGIN-NAME@MARKETPLACE-NAME": true
4280
},
4381
"permissions": {
44-
"disableBypassPermissionsMode": "disable",
45-
"model": "auto"
46-
}
82+
"disableBypassPermissionsMode": "disable"
83+
},
84+
"model": "auto"
4785
}
4886
```
4987

5088
* `extraKnownMarketplaces`: Defines additional plugin marketplaces available to users. Each entry is a named marketplace object containing a `source` property that specifies the provider (`"github"`) and the repository in `OWNER/REPO` format.
5189
* `strictKnownMarketplaces`: Restricts plugin installation to only the marketplaces explicitly defined by the enterprise. Each entry is a marketplace object containing a `source` property. The `source` specifies the provider as either `"github"` with a `repo` in `OWNER/REPO` format, or `"git"` with a `url` pointing to a git repository.
5290
* `enabledPlugins`: Defines plugins that are automatically installed for all enterprise users. Each entry uses the format `PLUGIN-NAME@MARKETPLACE-NAME` as the key, with a boolean value of `true` to enable the plugin.
53-
* `permissions`: Controls whether users can bypass command approval.
54-
* Set `model` to `"auto"` so new conversations start with Copilot auto model selection by default. Users can still switch to a different model on a per-conversation basis.
55-
* Set `disableBypassPermissionsMode` to `"disable"` to prevent users from turning on bypass mode. See [Disabling bypass mode for your enterprise](#disabling-bypass-mode-for-your-enterprise) further in this article for more information.
91+
* `permissions`: Controls whether users can bypass command approval. Set `disableBypassPermissionsMode` to `"disable"` to prevent users from turning on bypass mode. See [Disabling bypass mode for your enterprise](#disabling-bypass-mode-for-your-enterprise) further in this article for more information.
92+
* `model`: Controls default model governance settings. Set to `"auto"` so new conversations start with Copilot auto model selection by default. Users can still switch to a different model on a per-conversation basis.
5693

5794
## Configuring enterprise plugin standards
5895

5996
You can apply settings to control users' available plugin marketplaces and default-installed plugins. See [AUTOTITLE](/copilot/concepts/agents/about-enterprise-plugin-standards).
6097

6198
{% data reusables.copilot.create-managed-settings %}
62-
1. Add your plugin policy configuration to the file, using the `extraKnownMarketplaces`, `strictKnownMarketplaces`, and `enabledPlugins` properties described in [Consolidated schema reference](#consolidated-schema-reference).
99+
1. Add the `extraKnownMarketplaces`, `strictKnownMarketplaces`, and `enabledPlugins` properties you need to the file. See the example and property descriptions in [Consolidated schema reference](#consolidated-schema-reference). Merge these properties into an existing file rather than overwriting it, so you don't remove settings configured for other policies, such as `permissions`.
63100

64101
```json copy
65102
{
@@ -85,19 +122,30 @@ You can apply settings to control users' available plugin marketplaces and defau
85122

86123
1. Commit and push your changes to the default branch of the `.github-private` repository.
87124

88-
## Setting Copilot auto model selection as the default
125+
## Setting {% data variables.product.prodname_copilot_short %} auto model selection as the default
89126

90127
You can set auto model selection as the default model for new conversations in {% data variables.copilot.copilot_cli_short %} and {% data variables.product.prodname_vscode_shortname %}. To learn more see [AUTOTITLE](/copilot/concepts/auto-model-selection). By setting it as the default for your enterprise, you ensure new conversations start with Auto model selected.
91128

92129
### What setting Auto model as the default does
93130

94-
When you set `model` to `"auto"` under `permissions`, new conversations start with Auto model selected in both clients:
131+
When you `model` to `"auto"`, new conversations start with Auto model selected in both clients:
95132

96133
* In {% data variables.copilot.copilot_cli_short %}, new sessions use Auto model unless the user specifies a different model.
97134
* In {% data variables.product.prodname_vscode_shortname %}, the model picker defaults to Auto model when a user starts a new conversation.
98135

99136
Users can still switch to a different model on a per-conversation basis.
100137

138+
### Configuring the setting
139+
140+
{% data reusables.copilot.create-managed-settings %}
141+
1. Add the `model` property to the file, set to `"auto"`.
142+
143+
```json copy
144+
{
145+
"model": "auto"
146+
}
147+
```
148+
101149
## Disabling bypass mode for your enterprise
102150

103151
You can prevent users from enabling bypass mode (also known as "YOLO mode") in {% data variables.copilot.copilot_cli_short %} and {% data variables.product.prodname_vscode_shortname %}. Bypass mode lets an agent run commands, access files, and fetch URLs without asking for approval. By disabling it for your enterprise, you ensure that a person reviews each of these actions.
@@ -112,7 +160,7 @@ When you set `disableBypassPermissionsMode` to `"disable"`, users cannot turn on
112160
### Configuring the setting
113161

114162
{% data reusables.copilot.create-managed-settings %}
115-
1. Add the `permissions` property to the file, with `disableBypassPermissionsMode` set to `"disable"`.
163+
1. Add the `permissions` property to the file, with `disableBypassPermissionsMode` set to `"disable"`. If the file already has a `permissions` object (for example, from other permission settings), merge this key into it rather than replacing the object.
116164

117165
```json copy
118166
{
@@ -122,10 +170,8 @@ When you set `disableBypassPermissionsMode` to `"disable"`, users cannot turn on
122170
}
123171
```
124172

125-
1. Commit and push your changes to the default branch of the `.github-private` repository.
126-
127173
## Verifying the configuration has applied
128174

129-
Once the configuration is committed, users will see the specified settings the next time they authenticate from a supported client. Clients pull the latest configuration once per hour.
175+
Once the configuration is committed, users on a supported client see the specified settings within about an hour, since clients periodically check the server for updated configuration. Restarting the client or signing in again applies the latest settings immediately.
130176

131177
If a user does not see these settings, ensure they receive access to {% data variables.product.prodname_copilot_short %} 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 {% data variables.product.prodname_copilot_short %} settings](https://github.com/settings/copilot/features).

‎content/copilot/reference/enterprise-managed-settings-reference.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
title: Enterprise managed settings reference
3+
shortTitle: Managed settings reference
4+
intro: 'Reference for the enterprise managed settings schema used by {% data variables.product.prodname_copilot_short %} clients.'
5+
versions:
6+
feature: copilot
7+
contentType: reference
8+
category:
9+
- Configure Copilot
10+
---
11+
12+
> [!NOTE]
13+
> This feature is in {% data variables.release-phases.public_preview %} and subject to change.
14+
15+
Use this reference to understand the currently supported keys in `{% data variables.copilot.managed_setting_file %}`.
16+
17+
For deployment methods, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings#choosing-a-deployment-method).
18+
19+
## Precedence rules
20+
21+
When multiple settings sources are present, clients apply settings in this order:
22+
23+
1. Server-managed settings
24+
1. MDM-managed settings
25+
1. File-based settings
26+
1. User-level settings
27+
28+
MDM-managed settings take precedence. If MDM-managed settings are not available, clients apply server-managed settings before file-based settings.
29+
30+
## Supported keys
31+
32+
{% rowheaders %}
33+
34+
| Key | Type | Accepted values | Purpose |
35+
| --- | --- | --- | --- |
36+
| `permissions.disableBypassPermissionsMode` | `string` | `"disable"` | Disables bypass or YOLO-style allow-all behavior |
37+
| `enabledPlugins` | `object` | Key format: `PLUGIN-NAME@MARKETPLACE-NAME`; value: `true` | Enables specific plugins by key |
38+
| `extraKnownMarketplaces` | `object` | Named marketplace object with `source.source` (`"github"`) and `source.repo` (`OWNER/REPO`) | Adds plugin marketplaces that users can access |
39+
| `strictKnownMarketplaces` | `array` | Array of marketplace objects with `source` values (`"github"` with `repo`, or `"git"` with `url`) | Restricts plugin installation to explicitly listed marketplaces |
40+
| `model` | `object` | `default` set to a supported model name | Defines default model governance settings |
41+
| `telemetry` | `object` | `enabled` (`boolean`), `endpoint` (`string`), `protocol` (`"otlp-http"` or `"otlp-grpc"`), `captureContent` (`boolean`), `lockCaptureContent` (`boolean`), `serviceName` (`string`), `resourceAttributes` (`object`), `headers` (`object`) | Configures OpenTelemetry export for {% data variables.product.prodname_vscode_shortname %} |
42+
43+
{% endrowheaders %}
44+
45+
## Example configuration
46+
47+
The following example shows these keys in one managed settings file.
48+
49+
```json
50+
{
51+
"permissions": {
52+
"disableBypassPermissionsMode": "disable"
53+
},
54+
"enabledPlugins": {
55+
"my-plugin@agent-skills": true
56+
},
57+
"extraKnownMarketplaces": {
58+
"agent-skills": {
59+
"source": {
60+
"source": "github",
61+
"repo": "OWNER/REPO"
62+
}
63+
}
64+
},
65+
"strictKnownMarketplaces": [
66+
{
67+
"source": "github",
68+
"repo": "OWNER/REPO"
69+
}
70+
],
71+
"model": {
72+
"default": "MODEL-NAME"
73+
},
74+
"telemetry": {
75+
"enabled": true,
76+
"endpoint": "https://otel-collector.example.com",
77+
"protocol": "otlp-http",
78+
"captureContent": false,
79+
"lockCaptureContent": true,
80+
"serviceName": "copilot",
81+
"resourceAttributes": {
82+
"deployment.environment": "production"
83+
},
84+
"headers": {
85+
"Authorization": "Bearer TOKEN"
86+
}
87+
}
88+
}
89+
```

‎content/copilot/reference/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ children:
1616
- /hooks-reference
1717
- /policy-conflicts
1818
- /supported-surfaces-for-policies
19+
- /enterprise-managed-settings-reference
1920
- /copilot-allowlist-reference
2021
- /mcp-allowlist-enforcement
2122
- /metrics-data

‎data/reusables/copilot/create-managed-settings.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
1. In your enterprise's `.github-private` repository, create the managed settings file at `copilot/{% data variables.copilot.managed_setting_file %}`. If you haven't set a `.github-private` repository as your enterprise's source of agent configuration, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/create-github-private-repo).
1+
1. Create or update your enterprise managed settings file using your preferred deployment method. For a comparison of deployment methods, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings#choosing-a-deployment-method).
22

3-
The legacy path (`.github/copilot/settings.json`) is also supported.
3+
For server-managed deployment in a `.github-private` repository, create the file at `copilot/{% data variables.copilot.managed_setting_file %}`. The legacy path (`.github/copilot/settings.json`) is also supported.

0 commit comments

Comments
 (0)