Document Copilot CLI permissions-config.json schema and persisted approvals

[danmoseley]

Note

This pull request was created with the help of GitHub Copilot, and parts of the documentation were AI-generated. All schema details were verified against the Copilot CLI source.

What this changes

Expands the documentation for the Copilot CLI permissions-config.json file, which was previously documented only at a surface level.

content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md

• Documents the file-resolution order (--config-dir → COPILOT_HOME → ~/.copilot/permissions-config.json) and the legacy extensionless file.
• Documents the locations keying rules (Git root; linked worktrees resolve to the main repo root; submodules use their own directory; non-Git uses the cwd).
• Adds a full schema table covering locations, tool_approvals, and allowed_directories, and every approval kind (commands, read, write, memory, mcp, mcp-sampling, custom-tool, extension-management, extension-permission-access) with their per-kind fields (commandIdentifiers, serverName, toolName, operation, extensionName).
• Adds copy-pasteable example configurations and an explicit list of what the file does not support (deny/ask rules, default modes, URL rules, tool filtering, repository-local policy), pointing to the relevant CLI options instead.

content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md

• Adds a short "persisted permissions" note explaining that answering "yes, always" to a prompt saves the decision to ~/.copilot/permissions-config.json, with a cross-link to the reference section.

Why

Users have reported that permissions-config.json is hard to configure because the schema, fields, and file location were not documented in enough detail — particularly when migrating settings from other agent CLIs.

Verification

The documented schema, approval kinds, and per-kind fields were checked against the product source. Examples are valid JSON and consistent with the schema table. Locally ran npm ci and the docs content linter (lint-content) on the changed files; the repo's pre-commit content lint also passed.

[github-actions]

How to review these changes 👓

Thank you for your contribution. To review these changes, choose one of the following options:

• Spin up a codespace
• Set up a local development environment

A Hubber will need to deploy your changes internally to review.

Table of review links

Note: Please update the URL for your staging server or codespace.

The table shows the files in the content directory that were changed in this pull request. This helps you review your changes on a staging server. Changes to the data directory are not included in this table.

Source	Review	Production	What Changed
copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md	fpt ghec	fpt ghec
copilot/reference/copilot-cli-reference/cli-config-dir-reference.md	fpt ghec	fpt ghec

Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server

🤖 This comment is automatically generated.

[Copilot]

Pull request overview

Expands the GitHub Copilot CLI documentation for permissions-config.json, covering where it’s stored, how location scoping works, and the approval schema so users can reliably migrate or author persisted tool/path approvals.

Changes:

• Added detailed reference documentation for permissions-config.json (resolution order, location keying, schema, approval kinds, and examples).
• Documented command identifier and directory matching behavior used by persisted approvals.
• Added a “persisted permissions” explanation and cross-links from the tool-permissions how-to.

Show a summary per file

File	Description
content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md	Adds full reference coverage for permissions-config.json location resolution, schema, approval kinds, and examples.
content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md	Explains persisted approvals and links to the detailed reference section.

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 1