add-policy

構成ポリシーの追加

ポリシーを使用すると、企業の管理者は OS レベルの仕組み（Windows グループポリシー、macOS の管理対象環境設定、Linux の構成ファイル）または Copilot アカウントレベルのポリシーデータを介して、構成設定をロックできます。このスキルでは、手順全体を説明します。

使用する場合

• 任意の構成プロパティに新しい policy: フィールドを追加する場合
• 既存のポリシーを変更する場合（名前の変更、カテゴリの変更など）
• ポリシー登録に関わる PR をレビューする場合
• IPolicyData を介したアカウントベースのポリシーサポートを追加する場合
• 企業の管理対象設定（ネイティブ MDM ／ GitHub サーバー）を接続する場合 — github-managed-settings.md を参照してください
• policyReference を介して複数の設定を 1 つのポリシーで制御する場合
• 実際のバックエンドを使わずに、アカウント／管理対象設定ポリシーをローカルでテストする場合 — local-testing.md を参照してください

アーキテクチャの概要

ポリシーソース（レイヤー化され、後から適用された設定が優先）

ソース	実装	ポリシーの読み取り方法
OS レベル（Windows レジストリ、macOS plist）	@vscode/policy-watcher を介した NativePolicyService	Software\Policies\Microsoft\{productName}（Windows）またはバンドル識別子の環境設定（macOS）を監視します
Linux ファイル	FilePolicyService	/etc/vscode/policy.json を読み取ります
アカウント／GitHub	AccountPolicyService	IDefaultAccountService.policyData から IPolicyData を読み取り、value() 関数を適用します。サーバーから配信される管理対象設定は policyData.managedSettings に格納されます。ネイティブ MDM（INativeManagedSettingsService）とディスク上のファイル（IFileManagedSettingsService）は別個の入力であり、AccountPolicyService が getPolicyData() 内で pickManagedSettings(nativeMdm, server, file) を使ってマージします（キーごとの優先順位はネイティブ MDM > サーバー > ファイルです。上位のチャネルでロックされたキーは上書きできず、上位のチャネルで未設定のキーは下位のチャネルにフォールバックします）
Copilot 管理対象設定（ネイティブ MDM）	@vscode/policy-watcher を介した NativeManagedSettingsService	SOFTWARE\Policies\GitHubCopilot（Windows）／com.github.copilot の環境設定（macOS）を監視し、正規の managedSettings バッグに値を渡します — github-managed-settings.md を参照してください
Copilot 管理対象設定（ファイル）	FileManagedSettingsService	メインプロセスで、OS ごとに定められたパスから managed-settings.json を読み取り、監視します。IPC を介してレンダラーに公開されます。管理対象設定チャネルの中で最も優先順位が低いチャネルです — github-managed-settings.md を参照してください
多重化	MultiplexPolicyService	メインプロセスでは複数の OS／ファイルポリシーリーダーを統合します。デスクトップおよび Agents ウィンドウのレンダラーでは、メインプロセスの PolicyChannelClient と AccountPolicyService を統合します

主要ファイル

ファイル	目的
src/vs/base/common/policy.ts	PolicyCategory 列挙型、IPolicy インターフェイス、IPolicyReference、ManagedSettingsData、IManagedSettingsPolicyDefinitions
src/vs/platform/policy/common/policy.ts	IPolicyService、AbstractPolicyService、PolicyDefinition、toSerializablePolicyDefinition（IPC 用にクローン不可の value() を除外）、getRestrictedPolicyValue
src/vs/platform/policy/common/copilotManagedSettings.ts	管理設定のキー定数と既知のファイルパス、collectManagedSettingsDefinitions、projectManagedSettings、全チャネル共通の正規化関数 normalizeManagedSettings、チャネルごとのキー優先順位を扱う pickManagedSettings、INativeManagedSettingsService / IFileManagedSettingsService
src/vs/platform/policy/node/nativeManagedSettingsService.ts	Copilot の管理設定用ネイティブ MDM ウォッチャー（@vscode/policy-watcher）
src/vs/platform/policy/common/fileManagedSettingsService.ts	ファイルベースのチャネル：既知の OS ごとのパスにある managed-settings.json を読み込み、監視し、normalizeManagedSettings で正規化
src/vs/platform/configuration/common/configurations.ts	PolicyConfiguration — ポリシーを構成値に連携し、JSON 文字列の管理設定を型付きの値に再解析し、値を policyReference 設定に適用
src/vs/platform/configuration/common/configurationRegistry.ts	policy / policyReference の登録、getPolicyReferenceConfigurations()（名前 → 従属する設定）
src/vs/workbench/services/policies/common/accountPolicyService.ts	アカウント／GitHub ベースのポリシー評価。管理設定を選択・投影（サーバーよりネイティブ MDM を優先する単一の権威レイヤー）
src/vs/workbench/services/accounts/browser/managedSettings.ts	adaptManagedSettings — サーバーの managed_settings レスポンスを正規の設定バッグに正規化
src/vs/workbench/services/policies/common/multiplexPolicyService.ts	複数のポリシーサービスを結合
src/vs/workbench/contrib/policyExport/electron-browser/policyExport.contribution.ts	--export-policy-data コマンドラインハンドラー
src/vs/base/common/defaultAccount.ts	アカウントレベルのポリシーフィールド用 IPolicyData インターフェイス（managedSettings を含む）
build/lib/policies/policyData.jsonc	referencedSettings を含む、自動生成されたポリシーカタログ（手動で編集しないでください）
build/lib/policies/policyGenerator.ts	ADMX/ADML（Windows）、plist（macOS）、JSON（Linux）を生成
build/lib/test/policyConversion.test.ts	ポリシー成果物の生成テスト

