From e5596f49e2b5bda5b2a44961e286455f65f8f074 Mon Sep 17 00:00:00 2001 From: Emmanuel Chigbo Date: Fri, 12 Jun 2026 18:37:30 -0500 Subject: [PATCH 1/6] Reorganize Copilot usage metrics field reference by report type (#61700) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com> --- .../copilot-usage-metrics.md | 320 +++++++++++++----- 1 file changed, 234 insertions(+), 86 deletions(-) diff --git a/content/copilot/reference/copilot-usage-metrics/copilot-usage-metrics.md b/content/copilot/reference/copilot-usage-metrics/copilot-usage-metrics.md index df7f243e639f..32c5fb359d98 100644 --- a/content/copilot/reference/copilot-usage-metrics/copilot-usage-metrics.md +++ b/content/copilot/reference/copilot-usage-metrics/copilot-usage-metrics.md @@ -17,7 +17,7 @@ contentType: reference The {% data variables.product.prodname_copilot_short %} usage metrics dashboard and APIs display and export data using a consistent set of fields. This reference lists all available metrics and describes how to interpret their values in both dashboard visuals and NDJSON or API exports. * The {% data variables.product.prodname_copilot_short %} usage metrics dashboards are available at the **enterprise** and **organization** level. -* The {% data variables.product.prodname_copilot_short %} usage metrics APIs support **enterprise-, organization-, and user-level** records. +* The {% data variables.product.prodname_copilot_short %} usage metrics APIs return reports scoped to the **enterprise**, **organization**, or **individual user** level, in different shapes depending on scope and granularity. * Team-level metrics are not pre-aggregated; you construct them by joining the user-teams report with the per-user usage metrics report. See [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics). For guidance on how to read and interpret these metrics, see [AUTOTITLE](/copilot/concepts/copilot-metrics). @@ -63,100 +63,248 @@ These metrics appear in the code generation dashboard and provide a breakdown of ## API and export fields -These fields appear in the exported NDJSON reports and in the {% data variables.product.prodname_copilot_short %} usage metrics APIs. They provide daily records at the enterprise, organization, or user scope, depending on the metric. +These fields appear in the exported NDJSON reports and in the {% data variables.product.prodname_copilot_short %} usage metrics APIs. Most tables below list the field name, its JSON type, whether the value can be null, and a description. -For example schemas of the data returned by the APIs, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/example-schema). +Reports come in different shapes depending on their scope and granularity, so the fields available in a record depend on which report it comes from: -| Field | Description | -|:--|:--| -| `agent_edit` | Captures lines added and deleted when {% data variables.product.prodname_copilot_short %} (in agent and edit mode) writes changes directly into your files in the IDE. `agent_edit` is not included in suggestion-based metrics and may not populate suggestion-style fields (for example, `user_initiated_interaction_count`). Counts edits from custom agents as well. | -| `report_start_day` / `report_end_day` | Start and end dates for the 28-day reporting period. | -| `day` | Calendar day this record represents. | -| `enterprise_id` | Unique ID of the enterprise. | -| `organization_id` (API only) | Unique ID of the organization. | -| `user_id` / `user_login` | Unique identifier and {% data variables.product.github %} username for the user. | -| `user_initiated_interaction_count` | Number of explicit prompts sent to {% data variables.product.prodname_copilot_short %}.

Only counts messages or prompts actively sent to the model. Does **not** include opening the chat panel, switching modes (for example, ask, edit, plan, or agent), using keyboard shortcuts to open the inline UI, or making configuration changes. | -| `chat_panel_agent_mode` | Captures user-initiated interactions in the chat panel with agent mode selected. | -| `chat_panel_ask_mode` | Captures user-initiated interactions in the chat panel with ask mode selected. | -| `chat_panel_custom_mode` | Captures user-initiated interactions in the chat panel with a custom agent selected. | -| `chat_panel_edit_mode` | Captures user-initiated interactions in the chat panel with edit mode selected. | -| `chat_panel_plan_mode` | Captures user-initiated interactions in the chat panel with plan mode selected. | -| `chat_panel_unknown_mode` | Captures user-initiated interactions in the chat panel where the mode is unknown. | -| `code_generation_activity_count` | Number of distinct {% data variables.product.prodname_copilot_short %} output events generated.

**Includes:** All generated content, including comments and docstrings.
**Multiple blocks:** Each distinct code block from a single user prompt counts as a separate generation.
**Note:** This metric is not directly comparable to `user_initiated_interaction_count`, since one prompt can produce multiple generations. | -| `code_acceptance_activity_count` | Number of suggestions or code blocks accepted by users.

**Counts:** All built-in accept actions, such as “apply to file,” “insert at cursor,” “insert into terminal,” and use of the **Copy** button.
**Does not count:** Manual OS clipboard actions (for example, Ctrl+C).
**Granularity:** Each acceptance action increments the count once, regardless of how many code blocks were generated by the initial prompt. | -| `loc_suggested_to_add_sum` | Lines of code {% data variables.product.prodname_copilot_short %} suggested to add (completions, inline chat, chat panel, etc.; **excludes** agent edits). | -| `loc_suggested_to_delete_sum` | Lines of code {% data variables.product.prodname_copilot_short %} suggested to delete (future support planned). | -| `loc_added_sum` | Lines of code actually added to the editor (accepted completions, applied code blocks, agent/edit mode). | -| `loc_deleted_sum` | Lines of code deleted from the editor (currently from agent edits). | -| `totals_by_ide` | Breakdown of metrics by IDE used. | -| `totals_by_feature` | Breakdown of metrics by {% data variables.product.prodname_copilot_short %} feature (e.g., inline chat, chat panel). | -| `totals_by_language_feature` | Breakdown combining language and feature dimensions. | -| `totals_by_model_feature` / `totals_by_language_model` | Model-specific breakdowns for chat activity (not completions). When {% data variables.copilot.copilot_auto_model_selection_short %} is enabled, activity is attributed to the actual model used rather than appearing as `Auto`. | -| `last_known_ide_version` / `last_known_plugin_version` | The most recent IDE and {% data variables.copilot.copilot_chat_short %} extension version detected for each user. | -| `daily_active_cli_users` | Number of unique users in the enterprise or organization who used {% data variables.product.prodname_copilot_short %} via the CLI on a given day. This field is **independent** of IDE active user counts and is **not** included in IDE-based active user definitions. Omitted for enterprises or organizations with no CLI usage on that day. | -| `daily_active_copilot_code_review_users` | Number of unique users who actively used {% data variables.copilot.copilot_code-review_short %} on a given day. Active usage means manually requesting a review or applying a suggestion. When a user has both active and passive signals in the same period, they are counted as active only. | -| `daily_passive_copilot_code_review_users` | Number of unique users who had {% data variables.copilot.copilot_code-review_short %} automatically assigned to review their pull request on a given day, with no active engagement. | -| `weekly_active_copilot_code_review_users` | Number of unique users who actively used {% data variables.copilot.copilot_code-review_short %} during a trailing seven-day window. When a user has both active and passive signals in the same period, they are counted as active only. | -| `weekly_passive_copilot_code_review_users` | Number of unique users who had {% data variables.copilot.copilot_code-review_short %} automatically assigned to review their pull request during a trailing seven-day window, with no active engagement. | -| `monthly_active_copilot_code_review_users` | Number of unique users who actively used {% data variables.copilot.copilot_code-review_short %} during a trailing 28-day window. When a user has both active and passive signals in the same period, they are counted as active only. | -| `monthly_passive_copilot_code_review_users` | Number of unique users who had {% data variables.copilot.copilot_code-review_short %} automatically assigned to review their pull request during a trailing 28-day window, with no active engagement. | -| `totals_by_cli` | Breakdown of CLI-specific metrics for the enterprise, organization, or user on a given day. Independent of IDE metrics—CLI usage is **not** reflected in other fields such as `totals_by_ide` or `totals_by_feature`. Omitted when there's no CLI usage on that day. See [{% data variables.copilot.copilot_cli_short %} metrics fields](#copilot-cli-metrics-fields-api-only) below. | -| `used_cli` | Captures whether the user has used {% data variables.copilot.copilot_cli_short %} that day. | -| `used_agent` | Captures whether the user has used agent mode in the IDE that day. Does not include {% data variables.copilot.copilot_code-review_short %} activity, which is captured separately in `used_copilot_code_review_active` and `used_copilot_code_review_passive`. | -| `used_chat` | Captures whether the user has used IDE chat that day. | -| `used_copilot_code_review_active` | Captures whether the user actively engaged with {% data variables.copilot.copilot_code-review_short %} that day. A user is considered active if they manually requested a {% data variables.product.prodname_copilot_short %} review, or applied a {% data variables.product.prodname_copilot_short %} review suggestion. | -| `used_copilot_code_review_passive` | Captures whether the user had {% data variables.product.prodname_copilot_short %} automatically assigned to review their pull request that day, without actively engaging with the review. | - -### {% data variables.copilot.copilot_cli_short %} metrics fields (API only) - -The `totals_by_cli` object contains the following nested fields when CLI usage is present. - -| Field | Description | -|:--|:--| -| `totals_by_cli.session_count` | Number of distinct CLI sessions initiated on this day. | -| `totals_by_cli.request_count` | Total number of requests made to {% data variables.product.prodname_copilot_short %} via the CLI on this day, including both user-initiated prompts and automated agentic follow-up calls. | -| `totals_by_cli.token_usage.output_tokens_sum` | Total number of output tokens generated across all CLI requests on this day. | -| `totals_by_cli.token_usage.prompt_tokens_sum` | Total number of prompt tokens sent across all CLI requests on this day. | -| `totals_by_cli.token_usage.avg_tokens_per_request` | Average number of **output** and **prompt** tokens per CLI request, computed as `(output_tokens_sum + prompt_tokens_sum) ÷ request_count`.| -| `totals_by_cli.prompt_count` | Total number of user prompts, commands, or queries executed within a session. | -| `totals_by_cli.last_known_cli_version` | Most recent {% data variables.copilot.copilot_cli_short %} version detected for the user that day. | +* **Per-user reports** (`*-users-1-day` and `*-users-28-day`) contain one record per user, including `user_id`, `user_login`, the `used_*` indicators, and `ai_adoption_phase`. They do not contain active-user counts, `pull_requests`, or `totals_by_ai_adoption_phase`. +* **Aggregated reports** (`enterprise-1-day` and `org-1-day`) contain one aggregated record per enterprise or organization, including active-user counts, `pull_requests`, and `totals_by_ai_adoption_phase`. They do not contain `user_id`, `user_login`, or the `used_*` indicators. +* **28-day reports** (`enterprise-28-day` and `org-28-day`) wrap an array of daily aggregated records in a `day_totals` field, with the reporting window at the top level. +* **User-teams reports** (`*-user-teams-1-day`) map users to the teams they belong to, so you can construct team-level metrics. -### Pull request activity fields (API only) +Organization-scope reports also include `organization_id` alongside `enterprise_id`. For example schemas of the data returned by the APIs, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/example-schema). -> [!IMPORTANT] -> Organization- and enterprise-level reports may show different totals due to differences in user deduplication and attribution timing. For guidance on interpreting pull request metrics across scopes, see [AUTOTITLE](/copilot/concepts/copilot-usage-metrics/copilot-metrics#interpreting-pull-request-lifecycle-metrics-across-scopes). +The **Type** column uses JSON Schema types: `string`, `integer`, `number`, `boolean`, `array`, and `object`. The **Nullable** column indicates whether a field's value can be `null` or absent from a record where it would otherwise apply. Arrays are always present but can be empty (`[]`), so they are not nullable. -These fields capture daily pull request creation, review, merge, and suggestion activity at the enterprise or organization scope, including activity performed by {% data variables.product.prodname_copilot_short %}. +### Report identification and partition fields -| Field | Description | -|:--|:--| -| `pull_requests.total_created` | Total number of pull requests created on this specific day.

Creation is a one-time event. Each pull request is counted only on the day it is created. | -| `pull_requests.total_reviewed` | Total number of pull requests reviewed on this specific day.

The same pull request may be counted on multiple days if it receives reviews on multiple days. Within a single day, each pull request is counted once, even if multiple review actions occur. | -| `pull_requests.total_merged` | Total number of pull requests merged on this specific day.

Merging is a one-time event. Each pull request is counted only on the day it is merged. | -| `pull_requests.median_minutes_to_merge` | Median time, in minutes, between pull request creation and merge for pull requests merged on this specific day.

Median is used to reduce the impact of outliers from unusually long-running pull requests. | -| `pull_requests.total_suggestions` | Total number of pull request review suggestions generated on this specific day, regardless of author. | -| `pull_requests.total_applied_suggestions` | Total number of pull request review suggestions that were applied on this specific day, regardless of author. | -| `pull_requests.total_created_by_copilot` | Number of pull requests created by {% data variables.product.prodname_copilot_short %} on this specific day. | -| `pull_requests.total_reviewed_by_copilot` | Number of pull requests reviewed by {% data variables.product.prodname_copilot_short %} on this specific day.

A pull request may be counted on multiple days if {% data variables.product.prodname_copilot_short %} reviews it on multiple days. | -| `pull_requests.total_merged_created_by_copilot` | Number of pull requests created by {% data variables.product.prodname_copilot_short %} that were merged on this specific day. Each pull request is counted only on the day it is merged. | -| `pull_requests.total_merged_reviewed_by_copilot` | Number of pull requests that were both merged and reviewed by {% data variables.copilot.copilot_code-review_short %} during the reporting period. | -| `pull_requests.median_minutes_to_merge_copilot_authored` | Median time, in minutes, between pull request creation and merge for pull requests created by {% data variables.product.prodname_copilot_short %} and merged on this specific day. | -| `pull_requests.median_minutes_to_merge_copilot_reviewed` | Median time, in minutes, between pull request creation and merge, calculated only for pull requests reviewed by {% data variables.copilot.copilot_code-review_short %}. | -| `pull_requests.total_copilot_suggestions` | Number of pull request review suggestions generated by {% data variables.product.prodname_copilot_short %} on this specific day. | -| `pull_requests.total_copilot_applied_suggestions` | Number of pull request review suggestions generated by {% data variables.product.prodname_copilot_short %} that were applied on this specific day. | -| `pull_requests.copilot_suggestions_by_comment_type` | Aggregated counts of {% data variables.product.prodname_copilot_short %} code review suggestions, broken down by the comment type {% data variables.product.prodname_copilot_short %} assigned (for example, `security` or `bug_risk`). Each entry includes `comment_type`, `total_copilot_suggestions`, and `total_copilot_applied_suggestions`. Not available at the repository level. | - -### User-teams fields (API only) +These fields identify the scope, date, and (for exports) partition of each record. The exact set present depends on the report shape. + +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `day` | `string` | No | Calendar day this record represents, in `YYYY-MM-DD` format. In 28-day reports, `day` appears within each `day_totals` entry rather than at the top level. | +| `enterprise_id` | `string` | No | Unique ID of the enterprise. Included in both enterprise- and organization-scope reports. | +| `organization_id` | `string` | Yes | Unique ID of the organization. Included in organization-scope reports only; omitted from enterprise-scope reports. | +| `etl_id` / `day_partition` | `string` | No | Partition fields used for housekeeping. Included in exported NDJSON files and returned by the usage metrics APIs. | +| `entity_id_partition` | `integer` | No | Entity partition used for housekeeping. Included in exported NDJSON files and returned by the usage metrics APIs. | + +### Per-user report fields + +Per-user reports contain one record per user for the reporting period. The 28-day per-user report also includes `report_start_day` and `report_end_day` to mark the reporting window. + +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `user_id` | `integer` | No | Unique identifier for the user. | +| `user_login` | `string` | No | {% data variables.product.github %} username for the user. | +| `user_initiated_interaction_count` | `integer` | No | Number of explicit prompts sent to {% data variables.product.prodname_copilot_short %}.

Only counts messages or prompts actively sent to the model. Does **not** include opening the chat panel, switching modes (for example, ask, edit, plan, or agent), using keyboard shortcuts to open the inline UI, or making configuration changes. | +| `code_generation_activity_count` | `integer` | No | Number of distinct {% data variables.product.prodname_copilot_short %} output events generated.

**Includes:** All generated content, including comments and docstrings.
**Multiple blocks:** Each distinct code block from a single user prompt counts as a separate generation.
**Note:** This metric is not directly comparable to `user_initiated_interaction_count`, since one prompt can produce multiple generations. | +| `code_acceptance_activity_count` | `integer` | No | Number of suggestions or code blocks accepted by users.

**Counts:** All built-in accept actions, such as “apply to file,” “insert at cursor,” “insert into terminal,” and use of the **Copy** button.
**Does not count:** Manual OS clipboard actions (for example, Ctrl+C).
**Granularity:** Each acceptance action increments the count once, regardless of how many code blocks were generated by the initial prompt. | +| `loc_suggested_to_add_sum` | `integer` | No | Lines of code {% data variables.product.prodname_copilot_short %} suggested to add (completions, inline chat, chat panel, and so on; **excludes** agent edits). | +| `loc_suggested_to_delete_sum` | `integer` | No | Lines of code {% data variables.product.prodname_copilot_short %} suggested to delete (future support planned). | +| `loc_added_sum` | `integer` | No | Lines of code actually added to the editor (accepted completions, applied code blocks, agent and edit mode). | +| `loc_deleted_sum` | `integer` | No | Lines of code deleted from the editor (currently from agent edits). | +| `used_agent` | `boolean` | No | Whether the user used agent mode in the IDE that day. Does not include {% data variables.copilot.copilot_code-review_short %} activity, which is captured separately in `used_copilot_code_review_active` and `used_copilot_code_review_passive`. | +| `used_chat` | `boolean` | No | Whether the user used IDE chat that day. | +| `used_cli` | `boolean` | No | Whether the user used {% data variables.copilot.copilot_cli_short %} that day. | +| `used_copilot_coding_agent` | `boolean` | No | Whether the user used {% data variables.copilot.copilot_cloud_agent %} (previously Copilot coding agent) that day. | +| `used_copilot_cloud_agent` | `boolean` | No | Whether the user used {% data variables.copilot.copilot_cloud_agent %} that day. Carries the same value as `used_copilot_coding_agent`; both names are retained for backward compatibility. | +| `used_copilot_code_review_active` | `boolean` | Yes | Whether the user actively engaged with {% data variables.copilot.copilot_code-review_short %} that day. A user is considered active if they manually requested a {% data variables.product.prodname_copilot_short %} review, or applied a {% data variables.product.prodname_copilot_short %} review suggestion. Null when there is no {% data variables.copilot.copilot_code-review_short %} signal for the user that day. | +| `used_copilot_code_review_passive` | `boolean` | Yes | Whether the user had {% data variables.product.prodname_copilot_short %} automatically assigned to review their pull request that day, without actively engaging with the review. Null when there is no {% data variables.copilot.copilot_code-review_short %} signal for the user that day. | +| `ai_adoption_phase` | `object` | No | The user's AI adoption phase for the day. Always present; defaults to the "No Cohort" phase. See [AI adoption phase fields](#ai-adoption-phase-fields). | +| `totals_by_cli` | `object` | Yes | CLI-specific metrics for the user. Omitted when the user had no {% data variables.copilot.copilot_cli_short %} usage that day. See [{% data variables.copilot.copilot_cli_short %} metrics fields](#copilot-cli-metrics-fields). | +| `totals_by_ide` | `array` | No | Per-IDE breakdown of the user's activity. See [Activity breakdown objects](#activity-breakdown-objects). | +| `totals_by_feature` | `array` | No | Per-feature breakdown of the user's activity. See [Activity breakdown objects](#activity-breakdown-objects). | +| `totals_by_language_feature` | `array` | No | Breakdown combining language and feature dimensions. See [Activity breakdown objects](#activity-breakdown-objects). | +| `totals_by_language_model` | `array` | No | Breakdown combining language and model dimensions, for chat activity. See [Activity breakdown objects](#activity-breakdown-objects). | +| `totals_by_model_feature` | `array` | No | Breakdown combining model and feature dimensions, for chat activity. See [Activity breakdown objects](#activity-breakdown-objects). | + +### Aggregated enterprise and organization report fields + +Aggregated reports contain one record per enterprise or organization, summarizing all users for the day. The following tables list the active-user counts, then the activity totals and breakdowns. + +Active-user counts: + +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `daily_active_users` | `integer` | No | Number of unique users who used {% data variables.product.prodname_copilot_short %} on a given day. | +| `weekly_active_users` | `integer` | No | Number of unique users who used {% data variables.product.prodname_copilot_short %} during a trailing seven-day window. | +| `monthly_active_users` | `integer` | No | Number of unique users who used {% data variables.product.prodname_copilot_short %} during a trailing 28-day window. | +| `monthly_active_chat_users` | `integer` | No | Number of unique users who used chat during a trailing 28-day window. | +| `monthly_active_agent_users` | `integer` | No | Number of unique users who used agent mode during a trailing 28-day window. | +| `daily_active_copilot_cloud_agent_users` | `integer` | No | Number of unique users who used {% data variables.copilot.copilot_cloud_agent %} on a given day. | +| `weekly_active_copilot_cloud_agent_users` | `integer` | No | Number of unique users who used {% data variables.copilot.copilot_cloud_agent %} during a trailing seven-day window. | +| `monthly_active_copilot_cloud_agent_users` | `integer` | No | Number of unique users who used {% data variables.copilot.copilot_cloud_agent %} during a trailing 28-day window. | +| `daily_active_copilot_code_review_users` | `integer` | No | Number of unique users who actively used {% data variables.copilot.copilot_code-review_short %} on a given day. Active usage means manually requesting a review or applying a suggestion. When a user has both active and passive signals in the same period, they are counted as active only. | +| `weekly_active_copilot_code_review_users` | `integer` | No | Number of unique users who actively used {% data variables.copilot.copilot_code-review_short %} during a trailing seven-day window. When a user has both active and passive signals in the same period, they are counted as active only. | +| `monthly_active_copilot_code_review_users` | `integer` | No | Number of unique users who actively used {% data variables.copilot.copilot_code-review_short %} during a trailing 28-day window. When a user has both active and passive signals in the same period, they are counted as active only. | +| `daily_passive_copilot_code_review_users` | `integer` | No | Number of unique users who had {% data variables.copilot.copilot_code-review_short %} automatically assigned to review their pull request on a given day, with no active engagement. | +| `weekly_passive_copilot_code_review_users` | `integer` | No | Number of unique users who had {% data variables.copilot.copilot_code-review_short %} automatically assigned to review their pull request during a trailing seven-day window, with no active engagement. | +| `monthly_passive_copilot_code_review_users` | `integer` | No | Number of unique users who had {% data variables.copilot.copilot_code-review_short %} automatically assigned to review their pull request during a trailing 28-day window, with no active engagement. | +| `daily_active_cli_users` | `integer` | Yes | Number of unique users who used {% data variables.copilot.copilot_cli_short %} on a given day. This count is **independent** of IDE active-user counts and is **not** included in IDE-based active-user definitions. Omitted for enterprises or organizations with no CLI usage that day. | + +Activity totals and breakdowns: + +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `user_initiated_interaction_count` | `integer` | No | Total number of explicit prompts sent to {% data variables.product.prodname_copilot_short %} across all users for the day. | +| `code_generation_activity_count` | `integer` | No | Total number of distinct {% data variables.product.prodname_copilot_short %} output events generated across all users for the day. | +| `code_acceptance_activity_count` | `integer` | No | Total number of suggestions or code blocks accepted across all users for the day. | +| `loc_suggested_to_add_sum` | `integer` | No | Aggregated lines of code suggested to add for the day. Same definition as the per-user field. | +| `loc_suggested_to_delete_sum` | `integer` | No | Aggregated lines of code suggested to delete for the day. Same definition as the per-user field. | +| `loc_added_sum` | `integer` | No | Aggregated lines of code added for the day. Same definition as the per-user field. | +| `loc_deleted_sum` | `integer` | No | Aggregated lines of code deleted for the day. Same definition as the per-user field. | +| `totals_by_ide` | `array` | No | Aggregated per-IDE activity breakdown. See [Activity breakdown objects](#activity-breakdown-objects). | +| `totals_by_feature` | `array` | No | Aggregated per-feature activity breakdown. See [Activity breakdown objects](#activity-breakdown-objects). | +| `totals_by_language_feature` | `array` | No | Aggregated language-and-feature activity breakdown. See [Activity breakdown objects](#activity-breakdown-objects). | +| `totals_by_language_model` | `array` | No | Aggregated language-and-model activity breakdown. See [Activity breakdown objects](#activity-breakdown-objects). | +| `totals_by_model_feature` | `array` | No | Aggregated model-and-feature activity breakdown. See [Activity breakdown objects](#activity-breakdown-objects). | +| `totals_by_cli` | `object` | Yes | Aggregated {% data variables.copilot.copilot_cli_short %} metrics for the day. Omitted when there is no CLI usage that day. Unlike the per-user form, it does not include `last_known_cli_version`. See [{% data variables.copilot.copilot_cli_short %} metrics fields](#copilot-cli-metrics-fields). | +| `totals_by_ai_adoption_phase` | `array` | Yes | Per-phase aggregates of users and their average activity. Omitted when no adoption-phase data is available. See [AI adoption phase fields](#ai-adoption-phase-fields). | +| `pull_requests` | `object` | No | Daily pull request activity for the enterprise or organization. See [Pull request activity fields](#pull-request-activity-fields). | + +### 28-day report fields + +The 28-day reports (`enterprise-28-day` and `org-28-day`) are wrappers: they carry the reporting window at the top level and an array of daily aggregated records. + +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `report_start_day` | `string` | No | First calendar day of the 28-day reporting window, in `YYYY-MM-DD` format. | +| `report_end_day` | `string` | No | Last calendar day of the 28-day reporting window, in `YYYY-MM-DD` format. | +| `created_at` | `string` | No | Timestamp (ISO 8601) when the report was generated. | +| `day_totals` | `array` | No | Array of daily aggregated records. Each entry has the same fields as an aggregated 1-day report. See [Aggregated enterprise and organization report fields](#aggregated-enterprise-and-organization-report-fields). | + +### User-teams fields These fields appear in the daily user-teams report (available via REST API at the organization and enterprise scopes) and are used to construct team-level metrics by joining with the per-user usage metrics report. For the full join recipe and the endpoint URLs, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics). Teams with fewer than 5 seated {% data variables.product.prodname_copilot_short %} users on a given day are excluded from the user-teams report. -| Field | Description | +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `user_id` | `integer` | No | Unique identifier for the user. | +| `user_login` | `string` | No | {% data variables.product.github %} username for the user. | +| `day` | `string` | No | Calendar day this record represents. | +| `organization_id` | `string` | No | Unique ID of the organization the team belongs to. Organization scope only. | +| `enterprise_id` | `string` | No | Unique ID of the enterprise the team belongs to. Enterprise scope only. The enterprise-scoped report includes both enterprise teams and business teams. | +| `team_id` | `integer` | No | Unique ID of the team the user belongs to. | +| `slug` | `string` | No | URL-friendly identifier for the team. | + +### Activity breakdown objects + +The `totals_by_*` fields are arrays of breakdown objects. The array is always present but can be empty. Within each object, the metric fields (`*_count` and `loc_*_sum`) follow the same definitions as the top-level per-user fields, and the dimension fields carry the values documented in [Breakdown dimension values](#breakdown-dimension-values). + +| Object | Dimension fields | Description | +|:--|:--|:--| +| `totals_by_ide[]` | `ide` | Breakdown by IDE. In per-user reports, each entry also includes `last_known_ide_version` and `last_known_plugin_version`. | +| `totals_by_feature[]` | `feature` | Breakdown by {% data variables.product.prodname_copilot_short %} feature (for example, inline chat or chat panel). | +| `totals_by_language_feature[]` | `language`, `feature` | Breakdown combining language and feature. Does not include `user_initiated_interaction_count`. | +| `totals_by_language_model[]` | `language`, `model` | Breakdown combining language and model, for chat activity (not completions). | +| `totals_by_model_feature[]` | `model`, `feature` | Breakdown combining model and feature, for chat activity (not completions). | + +In per-user reports, each `totals_by_ide[]` entry also reports the most recently detected IDE and {% data variables.copilot.copilot_chat_short %} extension versions for the user. + +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `last_known_ide_version` | `object` | Yes | Most recent IDE version detected for the user, as `{ ide_version, sampled_at }`. Omitted for aggregated breakdown rows, such as the capped "others" IDE bucket. | +| `last_known_ide_version.ide_version` | `string` | No | IDE version string. Present when `last_known_ide_version` is present. | +| `last_known_ide_version.sampled_at` | `string` | Yes | Timestamp (ISO 8601) when the version was sampled. | +| `last_known_plugin_version` | `object` | Yes | Most recent {% data variables.product.prodname_copilot_short %} extension detected for the user, as `{ plugin, plugin_version, sampled_at }`. Omitted for aggregated breakdown rows. | +| `last_known_plugin_version.plugin` | `string` | No | Extension name (for example, `copilot` or `copilot-chat`). Present when `last_known_plugin_version` is present. | +| `last_known_plugin_version.plugin_version` | `string` | No | Extension version string. Present when `last_known_plugin_version` is present. | +| `last_known_plugin_version.sampled_at` | `string` | Yes | Timestamp (ISO 8601) when the version was sampled. | + +### {% data variables.copilot.copilot_cli_short %} metrics fields + +The `totals_by_cli` object contains the following nested fields when {% data variables.copilot.copilot_cli_short %} usage is present; the object is omitted when there is no CLI usage. CLI usage is independent of IDE metrics—it is **not** reflected in fields such as `totals_by_ide` or `totals_by_feature`. The `last_known_cli_version` object appears in per-user reports only. + +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `totals_by_cli.session_count` | `integer` | No | Number of distinct CLI sessions initiated on this day. | +| `totals_by_cli.request_count` | `integer` | No | Total number of requests made to {% data variables.product.prodname_copilot_short %} via the CLI on this day, including both user-initiated prompts and automated agentic follow-up calls. | +| `totals_by_cli.prompt_count` | `integer` | No | Total number of user prompts, commands, or queries executed within a session. | +| `totals_by_cli.token_usage.output_tokens_sum` | `integer` | No | Total number of output tokens generated across all CLI requests on this day. | +| `totals_by_cli.token_usage.prompt_tokens_sum` | `integer` | No | Total number of prompt tokens sent across all CLI requests on this day. | +| `totals_by_cli.token_usage.avg_tokens_per_request` | `number` | Yes | Average number of **output** and **prompt** tokens per CLI request, computed as `(output_tokens_sum + prompt_tokens_sum) ÷ request_count`. Null when there were no requests that day. | +| `totals_by_cli.last_known_cli_version` | `object` | No | Most recent {% data variables.copilot.copilot_cli_short %} version detected for the user that day, as `{ cli_version, sampled_at }`. Per-user reports only. | +| `totals_by_cli.last_known_cli_version.cli_version` | `string` | No | {% data variables.copilot.copilot_cli_short %} version string. Defaults to `unknown` if no version was detected. | +| `totals_by_cli.last_known_cli_version.sampled_at` | `string` | Yes | Timestamp (ISO 8601) when the version was sampled. | + +### Pull request activity fields + +> [!IMPORTANT] +> Organization- and enterprise-level reports may show different totals due to differences in user deduplication and attribution timing. For guidance on interpreting pull request metrics across scopes, see [AUTOTITLE](/copilot/concepts/copilot-usage-metrics/copilot-metrics#interpreting-pull-request-lifecycle-metrics-across-scopes). + +The `pull_requests` object appears in aggregated enterprise and organization reports only. It captures daily pull request creation, review, merge, and suggestion activity at the enterprise or organization scope, including activity performed by {% data variables.product.prodname_copilot_short %}. + +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `pull_requests.total_created` | `integer` | No | Total number of pull requests created on this specific day.

Creation is a one-time event. Each pull request is counted only on the day it is created. | +| `pull_requests.total_reviewed` | `integer` | No | Total number of pull requests reviewed on this specific day.

The same pull request may be counted on multiple days if it receives reviews on multiple days. Within a single day, each pull request is counted once, even if multiple review actions occur. | +| `pull_requests.total_merged` | `integer` | No | Total number of pull requests merged on this specific day.

Merging is a one-time event. Each pull request is counted only on the day it is merged. | +| `pull_requests.median_minutes_to_merge` | `number` | Yes | Median time, in minutes, between pull request creation and merge for pull requests merged on this specific day.

Median is used to reduce the impact of outliers from unusually long-running pull requests. Null when no pull requests were merged that day. | +| `pull_requests.total_suggestions` | `integer` | No | Total number of pull request review suggestions generated on this specific day, regardless of author. | +| `pull_requests.total_applied_suggestions` | `integer` | No | Total number of pull request review suggestions that were applied on this specific day, regardless of author. | +| `pull_requests.total_created_by_copilot` | `integer` | No | Number of pull requests created by {% data variables.product.prodname_copilot_short %} on this specific day. | +| `pull_requests.total_reviewed_by_copilot` | `integer` | No | Number of pull requests reviewed by {% data variables.product.prodname_copilot_short %} on this specific day.

A pull request may be counted on multiple days if {% data variables.product.prodname_copilot_short %} reviews it on multiple days. | +| `pull_requests.total_merged_created_by_copilot` | `integer` | No | Number of pull requests created by {% data variables.product.prodname_copilot_short %} that were merged on this specific day. Each pull request is counted only on the day it is merged. | +| `pull_requests.total_merged_reviewed_by_copilot` | `integer` | No | Number of pull requests that were both merged and reviewed by {% data variables.copilot.copilot_code-review_short %} during the reporting period. | +| `pull_requests.median_minutes_to_merge_copilot_authored` | `number` | Yes | Median time, in minutes, between pull request creation and merge for pull requests created by {% data variables.product.prodname_copilot_short %} and merged on this specific day. Null when no such pull requests were merged that day. | +| `pull_requests.median_minutes_to_merge_copilot_reviewed` | `number` | Yes | Median time, in minutes, between pull request creation and merge, calculated only for pull requests reviewed by {% data variables.copilot.copilot_code-review_short %}. Null when no such pull requests were merged that day. | +| `pull_requests.total_copilot_suggestions` | `integer` | No | Number of pull request review suggestions generated by {% data variables.product.prodname_copilot_short %} on this specific day. | +| `pull_requests.total_copilot_applied_suggestions` | `integer` | No | Number of pull request review suggestions generated by {% data variables.product.prodname_copilot_short %} that were applied on this specific day. | +| `pull_requests.copilot_suggestions_by_comment_type` | `array` | No | Aggregated counts of {% data variables.product.prodname_copilot_short %} code review suggestions, broken down by the comment type {% data variables.product.prodname_copilot_short %} assigned (for example, `security` or `bug_risk`). Each entry includes `comment_type`, `total_copilot_suggestions`, and `total_copilot_applied_suggestions`. Always present but can be empty. Not available at the repository level. | + +### AI adoption phase fields + +{% data variables.product.prodname_copilot_short %} groups users into AI adoption phases based on their activity. Phase information appears in two places: the per-user `ai_adoption_phase` object, and the aggregated `totals_by_ai_adoption_phase` array. For the phase values, see [Breakdown dimension values](#breakdown-dimension-values). + +The per-user `ai_adoption_phase` object contains: + +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `ai_adoption_phase.phase_number` | `integer` | No | Numeric phase identifier (for example, `0` for "No Cohort"). | +| `ai_adoption_phase.phase` | `string` | No | Human-readable phase name. | +| `ai_adoption_phase.version` | `string` | No | Version of the adoption-phase model used (for example, `v1`). | + +Each entry in the aggregated `totals_by_ai_adoption_phase` array contains: + +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `phase` | `string` | No | Human-readable phase name. | +| `phase_number` | `integer` | No | Numeric phase identifier. | +| `total_engaged_users` | `integer` | No | Number of users grouped into this phase for the period. | +| `avg_user_initiated_interactions` | `number` | No | Average user-initiated interactions per user in this phase. | +| `avg_code_generation_activities` | `number` | No | Average code generation activities per user in this phase. | +| `avg_code_acceptance_activities` | `number` | No | Average code acceptance activities per user in this phase. | +| `avg_loc_added` | `number` | No | Average lines of code added per user in this phase. | +| `avg_loc_deleted` | `number` | No | Average lines of code deleted per user in this phase. | +| `avg_pull_requests_reviewed` | `number` | No | Average pull requests reviewed per user in this phase. | +| `avg_pull_requests_created` | `number` | No | Average pull requests created per user in this phase. | +| `avg_pull_requests_merged` | `number` | No | Average pull requests merged per user in this phase. | +| `avg_pull_requests_median_minutes_to_merge` | `number` | No | Average of the per-user median minutes to merge for users in this phase. | + +### Breakdown dimension values + +The breakdown objects above use dimension fields whose values come from fixed sets. These are field **values**, not separate fields. For example, `agent_edit` and the `chat_panel_*_mode` values are values of the `feature` field, not top-level fields. + +The `feature` dimension identifies the {% data variables.product.prodname_copilot_short %} feature or mode an activity is attributed to: + +| Value | Description | |:--|:--| -| `user_id` / `user_login` | Unique identifier and {% data variables.product.github %} username for the user. | -| `day` | Calendar day this record represents. | -| `organization_id` (organization scope) | Unique ID of the organization the team belongs to. | -| `enterprise_id` (enterprise scope) | Unique ID of the enterprise the team belongs to. The enterprise-scoped report includes both enterprise teams and business teams. | -| `team_id` | Unique ID of the team the user belongs to. | -| `slug` | URL-friendly identifier for the team. | +| `code_completion` | Inline code completions. | +| `chat_inline` | Inline chat in the editor. | +| `chat_panel_ask_mode` | Chat panel interactions with ask mode selected. | +| `chat_panel_edit_mode` | Chat panel interactions with edit mode selected. | +| `chat_panel_agent_mode` | Chat panel interactions with agent mode selected. | +| `chat_panel_plan_mode` | Chat panel interactions with plan mode selected. | +| `chat_panel_custom_mode` | Chat panel interactions with a custom agent selected. | +| `chat_panel_unknown_mode` | Chat panel interactions where the mode is unknown. | +| `agent_edit` | Lines added and deleted when {% data variables.product.prodname_copilot_short %} (in agent and edit mode) writes changes directly into your files in the IDE. Counts edits from custom agents as well. `agent_edit` is not included in suggestion-based metrics and may not populate suggestion-style fields, such as `user_initiated_interaction_count`. | +| `copilot_cli` | Activity attributed to {% data variables.copilot.copilot_cli_short %}. | +| `others` | Any feature not covered by the values above. | + +The `ide` dimension identifies the IDE an activity occurred in. This is not an exhaustive list, but examples of observed values include `vscode`, `visualstudio`, `intellij`, `eclipse`, `xcode`, `neovim`, `vim`, `emacs`, and `zed`. + +The `model` dimension identifies the AI model used for chat activity. Values include specific model identifiers (for example, `gpt-5.4` or `claude-sonnet-4.6`), `auto`, `unknown`, and `others`. The `auto` value represents activity where {% data variables.copilot.copilot_auto_model_selection_short %} was used and the request was not attributed to a specific model. + +The `phase` dimension identifies the AI adoption phase a user is grouped into: `No Cohort`, `Phase 1`, `Phase 2`, or `Phase 3`. From 636f93141caae36434a8838fa95ac97a5fd6b8a9 Mon Sep 17 00:00:00 2001 From: Claire W <78226508+crwaters16@users.noreply.github.com> Date: Sat, 13 Jun 2026 08:19:16 -0500 Subject: [PATCH 2/6] Copilot: Updating Fable ability following Anthropic's announcement (#61724) Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- content/copilot/reference/copilot-billing/models-and-pricing.md | 2 ++ data/reusables/copilot/model-fable-disabled.md | 1 + 2 files changed, 3 insertions(+) create mode 100644 data/reusables/copilot/model-fable-disabled.md diff --git a/content/copilot/reference/copilot-billing/models-and-pricing.md b/content/copilot/reference/copilot-billing/models-and-pricing.md index 79393e32e839..87b5c0f23e7b 100644 --- a/content/copilot/reference/copilot-billing/models-and-pricing.md +++ b/content/copilot/reference/copilot-billing/models-and-pricing.md @@ -43,6 +43,8 @@ All prices are **per 1 million tokens**. Anthropic models include a cache write cost in addition to cached input. +{% data reusables.copilot.model-fable-disabled %} + | Model | Release status | Category | Input | Cached input | Cache write | Output | | --- | --- | --- | ---: | ---: | ---: | ---: | | {% for entry in tables.copilot.models-and-pricing %}{% if entry.provider == "anthropic" %} | diff --git a/data/reusables/copilot/model-fable-disabled.md b/data/reusables/copilot/model-fable-disabled.md new file mode 100644 index 000000000000..3fe3c546eba8 --- /dev/null +++ b/data/reusables/copilot/model-fable-disabled.md @@ -0,0 +1 @@ +> [!NOTE] Claude Fable 5 is currently unavailable. For more information, see [Anthropic's announcement](https://www.anthropic.com/news/fable-mythos-access). \ No newline at end of file From 48cafe3e6676acb0f6d963ba78ad361a526dcdbc Mon Sep 17 00:00:00 2001 From: Zareef Al Islam Date: Mon, 15 Jun 2026 06:08:40 -0400 Subject: [PATCH 3/6] Added copilot slowness troubleshooting guide (#61551) Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: zareefislam <186110388+zareefislam@users.noreply.github.com> Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com> --- .../how-tos/troubleshoot-copilot/index.md | 1 + .../troubleshoot-copilot-slowness.md | 74 +++++++++++++++++++ 2 files changed, 75 insertions(+) create mode 100644 content/copilot/how-tos/troubleshoot-copilot/troubleshoot-copilot-slowness.md diff --git a/content/copilot/how-tos/troubleshoot-copilot/index.md b/content/copilot/how-tos/troubleshoot-copilot/index.md index 99f43f2f4857..0db17c1bcf70 100644 --- a/content/copilot/how-tos/troubleshoot-copilot/index.md +++ b/content/copilot/how-tos/troubleshoot-copilot/index.md @@ -11,6 +11,7 @@ children: - /troubleshoot-firewall-settings - /troubleshoot-network-errors - /troubleshoot-spark + - /troubleshoot-copilot-slowness redirect_from: - /copilot/troubleshooting-github-copilot - /copilot/how-tos/troubleshoot diff --git a/content/copilot/how-tos/troubleshoot-copilot/troubleshoot-copilot-slowness.md b/content/copilot/how-tos/troubleshoot-copilot/troubleshoot-copilot-slowness.md new file mode 100644 index 000000000000..61a8fcde9213 --- /dev/null +++ b/content/copilot/how-tos/troubleshoot-copilot/troubleshoot-copilot-slowness.md @@ -0,0 +1,74 @@ +--- +title: Troubleshooting slow responses from GitHub Copilot +intro: Troubleshooting help for slow responses from {% data variables.product.prodname_copilot %}. +allowTitleToDifferFromFilename: true +versions: + feature: copilot +shortTitle: Troubleshoot slow responses +redirect_from: + - /copilot/troubleshooting-github-copilot/troubleshooting-copilot-slowness + - /copilot/how-tos/troubleshoot/troubleshooting-copilot-slowness + - /copilot/how-tos/troubleshoot/troubleshoot-copilot-slowness +contentType: how-tos +category: + - Troubleshooting Copilot +--- + +## About the problem + +If {% data variables.product.prodname_copilot %} is responding more slowly than expected, the problem may be related to network conditions, local system performance, editor configuration, or connectivity restrictions such as proxies or firewalls. Because {% data variables.product.prodname_copilot_short %} relies on remote services to generate responses, issues that affect communication with {% data variables.product.github %} services can reduce responsiveness or cause delays. The troubleshooting steps below can help you determine whether the problem is caused by your environment or by a broader service issue. + +If {% data variables.product.prodname_copilot_short %} is responding slowly, work through the following troubleshooting steps. + +## Check your internet connection + +Make sure you have a stable, high-speed internet connection. Slow or inconsistent connectivity can increase latency and affect how quickly {% data variables.product.prodname_copilot_short %} returns responses. + +## Check the GitHub status page + +Visit the [GitHub status page](https://www.githubstatus.com/) to confirm whether there is an ongoing incident affecting {% data variables.product.prodname_copilot_short %} or related GitHub services. + +## Update your editor and {% data variables.product.prodname_copilot_short %} extension + +Make sure your editor and the {% data variables.product.prodname_copilot_short %} extension or plugin are up to date. After updating, restart your editor. + +## Check for extension conflicts + +Temporarily disable other extensions or plugins, especially ones related to AI coding assistants, linting, formatting, or code analysis. Conflicts between extensions can sometimes affect editor responsiveness and make {% data variables.product.prodname_copilot_short %} appear slow. + +## Try a smaller or simpler file + +{% data variables.product.prodname_copilot_short %} may respond more slowly in very large files or in projects with high complexity. Test whether performance improves in a smaller file or after splitting large files into smaller units. + +## Test in a new project or workspace + +Open a new minimal project or workspace and test {% data variables.product.prodname_copilot_short %} there. If response times improve, the issue may be related to the size, dependencies, or configuration of your main project. + +## Review system resource usage + +Check CPU and memory usage on your machine. High system load or limited available resources can slow down your editor and affect how quickly {% data variables.product.prodname_copilot_short %} responds. + +## Check proxy, VPN, and firewall settings + +If you use a proxy, VPN, firewall, or security software that inspects web traffic, verify that it is not blocking or interfering with connections required by {% data variables.product.prodname_copilot_short %}. If you work behind a corporate proxy or firewall, you may need to review your organization's network configuration and make sure to follow [AUTOTITLE](/copilot/how-tos/troubleshoot-copilot/troubleshoot-firewall-settings). + +## Review logs for errors or timeouts + +Check your editor logs for errors, timeouts, or connectivity problems. + + * In **Visual Studio Code**, open the **Output** panel and select **GitHub Copilot** from the dropdown. + * In **JetBrains IDEs**, open the logs from the **Help** menu. + +For more information, see [AUTOTITLE](/copilot/how-tos/troubleshoot-copilot/view-logs?tool=vscode#viewing-and-collecting-log-files). Save any relevant logs if you need to report the problem. + +## Try a different network or device + +If possible, test {% data variables.product.prodname_copilot_short %} on a different network or another device. This can help determine whether the issue is specific to your current environment. + +## Check GitHub Docs and known issues + +Review [AUTOTITLE](/copilot/how-tos/troubleshoot-copilot/troubleshoot-common-issues), similar reports, or environment-specific guidance. + +## Contact GitHub Support with diagnostic details + +If the problem persists, collect relevant diagnostic information before contacting GitHub Support. Include your editor and {% data variables.product.prodname_copilot_short %} extension or plugin versions, steps to reproduce the problem, example files if available, and any related log messages or errors. From 861a53e1e359567c5e5fecf4da2ac2193df2eda8 Mon Sep 17 00:00:00 2001 From: docs-bot <77750099+docs-bot@users.noreply.github.com> Date: Mon, 15 Jun 2026 03:45:28 -0700 Subject: [PATCH 4/6] docs: update copilot-cli content from source docs (#61640) Co-authored-by: github-actions[bot] Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: hubwriter <54933897+hubwriter@users.noreply.github.com> Co-authored-by: hubwriter --- .../cli-command-reference.md | 14 +++-- content/copilot/reference/hooks-reference.md | 55 +++++++++++++++++++ src/content-pipelines/state/copilot-cli.sha | 2 +- 3 files changed, 65 insertions(+), 6 deletions(-) diff --git a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md index 10f3257a8f8a..78cecac225e3 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md @@ -196,6 +196,7 @@ Holding ↑ or ↓ accelerates scrolling after the first 1 | Command | Purpose | |-----------------------------------------------------|---------| | `/add-dir PATH` | Add a directory to the allowed list for file access. | +| `/after [DELAY PROMPT]`, `/after` | Schedule a non-recurring prompt, skill, or schedulable slash command for the current session (for example, `/after 30m remind me the time` or `/after 1h /chronicle standup`). With no arguments the schedule manager is displayed. {% data reusables.copilot.experimental %} | | `/agent` | Browse and select from available agents (if any). See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-custom-agents). | | `/ask QUESTION` | Ask a quick side question without adding to the conversation history. {% data reusables.copilot.experimental %} | | `/allow-all [on\|off\|show]`, `/yolo [on\|off\|show]` | Enable all permissions (tools, paths, and URLs). | @@ -209,8 +210,9 @@ Holding ↑ or ↓ accelerates scrolling after the first 1 | `/cwd`, `/cd [PATH]` | Change the working directory or display the current directory. | | `/delegate [PROMPT]` | Delegate changes to a remote repository with an AI-generated pull request. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/delegate-tasks-to-cca). | | `/diff` | Review changes in the current directory; auto-switches to branch diff when the working tree is clean (experimental). | -| `/downgrade ` | Download and restart into a specific CLI version. Available for team accounts. | +| `/downgrade VERSION` | Download and restart into a specific CLI version. Available for team accounts. | | `/env` | Show loaded environment details (instructions, MCP servers, skills, agents, plugins, LSPs, hooks, extensions). | +| `/every [INTERVAL PROMPT]`, `/every` | Schedule a recurring prompt, skill, or schedulable slash command for the current session (for example, `/every 1h run tests` or `/every 1d /chronicle standup`). With no arguments the schedule manager is displayed. {% data reusables.copilot.experimental %} | | `/exit`, `/quit` | Exit the CLI. | | `/extensions [manage\|mode]`, `/extension` | Manage CLI extensions. | | `/experimental [on\|off\|show]` | Toggle, set, or show experimental features. | @@ -255,7 +257,7 @@ Holding ↑ or ↓ accelerates scrolling after the first 1 | `/usage` | Display session usage metrics and statistics. | | `/user [show\|list\|switch]` | Manage the current {% data variables.product.github %} user. | | `/version` | Display version information and check for updates. | -| `/worktree [branch]`, `/move [branch]` | Create a new git worktree and switch to it, moving any uncommitted changes along. If you omit the branch name, a name is auto-generated from the conversation. Requires a git repository. {% data reusables.copilot.experimental %} | +| `/worktree [branch]`, `/move [branch]` | Create a new Git worktree and switch to it, moving any uncommitted changes along. If you omit the branch name, a name is auto-generated from the conversation. Requires a Git repository. {% data reusables.copilot.experimental %} | For a complete list of available slash commands enter `/help` in the CLI's interactive interface. @@ -311,7 +313,7 @@ For a complete list of available slash commands enter `/help` in the CLI's inter | `--output-format=FORMAT` | FORMAT can be `text` (default) or `json` (outputs JSONL: one JSON object per line). | | `-p PROMPT`, `--prompt=PROMPT` | Execute a prompt programmatically (exits after completion). See [AUTOTITLE](/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically). | | `--plan` | Start in plan mode. Shorthand for `--mode plan`. Cannot be combined with `--mode` or `--autopilot`. | -| `--plain-diff` | Disable rich diff rendering (syntax highlighting via the diff tool specified by your git config). | +| `--plain-diff` | Disable rich diff rendering (syntax highlighting via the diff tool specified by your Git config). | | `--plugin-dir=DIRECTORY` | Load a plugin from a local directory (can be used multiple times). | | `--remote` | Enable remote access to this session from {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_mobile %}. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely). | | `-r`, `--resume[=VALUE]` | Resume a previous interactive session by choosing from a list. Optionally specify a session ID, ID prefix, or session name. Name matching is exact and case-insensitive; falls back to the auto-generated summary when no explicit name matches. | @@ -426,6 +428,7 @@ copilot --allow-tool='MyMCP' | `COPILOT_ALLOW_ALL` | Set to `true` to allow all permissions automatically (equivalent to `--allow-all`). | | `COPILOT_AUTO_UPDATE` | Set to `false` to disable automatic updates. | | `COPILOT_CACHE_HOME` | Override the cache directory (used for marketplace caches, auto-update packages, and other ephemeral data). See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#changing-the-location-of-the-configuration-directory) for platform defaults. | +| `COPILOT_COMPUTER_USE_LINUX` | Set to opt in to the `computer-use` MCP server on Linux distributions that support it. The `computer-use` server is not available on Alpine Linux (musl libc). | | `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` | Comma-separated list of additional directories for custom instructions. | | `COPILOT_EDITOR` | Editor command for interactive editing (checked after `$VISUAL` and `$EDITOR`). Defaults to `vi` if none are set. | | `COPILOT_ENABLE_HTTP2` | Set to `1` or `true` to opt into HTTP/2 transport. HTTP/1.1 is the default. | @@ -615,6 +618,7 @@ The CLI includes built-in MCP servers that are available without additional setu | `playwright` | Browser automation: navigate, click, type, screenshot, and form handling. | | `fetch` | HTTP requests via the `fetch` tool. | | `time` | Time utilities: `get_current_time` and `convert_time`. | +| `computer-use` | Screen capture and mouse/keyboard automation. Not available on Alpine Linux (musl libc). Set `COPILOT_COMPUTER_USE_LINUX` to opt in on other Linux distributions where it is available. | Use `--disable-builtin-mcps` to disable all built-in servers, or `--disable-mcp-server SERVER-NAME` to disable a specific one. @@ -764,7 +768,7 @@ Custom agents are specialized AI agents defined in Markdown files. The filename | User | `~/.copilot/agents/` | | Plugin | `/agents/` | -Project-level agents take precedence over user-level agents. Plugin agents have the lowest priority. +For project-scoped agents, the CLI walks upward from your current working directory to the Git root, loading `.github/agents/` and `.claude/agents/` directories at each ancestor level. This means each package or subdirectory in a monorepo can contribute its own agents. When multiple `.github/agents/` directories exist in the path, all are loaded, with the deepest directory taking highest priority. The `.github/agents/` convention takes precedence over `.claude/agents/` at the same level. User-level agents have lower priority than project-level agents. Plugin agents have the lowest priority. ### Subagent limits @@ -797,7 +801,7 @@ When the full dialog is shown, you can also choose from these options: | This location | Until manually cleared | Saved to disk per location | | Always | Permanent | Config file | -The **This location** option appears when the CLI can determine a location key (git root or current directory). It persists the approval to disk so the same permission is automatically granted the next time you work in that directory without prompting again. +The **This location** option appears when the CLI can determine a location key (Git root or current directory). It persists the approval to disk so the same permission is automatically granted the next time you work in that directory without prompting again. Use `/permissions reset` to clear in-memory approvals for the current session. diff --git a/content/copilot/reference/hooks-reference.md b/content/copilot/reference/hooks-reference.md index d8bde2b684fc..3b931dab5e87 100644 --- a/content/copilot/reference/hooks-reference.md +++ b/content/copilot/reference/hooks-reference.md @@ -115,6 +115,34 @@ Command hooks run shell scripts and are supported on all hook types. | `timeoutSec` | number | No | Timeout in seconds. Default: `30`. | | `type` | `"command"` | No | Hook type. Defaults to `"command"` when omitted. | +#### Progress messages + +Command hooks can emit progress status lines to the CLI timeline while executing. Write a `{"type": "progress", "message": "..."}` JSON object to stdout before writing the final output: + +```bash +echo '{"type": "progress", "message": "Checking policy..."}' +# ... perform work ... +echo '{"permissionDecision": "allow"}' +``` + +Set `"temporary": true` to emit a transient status line. A transient line replaces the previous transient line and is cleared when the assistant responds, instead of accumulating in the timeline: + +```bash +echo '{"type": "progress", "message": "Routing...", "temporary": true}' +echo '{"type": "progress", "message": "Thinking...", "temporary": true}' +# ... perform work ... +echo '{"permissionDecision": "allow"}' +``` + +Progress messages are display-only and do not affect hook output or decision logic. + +**How stdout is parsed when progress messages are mixed in.** — The CLI scans stdout line-by-line as the hook runs. Any line that, after trimming, is a single complete JSON object with `"type": "progress"` is consumed as a progress event and **removed from the hook's output stream**. Every other line—blank lines, plain text, and JSON objects that are not progress messages—is preserved verbatim. When the hook exits, the preserved lines are concatenated, trimmed, and parsed with a single `JSON.parse` call: that result is the hook's output (the "hook output JSON" referenced elsewhere in this article). This means: + +* Emitting progress lines alongside a final decision object (as in the examples above) is safe and is the intended pattern—the progress lines never reach the JSON parser. +* Each progress message must be on its own line and must be valid JSON on that single line. Multi-line / pretty-printed progress objects are not recognized as progress and will be left in the output stream, where they will likely cause the final `JSON.parse` to fail. +* The final decision object, by contrast, may span multiple lines—only progress *recognition* is line-oriented; what remains after progress stripping is parsed as one JSON document, not as line-delimited JSON. +* If the leftover output is empty, or fails to parse as JSON, the hook is treated as having produced no output and falls through to default behavior. Two or more non-progress JSON objects on stdout (for example, two `echo '{"permissionDecision": ...}'` calls) will therefore concatenate into invalid JSON and be ignored—emit exactly one final decision object. + ### HTTP hooks HTTP hooks send the input payload as a JSON `POST` to a URL. @@ -311,6 +339,30 @@ When configured with the PascalCase event name `PreToolUse`, the payload uses sn } ``` +**Claude-format matchers (PascalCase `PreToolUse`):** Hooks configured with the PascalCase event name `PreToolUse`—as used in Claude Code plugins and the Open Plugins format—apply Claude's matcher semantics instead of the native regex rule: + +* `*`, `**`, or an empty matcher fires for every tool. +* A literal name or `|`-separated alternation (for example, `Bash` or `Edit|Write`) fires when any token equals the runtime tool name or its Claude tool name from the table below. +* Any other value is treated as a case-sensitive regex anchored as `^(?:pattern)$` tested against the Claude tool name (or the runtime name for tools with no Claude equivalent). + +Payloads for PascalCase `PreToolUse` report `tool_name` as the Claude tool name (for example, `Bash`, not `bash`). + +| Runtime tool | Claude tool name | +|---|---| +| `bash`, `powershell` | `Bash` | +| `view` | `Read` | +| `create` | `Write` | +| `edit`, `str_replace_editor`, `apply_patch` | `Edit` | +| `grep`, `rg` | `Grep` | +| `glob` | `Glob` | +| `web_fetch` | `WebFetch` | +| `web_search` | `WebSearch` | +| `ask_user` | `AskUserQuestion` | +| `update_todo` | `TodoWrite` | +| `task` | `Agent` (the literal `Task` is also accepted) | + +Tools with no Claude equivalent keep their runtime names. + > [!IMPORTANT] > **Command vs HTTP fail behavior for `preToolUse`:** Command `preToolUse` hooks are **fail-closed**—a crash or non-zero exit denies the tool call. HTTP `preToolUse` hooks are **fail-open**—a network error, timeout, or non-2xx response falls through to the default permission flow. Choose the variant that matches your security requirements. @@ -573,6 +625,9 @@ All configured `permissionRequest` hooks run for each request (except `read` and **Matcher:** Optional regex tested against `toolName`. Anchored as `^(?:pattern)$`; must match the full tool name. When set, the hook fires only for matching tool names. +> [!NOTE] +> **Claude-format matchers (PascalCase `PermissionRequest`):** Hooks configured with the PascalCase event name `PermissionRequest` use the same Claude matcher semantics as `PreToolUse`. See [Claude-format matchers (PascalCase PreToolUse)](#claude-format-matchers-pascalcase-pretooluse) for the matcher rules and tool name table. + Output JSON to stdout to control the permission decision: | Field | Values | Description | diff --git a/src/content-pipelines/state/copilot-cli.sha b/src/content-pipelines/state/copilot-cli.sha index 473bb8c694a7..c1ece678dd0e 100644 --- a/src/content-pipelines/state/copilot-cli.sha +++ b/src/content-pipelines/state/copilot-cli.sha @@ -1 +1 @@ -c05adb990b05f7ab88981904a6f5e0d67ab1387c +005830f576fb7f53962c8080fdd86d7a382587c6 From 024719bc75629e5a287a36410a0b83024824faa6 Mon Sep 17 00:00:00 2001 From: Cory Calahan Date: Mon, 15 Jun 2026 04:06:30 -0700 Subject: [PATCH 5/6] Adding additional investigation suggestions for security incidents (#61499) Co-authored-by: Stacy Carter Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com> --- .../investigation-areas.md | 4 ++++ .../investigation-tools.md | 19 +++++++++++++++++-- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/content/code-security/reference/security-incident-response/investigation-areas.md b/content/code-security/reference/security-incident-response/investigation-areas.md index 311503c2a219..d241b9365de7 100644 --- a/content/code-security/reference/security-incident-response/investigation-areas.md +++ b/content/code-security/reference/security-incident-response/investigation-areas.md @@ -109,6 +109,8 @@ You found suspicious code in your repository, a security researcher reported an * Review the **Actions** tab for unexpected workflow runs, especially those triggered by unfamiliar users or at unusual times. * Inspect workflow run logs for suspicious output. +* Review the credentials accessible to suspicious workflow runs, including the default `GITHUB_TOKEN`, any {% data variables.product.pat_generic_plural %}, {% data variables.product.prodname_github_app %} tokens, or other credentials stored as secrets. The `GITHUB_TOKEN` is scoped to the job and expires when the job completes, but other credentials have their own lifecycle and do not expire with the job. Any credential that may have been exposed should be treated as compromised and rotated or replaced immediately. +* Be aware that workflow run logs only capture standard output from workflow steps. Activity that does not write to standard output (such as network calls, file system modifications, or background processes) will not appear in the logs. For a more comprehensive investigation, correlate with audit log events. * Use {% data variables.product.github %} code search to find suspicious files or code additions, particularly in workflow files (`.github/workflows/`), shell scripts, or configuration files. * Use the Activity view to check for pushes to unusual branch names, force pushes, pushes from unexpected actors. * Check the audit logs for changes to security settings or disablement actions (look for events like `repository_ruleset.destroy`, `repository_secret_scanning_push_protection.disable`, or other `.delete`, `.disable`, `.destroy` events). @@ -127,6 +129,8 @@ You found suspicious code in your repository, a security researcher reported an ### Key resources * [Containment actions](/code-security/tutorials/secure-your-organization/responding-to-security-incidents#step-2-contain-the-threat) +* [AUTOTITLE](/actions/concepts/security/github_token) +* [AUTOTITLE](/actions/reference/security/secure-use) {% ifversion fpt or ghec %} diff --git a/content/code-security/reference/security-incident-response/investigation-tools.md b/content/code-security/reference/security-incident-response/investigation-tools.md index a9534d1c1acd..1db03e9b72d7 100644 --- a/content/code-security/reference/security-incident-response/investigation-tools.md +++ b/content/code-security/reference/security-incident-response/investigation-tools.md @@ -156,7 +156,8 @@ Read access to the repository. * Confirm what executed in CI/CD at a given time (such as the commands executed, or the dependency installed). * Investigate suspicious workflow runs, such as those triggered by an unfamiliar user or at an unusual time, to see what actions were performed, which secrets were accessed, and what code was executed. -* Determine whether a workflow had access to any secrets. +* Review what credentials a workflow job had access to, including the default `GITHUB_TOKEN`, any {% data variables.product.pat_generic_plural %}, {% data variables.product.prodname_github_app %} tokens, other credentials stored as secrets, and access tokens obtained during the workflow run. +* Retrieve logs programmatically via the REST API for archival, forensic, or automation purposes. #### Permissions required @@ -166,8 +167,22 @@ Read access to the repository. * [AUTOTITLE](/actions/how-tos/monitor-workflows/view-workflow-run-history) * [AUTOTITLE](/actions/how-tos/monitor-workflows/use-workflow-run-logs) +* [AUTOTITLE](/actions/how-tos/manage-workflow-runs/download-workflow-artifacts) +* [AUTOTITLE](/actions/concepts/security/github_token) +* [AUTOTITLE](/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) +* [AUTOTITLE](/actions/reference/security/secure-use) +* [AUTOTITLE](/rest/actions/workflow-runs) +* [AUTOTITLE](/rest/actions/workflow-jobs) +* [AUTOTITLE](/code-security/tutorials/implement-supply-chain-best-practices/securing-builds) ### Notes and limitations * {% data variables.product.github %} automatically redacts secrets from workflow logs. -* By default, workflow logs are retained by {% data variables.product.github %} for 90 days, but you can configure this retention period to be longer (up to 400 days for private repositories). +* By default, workflow logs are retained by {% data variables.product.github %} for 90 days, but you can configure this retention period. {% ifversion fpt or ghec %}For public repositories, the maximum retention is 90 days. For private{% ifversion ghec %} and internal{% endif %} repositories, the maximum is 400 days.{% else %}The maximum retention is 400 days.{% endif %} Retention can be configured at the enterprise, organization, or repository level. If a workflow run occurred outside of your configured retention window, the logs may no longer be available. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository), [AUTOTITLE](/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization), or [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise). +* Workflow runs (including their logs) can also be deleted via the REST API. To check whether a run was deleted, query for `workflows.delete_workflow_run` events in the audit log. +* The default `GITHUB_TOKEN` issued to each job is scoped to that job and expires when the job finishes or after its effective maximum lifetime (up to 24 hours on self-hosted runners). Even if a step captured the token, it cannot be reused after the job finishes. For more information, see [AUTOTITLE](/actions/concepts/security/github_token). +* Other credentials referenced in workflows, such as {% data variables.product.pat_generic_plural %}, {% data variables.product.prodname_github_app %} installation tokens, or third-party API keys stored as secrets, have their own lifecycle and do not expire when the job ends. If a workflow step exposed one of these credentials, the token remains valid until it is revoked or expires according to its own policy. Any credential that may have been exposed should be treated as compromised and rotated or replaced immediately. Review the workflow file and the repository, organization, and environment secrets to determine which credentials were accessible. For more information, see [AUTOTITLE](/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets). +* You can download logs for an entire workflow run or for a specific job programmatically using the REST API. Both endpoints return a redirect URL that is valid for one minute. For more information, see [AUTOTITLE](/rest/actions/workflow-runs) and [AUTOTITLE](/rest/actions/workflow-jobs). +* Workflow run logs only capture standard output from workflow steps. Activity that does not write to standard output, such as network calls, file system modifications, or background processes, does not appear in the logs. +* For {% data variables.product.github %}-hosted runners, the runner environment is ephemeral and destroyed after the job completes. {% data variables.product.github %} does not retain any data beyond the workflow run logs for these runners. For self-hosted runners, additional host-level or network telemetry may be available from your own infrastructure. +* For a more comprehensive investigation, correlate workflow run logs with audit log events. Events such as `git.clone`, `git.fetch`, `git.push`, `protected_branch.create`, and `protected_branch.policy_override` can provide additional context. Because Git events in {% data variables.product.github %}-hosted audit logs are currently retained for only 7 days for enterprises, setting up streamed enterprise audit logs ahead of time is important for this type of investigation. For more information, see [AUTOTITLE](/code-security/tutorials/secure-your-organization/preparing-for-security-incidents). From 444e74af1bb0f7c213db1117498a2ba3e63072dc Mon Sep 17 00:00:00 2001 From: Ksenia Bobrova Date: Mon, 15 Jun 2026 17:14:44 +0200 Subject: [PATCH 6/6] Add docs for new ways of adding and managing MCPs in Copilot CLI (#61336) Co-authored-by: Sarita Iyer <66540150+saritai@users.noreply.github.com> --- .../customize-copilot/add-mcp-servers.md | 112 +++++++++++++++++- 1 file changed, 110 insertions(+), 2 deletions(-) diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md index b2807e1c71f9..ac9bf01024c8 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md @@ -22,10 +22,15 @@ The Model Context Protocol (MCP) is an open standard that defines how applicatio If your organization or enterprise has configured a registry URL and allowlist policy, those settings apply to {% data variables.copilot.copilot_cli_short %}. The configured registry URL will appear as a discovery source, and only servers permitted by the allowlist policy can run. -You can add MCP servers using the interactive `/mcp add` command within the CLI, or by editing the configuration file directly. +You can add MCP servers in the following ways: +* [Using the `/mcp add` command](#using-the-mcp-add-command) +* [Using the `copilot mcp add` subcommand](#using-the-copilot-mcp-add-subcommand) +* [Editing the configuration file](#editing-the-configuration-file) +* [Searching and installing from the registry (experimental)](#searching-and-installing-from-the-registry) For installation instructions, available tools, and URLs for specific MCP servers, see the [{% data variables.product.github %} MCP Registry](https://github.com/mcp). + ### Using the `/mcp add` command 1. In interactive mode, enter `/mcp add`. A configuration form is displayed. Use Tab to navigate between fields. @@ -50,6 +55,59 @@ For installation instructions, available tools, and URLs for specific MCP server 1. Next to **Tools**, specify which tools from the server should be available. Enter `*` to include all tools, or provide a comma-separated list of tool names (no quotes needed). The default is `*`. 1. Press Ctrl+S to save the configuration. The MCP server is added and available immediately without restarting the CLI. +### Using the `copilot mcp add` subcommand + +You can add MCP servers from the terminal using the `copilot mcp add` subcommand, without entering interactive mode. The server is added to the user configuration at `~/.copilot/mcp-config.json`. + +For local (stdio) servers, provide the command after `--`: + +```shell copy +copilot mcp add SERVER-NAME -- COMMAND [ARGS...] +``` + +For remote (HTTP/SSE) servers, specify the transport and provide the URL: + +```shell copy +copilot mcp add --transport http SERVER-NAME URL +``` + +You can also pass additional options: + +* `--env KEY=VALUE`: Set environment variables for the server. Repeat for multiple variables. +* `--header "HEADER: VALUE"`: Set HTTP headers for remote servers. Repeat for multiple headers. +* `--transport TRANSPORT`: Set the transport type (`stdio`, `http`, or `sse`). The default is `stdio`. +* `--tools TOOLS`: Specify which tools to enable. Use `*` for all tools (default), a comma-separated list, or `""` for none. +* `--timeout MS`: Set a timeout in milliseconds. + +#### Examples + +Add a local stdio server: + +```shell copy +copilot mcp add context7 -- npx -y @upstash/context7-mcp +``` + +Add a local server with environment variables: + +```shell copy +copilot mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server +``` + +Add a remote HTTP server: + +```shell copy +copilot mcp add --transport http notion \ + https://mcp.notion.com/mcp +``` + +Add a remote server with an authorization header: + +```shell copy +copilot mcp add --transport http \ + --header "Authorization: Bearer YOUR-TOKEN" \ + stripe https://mcp.stripe.com +``` + ### Editing the configuration file You can also add MCP servers by editing the configuration file at `~/.copilot/mcp-config.json`. This is useful if you want to share configurations or add multiple servers at once. @@ -80,9 +138,31 @@ The following example shows a configuration file with a local server and a remot For more information on MCP server configuration, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/extend-cloud-agent-with-mcp#writing-a-json-configuration-for-mcp-servers). +### Searching and installing from the registry + +> [!NOTE] +> The `/mcp search` command is currently an experimental feature. To use it, start {% data variables.copilot.copilot_cli_short %} with the `--experimental` command line option, or enter `/experimental on` during a session. + +You can discover and install MCP servers directly from the [{% data variables.product.github %} MCP Registry](https://github.com/mcp) using the `/mcp search` command in interactive mode. This lets you browse available servers, view their details, and install them without manually filling out the configuration form. + +If your organization has configured a custom MCP registry URL, `/mcp search` connects to that registry instead of the default {% data variables.product.github %} registry. + +1. In interactive mode, enter `/mcp search` to browse top servers by stars, or `/mcp search QUERY` to search for a specific server. For example: + + ```text + /mcp search context7 + ``` + +1. A keyboard-navigable list of matching servers is displayed. Use the arrow keys to browse the results. +1. Select a server to open its configuration form. The form is pre-populated with the server's configuration from the registry. Fill in any required fields, such as API keys or tokens. +1. Press Ctrl+S to save. The server is added to your `mcp-config.json` and started immediately. + + ## Managing MCP servers -You can manage your configured MCP servers using the following `/mcp` commands in {% data variables.copilot.copilot_cli_short %}. +You can manage your configured MCP servers using the `/mcp` commands in interactive mode or the `copilot mcp` subcommands from the terminal. + +### Using `/mcp` commands in interactive mode * **List configured MCP servers:** Use the command `/mcp show`. This displays all configured MCP servers and their current status. @@ -96,6 +176,34 @@ You can manage your configured MCP servers using the following `/mcp` commands i * **Enable a previously disabled server:** Use the command `/mcp enable SERVER-NAME`. +### Using `copilot mcp` subcommands from the terminal + +You can also manage MCP servers from the terminal without entering interactive mode. + +* **List all configured servers:** + + ```shell copy + copilot mcp list + ``` + + Lists servers from all configuration sources (user, workspace, and plugin). Add `--json` for JSON output. + +* **View server details:** + + ```shell copy + copilot mcp get SERVER-NAME + ``` + + Shows a server's type, status, and available tools. Add `--json` for JSON output. + +* **Remove a server:** + + ```shell copy + copilot mcp remove SERVER-NAME + ``` + + Removes the server from the user configuration. + ## Using MCP servers Once you have added an MCP server, {% data variables.product.prodname_copilot_short %} can automatically use the tools it provides when relevant to your prompt. You can also directly reference an MCP server and specific tools in a prompt to ensure they are used.