手順

ステップ 1 — 構成プロパティに policy フィールドを追加する

構成の登録箇所（通常は *.contribution.ts ファイル内）を見つけ、プロパティスキーマに policy オブジェクトを追加します。

必須フィールド：

minimumVersion の決定方法： ルートの package.json から必ず version を読み取り、major.minor の部分を使用します。たとえば、package.json に "version": "1.112.0" とある場合は、minimumVersion: '1.112' を使用します。'1.99' のような古いバージョンをハードコードしないでください。

policy: {
    name: 'MyPolicyName',                          // PascalCase, unique across all policies
    category: PolicyCategory.InteractiveSession,    // From PolicyCategory enum
    minimumVersion: '1.112',                        // Use major.minor from package.json version
    localization: {
        description: {
            key: 'my.config.key',                   // NLS key for the description
            value: nls.localize('my.config.key', "Human-readable description."),
        }
    }
}

任意：アカウントベースのポリシー用の value 関数：

このポリシーを Copilot アカウントのポリシーデータ（IPolicyData から取得）でも制御できるようにする場合は、value 関数を追加します。

policy: {
    name: 'MyPolicyName',
    category: PolicyCategory.InteractiveSession,
    minimumVersion: '1.112',                        // Use major.minor from package.json version
    value: (policyData) => policyData.my_field === false ? false : undefined,
    localization: { /* ... */ }
}

value 関数は（src/vs/base/common/defaultAccount.ts の）IPolicyData を受け取り、次のいずれかを返します。

• ユーザー設定を上書きする具体的な値
• アカウントレベルの上書きを適用しない場合は undefined（OS ポリシーまたはユーザー設定にフォールバックします）

IPolicyData に新しいフィールドが必要な場合は、src/vs/base/common/defaultAccount.ts のインターフェイスに追加してください。

任意：列挙型／文字列ポリシー用の enumDescriptions：

重要： 構成プロパティが type: 'string' で enum 配列を持つ場合、localization ブロックに enumDescriptions を含める必要があります。エントリ数は enum 配列と同じでなければなりません。これがないと、npm run export-policy-data は次のエラーで失敗します：enumDescriptions must exist and have the same length as enum for policy "..."。

localization: {
    description: { key: '...', value: nls.localize('...', "...") },
    enumDescriptions: [
        { key: 'opt.none', value: nls.localize('opt.none', "No access.") },
        { key: 'opt.all', value: nls.localize('opt.all', "Full access.") },
    ]
}

ステップ 2 — PolicyCategory がインポートされていることを確認する

import { PolicyCategory } from '../../../../base/common/policy.js';

PolicyCategory 列挙型にある既存のカテゴリ：

• Extensions
• IntegratedTerminal
• InteractiveSession（すべてのチャット／Copilot ポリシーで使用）
• Telemetry
• Update

新しいカテゴリが必要な場合は、src/vs/base/common/policy.ts の PolicyCategory に追加し、対応する PolicyCategoryData のローカライズも追加してください。

ステップ 3 — TypeScript のコンパイルを検証する

VS Code - Build のウォッチタスク出力を確認するか、次を実行します。

npm run typecheck-client

ステップ 4 — ポリシーデータをエクスポートする

自動生成されるポリシーカタログを再生成します。

npm run export-policy-data

このスクリプトはトランスパイルを処理し、GITHUB_TOKEN を設定し（gh CLI または GitHub OAuth のデバイスフローを使用）、--export-policy-data を実行します。エクスポートコマンドは GitHub API を介してディストリビューションの product.json から拡張機能の構成ポリシーを読み取り、出力に統合します。

これにより build/lib/policies/policyData.jsonc が更新されます。このファイルを手動で編集しないでください。 出力に新しいポリシーが含まれていることを確認してください。この変更を main にマージするには、コードオーナーによるコードレビューが必要です。

拡張機能が提供する設定のポリシー

拡張機能の作成者は policy: フィールドを直接追加できません。設定は VS Code コアではなく、拡張機能の package.json で定義されているためです。代わりに、拡張機能の設定に対するポリシーは、vscode-distro の product.json にある extensionConfigurationPolicy キーで定義します。

仕組み

1. 信頼できる情報源：extensionConfigurationPolicy マップは、vscode-distro の mixin/{quality}/product.json（stable、insider、exploration）にあります。
2. 実行時：VS Code の起動時に、ディストリビューションの product.json がマージされていると、configurationExtensionPoint.ts が extensionConfigurationPolicy を読み取り、一致するポリシーオブジェクトを拡張機能が提供する構成プロパティに追加します。
3. エクスポート／ビルド：--export-policy-data コマンドは、package.json で指定されたコミット時点のディストリビューションの product.json を取得し、拡張機能のポリシーを出力に統合します。認証は自動的に設定されるため、npm run export-policy-data を使用してください。

ディストリビューションの形式

extensionConfigurationPolicy の各エントリには、次の項目が必要です。

"extensionConfigurationPolicy": {
    "publisher.extension.settingName": {
        "name": "PolicyName",
        "category": "InteractiveSession",
        "minimumVersion": "1.99",
        "description": "Human-readable description."
    }
}

• name：すべてのポリシーで一意となる PascalCase のポリシー名
• category：有効な PolicyCategory 列挙値（例：InteractiveSession、Extensions）
• minimumVersion：このポリシーが最初にリリースされた VS Code のバージョン
• description：ADMX／ADML／macOS／Linux のポリシー成果物向けにローカライズキーと値を生成するために使用される、人が読める説明文字列

新しい拡張機能ポリシーの追加

1. vscode-distro にある品質関連の 3 つすべての product.json ファイル（mixin/stable/、mixin/insider/、mixin/exploration/）の extensionConfigurationPolicy にエントリーを追加します
2. package.json の distro コミットハッシュを、新しいエントリーを含む distro のコミットを指すように更新します — エクスポートコマンドは、固定された distro のコミットから拡張機能ポリシーを取得します
3. npm run export-policy-data を実行して policyData.jsonc を再生成します（上記のステップ 4 を参照）
4. src/vs/workbench/contrib/policyExport/test/node/extensionPolicyFixture.json のテストフィクスチャを新しいエントリーで更新します

テストフィクスチャ

src/vs/workbench/contrib/policyExport/test/node/extensionPolicyFixture.json は、チェックイン済みの policyData.jsonc に含まれる拡張機能ポリシーと同期させておく必要があるテストフィクスチャです。distro で拡張機能ポリシーが追加または変更された場合は、それに合わせてこのフィクスチャも更新する必要があります。そうしないと、テスト出力（フィクスチャから生成）がチェックイン済みファイル（実際の distro から生成）と一致せず、統合テストが失敗します。

下流の利用者

利用者	読み取るもの	出力
policyGenerator.ts	policyData.jsonc	ADMX/ADML（Windows GP）、.mobileconfig（macOS）、policy.json（Linux）
vscode-website（gulpfile.policies.js）	policyData.jsonc	code.visualstudio.com/docs/enterprise/policies のエンタープライズポリシー参照表
vscode-docs	Web サイトのビルドから生成	docs/enterprise/policies.md

GitHub プレビュー機能

設定が GitHub プレビュー機能（組織が GitHub アカウントレベルのポリシーで無効にできる Copilot／チャット機能）である場合、policyData.chat_preview_features_enabled を確認する value 関数を 必ず追加してください。

このフラグを追加する場合

以下のすべてに該当する場合は、chat_preview_features_enabled のチェックを追加します。

• 設定が Copilot またはチャット機能（例：エージェントツール、フック、MCP、自動承認）を制御している
• 機能がプレビューまたは試験的なステータスである（通常は 'preview' または 'experimental' のタグが付いています）
• 組織の管理者が GitHub アカウントポリシーを通じて、組織内のすべてのユーザーに対してこの機能を無効にできる必要がある

仕組み

IPolicyData（src/vs/base/common/defaultAccount.ts で定義）の chat_preview_features_enabled フィールドには、ユーザーの GitHub Copilot トークンのエンタイトルメントから値が設定されます。組織の管理者がプレビュー機能を無効にすると、chat_preview_features_enabled は false に設定されます。

パターン

ポリシーに value 関数を追加します。この関数は、chat_preview_features_enabled === false の場合は機能を無効にする値を返し、それ以外の場合は undefined を返します（ユーザー自身の設定に委ねます）。

policy: {
    name: 'MyPreviewFeaturePolicy',
    category: PolicyCategory.InteractiveSession,
    minimumVersion: '1.xx', // Must match the first VS Code release that ships this policy.
    value: (policyData) => policyData.chat_preview_features_enabled === false ? false : undefined,
    localization: {
        description: {
            key: 'my.setting.description',
            value: nls.localize('my.setting.description', "Description of the setting."),
        }
    }
}

重要な点：

• !policyData.chat_preview_features_enabled ではなく、必ず === false で比較してください — このフィールドは省略可能であり、undefined は「ポリシーデータが利用できない」ことを意味するため、機能を無効にすべきではありません。
• アカウントレベルのポリシーでユーザーの設定を上書きしないよう、フラグが false でない場合は undefined を返してください。
• 設定の型に応じた無効化の値を 返してください。ブール値の場合は false、それ以外の型の場合は制限的な文字列／列挙値を返します。

実例

このパターンを使用している既存の設定については、src/vs/workbench/contrib/chat/browser/chat.shared.contribution.ts の chat.tools.global.autoApprove と chat.useHooks を参照してください。

エンタープライズ管理設定（ネイティブ MDM／GitHub サーバー）

GitHub Copilot のエンタープライズ管理者は、managed-settings バッグを通じて設定をロックできます。 VS Code は、ネイティブ MDM（Windows レジストリ／macOS plist）と GitHub の /copilot_internal/managed_settings エンドポイントという2 つの経路からバッグを受け取ります。（外部の managed-settings-schema.json には managed-settings.json ファイル経由の経路も記載されていますが、 VS Code はそのようなファイルを読み取りません。）VS Code の両方の経路は IPolicyData.managedSettings（フラットなドットパス形式のバッグ）に集約され、既存の policy.value(policyData) コールバックによって使用されます。新しい IPolicyService はありません。

管理設定からポリシーを制御するには、ポリシーで managedSettings を宣言し、value 内で policyData.managedSettings?.[KEY] を読み取ります（実際の ChatToolsAutoApprove は chat_preview_features_enabled === false も OR で組み合わせます）。

// Existing policy shown verbatim; `minimumVersion: '1.99'` is its historical value —
// a NEW policy derives minimumVersion from package.json major.minor (see Step 1).
policy: {
    name: 'ChatToolsAutoApprove',
    category: PolicyCategory.InteractiveSession,
    minimumVersion: '1.99',
    value: (policyData) =>
        policyData.managedSettings?.[COPILOT_DISABLE_BYPASS_PERMISSIONS_MODE_KEY] === 'disable'
            || policyData.chat_preview_features_enabled === false ? false : undefined,
    managedSettings: {
        [COPILOT_DISABLE_BYPASS_PERMISSIONS_MODE_KEY]: { type: 'string' },
    },
    localization: { /* ... */ }
}

これは独立したモダリティです。詳細、スキーマの信頼できる情報源、ヘルパー、配線、新しいキーのチェックリストについては、github-managed-settings.md を参照してください。 管理設定のキーを追加またはレビューする前に、必ずお読みください。

ローカルでのテスト： 実際の GitHub バックエンドを使わずにアカウント／管理設定のフローを試すには、モックポリシーサーバーを使用してください。詳しくは local-testing.md を参照してください。

1 つのポリシーで複数の設定を管理する（policyReference）

1 つのポリシーで複数の設定を管理できます（例：エディターウィンドウと Agents ウィンドウの両方でエージェントを制御する）。所有元は完全な policy: { name, … } を宣言し、他の設定は所有元のポリシー名を指定する policyReference: { name } を宣言します。

// Owner setting (existing policy; `minimumVersion: '1.126'` is its historical value —
// a NEW policy uses package.json major.minor, see Step 1)
policy: { name: 'Codex3PIntegration', category: PolicyCategory.InteractiveSession, minimumVersion: '1.126', /* ... */ }

// Subordinate setting (no type/value/localization of its own)
policyReference: { name: 'Codex3PIntegration' }

policyReference は管理設定専用ではありません。1 つのエンタープライズポリシーで複数の設定を同じ値にロックする場合に使用してください。この参照は単なるポインターです。参照自体に型、value、managedSettings、restrictedValue、ローカライズ情報はありません。ポリシーのメタデータと実行時の動作に関する唯一の信頼できる情報源は、引き続き所有元です。

主なルールと内部動作：

• 1 つの設定で policy と policyReference の両方を宣言してはいけません（設定の登録時に拒否されます）。
• ポリシー名を所有できる設定は policy を宣言する 1 つだけです。追加の設定は policyReference で関連付けます。
• 参照先の設定の型は所有元の型と一致する必要があります。解決された同じポリシー値が所有元と参照先にそのまま適用されるため、npm run export-policy-data によって検証されます。
• ConfigurationRegistry.getPolicyReferenceConfigurations() は policyName → Set<settingKey> を追跡し、ポリシー値が変わると PolicyConfiguration が所有元の設定と登録済みのすべての参照先を更新します。
• AbstractPolicyService.serialize() は toSerializablePolicyDefinition() を使用して、IPC 経由でポリシー定義を送信する前に、複製できない value() コールバックを取り除きます。
• AbstractPolicyService.updatePolicyDefinitions() はポリシー名ごとに定義を置き換えます。そのため、後から登録された所有元が先に登録された参照先のフォールバックに優先します。所有元が削除された場合でも、参照先は型のみのフォールバックを提供できます。
• エクスポートされたポリシーデータには、エクスポート中に登録された参照先の referencedSettings が含まれます。また、Developer: Policy Diagnostics には、同じポリシー名で登録された所有元／参照先の設定が表示されます。

policyReference と Copilot の管理設定を組み合わせた管理設定固有の例については、github-managed-settings.md を参照してください。

例

コードベース内で policy: を検索すると、さまざまなポリシー設定の例を確認できます。

学んだこと

• build/lib/policies/policyData.jsonc は手作業で編集しないでください（ヘッダーで明示的に禁止されています）。npm run export-policy-data が失敗する場合は、スクリプトを修正してください。JSON を直接修正してはいけません。よくある原因は、誤った作業ディレクトリで実行していることです（例：ワークツリーではなくメインリポジトリ）。その場合、誤ったソースツリーが気付かないうちにエクスポートされます。
• クリーンな環境で policyData.jsonc を再生成してください。そうしないと、PolicyExport 統合テストが CI で失敗します。 referencedSettings に記録されるのは、エクスポート時に読み込まれた参照だけです。通常の npm run export-policy-data では、開発用プロファイルの拡張機能（例：Copilot 拡張機能）が読み込まれます。これにより、テストのフィクスチャーベースのエクスポート（クリーンなプロファイルで、ユーザー拡張機能なし）では生成されない referencedSettings がコアポリシーに追加されます。そのため、チェックインされたファイルに余分な referencedSettings が含まれ、CI が失敗します。テストでは既定の拡張機能ディレクトリが再利用されるため、ローカルでは再現しません。テストと同じ方法でエクスポートしてください：DISTRO_PRODUCT_JSON=<extensionPolicyFixture.json> ./scripts/code.sh --export-policy-data="$PWD/build/lib/policies/policyData.jsonc" --user-data-dir="$(mktemp -d)" --extensions-dir="$(mktemp -d)"（VSCODE_SKIP_PRELAUNCH=1 を指定してください）。
• 実装をそのままコピーするのではなく、動作とビジネスロジックに関する期待事項を記載してください。内部コード（例：getPolicyData() のマージ処理）をスキルに再現すると、ソースが変更された時点で内容が古くなり、ソース自体を超える情報も得られません。契約を文章で示し（例：「ネイティブ MDM 管理設定はサーバー配信チャネルより優先され、2 つのレイヤーがマージされることはありません」）、実装についてはソースを参照するようにしてください。コードブロックは、コントリビューターが従う必要のある作成者向け API 契約、つまり policy／managedSettings／value コールバックの宣言方法に限って使用し、実行時の処理を言い換えて説明するためには使わないでください。