diff --git a/content/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps.md b/content/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps.md index de42b7dcdd07..0455a9ebba51 100644 --- a/content/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps.md +++ b/content/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps.md @@ -20,6 +20,8 @@ When an {% data variables.product.prodname_oauth_app %} wants to identify you by > [!TIP] > You must [verify your email address](/account-and-profile/how-tos/email-preferences/verifying-your-email-address) before you can authorize an {% data variables.product.prodname_oauth_app %}. +If you see “This account is flagged, and therefore cannot authorize a third party application” while authorizing an {% data variables.product.prodname_oauth_app %} or choosing **Continue with {% data variables.product.github %}**, your account has a restriction or is under review. This message isn't caused by missing email verification, organization approval, or SAML reauthorization. Retrying the authorization flow won't resolve the error while the restriction remains. For next steps, see [AUTOTITLE](/free-pro-team@latest/site-policy/acceptable-use-policies/github-appeal-and-reinstatement). + {% endif %} ## {% data variables.product.prodname_oauth_app %} access diff --git a/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers.md b/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers.md index 838a570370f3..4438fd7d4bd0 100644 --- a/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers.md +++ b/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers.md @@ -161,13 +161,28 @@ Within each server definition, the following fields are available/required: command - Yes - The command used to start the LSP server. + No + The command used to start the LSP server. At least one of command, bash, or powershell must be specified. + + + bash + No + A bash script to run instead of command, for servers that need shell features such as pipes or environment setup. Not used on Windows if powershell is also set. + + + powershell + No + A PowerShell script to run instead of command, used on Windows when set. args No - Arguments to pass to the command. + Arguments to pass to command. Ignored when the server is launched with bash or powershell. + + + cwd + No + The working directory to launch the server from. Defaults to the project root. fileExtensions @@ -199,6 +214,16 @@ Within each server definition, the following fields are available/required: No The timeout for the server's startup handshake in milliseconds (default: 60 seconds). If a server needs more time for initial project analysis, increase this value. + + spawnTimeoutMs + No + The timeout for spawning the server process in milliseconds. + + + warmupTimeoutMs + No + The timeout for the server's warmup phase in milliseconds. + diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle.md index 037afc2dfbce..e7797e129f15 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle.md @@ -54,10 +54,12 @@ You can share the content of the current session as a shareable link to the sess > [!NOTE] > You can use `/export` as an alias for `/share` in any of the commands below. -To share the session to {% data variables.product.github %} and print a shareable link, type the following in an interactive session: +Typing `/share` with no arguments opens a full-screen sharing menu where you can choose how to share the session. Opening this menu does not itself share or export anything. + +To share the session to {% data variables.product.github %} and print a shareable link directly, type the following in an interactive session: ```copilot copy -/share +/share link ``` To stop sharing the session, type `/share off`. @@ -240,6 +242,7 @@ The simplest way to delete sessions is to use the `/session` slash command in an * `/session delete SESSION-ID` deletes a specific session. This shows a preview first; add `--yes` to confirm, for example `/session delete SESSION-ID --yes`. * `/session delete-all` deletes all of your local sessions except the current one. Add `--yes` to confirm: `/session delete-all --yes`. Sessions that are in use by another process are skipped. * `/session prune --older-than DAYS` deletes sessions older than the specified number of days. Add `--dry-run` to preview what would be deleted. +* `/session cleanup` shows a storage summary of your other local sessions, grouped by age, and suggests commands for deleting old sessions. It does not delete local or synced sessions. Use `/session prune --older-than DAYS --dry-run` to preview deletions, then remove `--dry-run` to delete those local sessions. When you delete a session that has been synced to your account, `/session delete` asks whether you also want to delete the synced (remote) copy. Deleting the synced copy also removes the session from your `/chronicle` insights and query results. The `/session delete-all` and `/session prune` subcommands only affect local sessions and do not delete synced data. To remove synced data for those sessions, manually delete it from {% data variables.product.prodname_dotcom_the_website %}. diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely.md index 8dec22f86458..b9fa2fb517c2 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely.md @@ -37,7 +37,6 @@ This article explains how to enable and use remote control. For more conceptual You can enable remote control in several ways: * With a slash command during an interactive session. -* With a command-line option when you start {% data variables.copilot.copilot_cli_short %}. * By configuring the CLI to enable remote control by default for all interactive sessions. * From JetBrains IDE settings before you start a session. @@ -53,16 +52,6 @@ The CLI connects to {% data variables.product.prodname_dotcom_the_website %} and You can use the `/remote` slash command without an argument to check the current remote control status, or to redisplay the remote access details if remote control is currently enabled. If you want to end the remote connection for the current session, enter `/remote off`. -### Using the `--remote` command-line option - -If you think you may want to access a session remotely, you can start the CLI with the `--remote` command-line option. This avoids the need to remember to use the `/remote` slash command during the session. - -```bash copy -copilot --remote -``` - -Details for accessing the session remotely are displayed when the interactive session starts and can be displayed again at any time by using the `/remote` slash command. - ### Configuring remote control to always be enabled If you always want your interactive CLI sessions to be remotely accessible, add the following to your {% data variables.product.prodname_copilot_short %} settings file (typically located at `~/.copilot/settings.json`): @@ -73,15 +62,6 @@ If you always want your interactive CLI sessions to be remotely accessible, add } ``` -To override this setting for a particular session, use the `--no-remote` option when you start the session: - -```bash copy -copilot --no-remote -``` - -> [!NOTE] -> The command-line options `--remote` and `--no-remote` always take precedence over the `remote` setting in the settings file. - ### Using JetBrains IDE settings If you use {% data variables.copilot.copilot_cli_short %} from a JetBrains IDE, you can enable remote control from the IDE before you start a session. @@ -163,10 +143,7 @@ On {% data variables.product.prodname_dotcom_the_website %}, a message tells you ## Preventing remote control -Remote control is disabled by default, but may be enabled in your {% data variables.product.prodname_copilot_short %} settings file (typically `~/.copilot/settings.json`). You can ensure a session is not remotely controllable by: - -* **For a single session**: Start the CLI with `--no-remote` to prevent remote control for that session, regardless of your settings file value. -* **Permanently**: Remove the `"remoteSessions": true` setting from `~/.copilot/settings.json`, or set it to `false`. +Remote control is disabled by default, but may be enabled in your {% data variables.product.prodname_copilot_short %} settings file (typically `~/.copilot/settings.json`). You can ensure a session is not remotely controllable by removing the `"remoteSessions": true` setting from `~/.copilot/settings.json`, or setting it to `false`. Enterprise owners can also restrict remote control of sessions hosted on your device using enterprise managed settings, regardless of your personal settings. Depending on the configured policy, remote control of sessions on your device may be disabled entirely, or only available to a controlling client that is SSO-authorized for specific organizations. This doesn't affect your ability to remotely control your own sessions hosted on other devices. See [AUTOTITLE](/copilot/reference/enterprise-administrators/enterprise-managed-settings). diff --git a/content/copilot/reference/copilot-billing/request-based-billing-legacy/github-copilot-premium-requests.md b/content/copilot/reference/copilot-billing/request-based-billing-legacy/github-copilot-premium-requests.md index 18edd3c3cb95..f034c3ef823b 100644 --- a/content/copilot/reference/copilot-billing/request-based-billing-legacy/github-copilot-premium-requests.md +++ b/content/copilot/reference/copilot-billing/request-based-billing-legacy/github-copilot-premium-requests.md @@ -91,6 +91,21 @@ You can set a budget in your personal billing settings to receive alerts when yo * **Bundled premium request budget** - Combines all premium requests into a single budget (Recommended for most users) * **Individual SKU budgets** - Set separate budgets for each AI product (Copilot, {% data variables.product.prodname_spark_short %}, {% data variables.copilot.copilot_cloud_agent %}) +To prevent paid premium-request overages while keeping your annual {% data variables.product.prodname_copilot_short %} subscription: + +{% data reusables.user-settings.access_billing_settings_url %} + +1. Click **Budgets and alerts**. +1. Create or edit a bundled premium request budget covering all premium-request SKUs, or individual SKU budgets covering every applicable premium-request SKU. +1. Set each budget to **$0 USD**, enable **Stop usage when budget limit is reached**, and save your changes. + +This blocks additional paid premium requests after your included monthly allowance is exhausted without canceling your subscription. + +> [!NOTE] +> Deleting a budget is not a substitute for this configuration and can remove spending limits. + +For configuration steps, see [AUTOTITLE](/billing/how-tos/set-up-budgets#managing-budgets-for-your-personal-account). + ## Monitoring usage * Track your monthly usage in your IDE, in {% data variables.product.prodname_copilot_short %} settings on {% data variables.product.prodname_dotcom %}, or by downloading a usage report. diff --git a/content/copilot/reference/copilot-cli-reference/acp-server.md b/content/copilot/reference/copilot-cli-reference/acp-server.md index 23d3911edf8a..08a75d7eae3a 100644 --- a/content/copilot/reference/copilot-cli-reference/acp-server.md +++ b/content/copilot/reference/copilot-cli-reference/acp-server.md @@ -52,6 +52,8 @@ copilot --acp --port 3000 --effort=max --available-tools="bash,view" Every session the connected client opens against that server inherits those settings. Because the values are fixed when the server starts, a client cannot change them per session through `session/new`. +Sessions also honor saved sandbox settings and the `--sandbox` and `--no-sandbox` options, including when a session is resumed. An enterprise-managed policy that enforces sandboxing will override `--no-sandbox`. + ### stdio mode stdio mode is inferred by default when you start the ACP server. You can also use the `--stdio` option for disambiguation. 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 f199be6f4fdd..23fb2ab4f674 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md @@ -607,7 +607,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/security-review [PROMPT]` | Run a focused security review of active local code changes and return prioritized vulnerability findings with remediation suggestions. This command is not a full repository security audit. | | `/session [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]`, `/sessions [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]` | Show session information and manage sessions. The `info` subcommand shows session details including the session link (when available). Subcommands: `info`, `checkpoints`, `files`, `plan`, `rename`, `cleanup`, `prune`, `delete`, `delete-all`. | | `/settings [--repo\|--local] [show KEY\|KEY\|KEY VALUE]`,
`/config [--repo\|--local] [show KEY\|KEY\|KEY VALUE]` | Open the settings dialog, open it focused on a specific setting (`KEY`), set a setting inline (`KEY VALUE`), or display a setting's current value (`show KEY`). `show` masks secret-named values (for example, tokens or API keys nested under a setting) instead of printing them in clear text. The dialog shows **User**, **Repo**, **Repo (local)**, and **Problems** tabs—switch with Tab/Shift+Tab; a setting overridden in another scope shows a badge naming which scope wins. The **Problems** tab is a cross-scope view of settings that need attention (for example, unknown or invalid keys); its label shows a count, such as `Problems (2)`, when any scope has an issue, and otherwise just reads `Problems`. Add `--repo` or `--local` to target `.github/copilot/settings.json` or `.github/copilot/settings.local.json` instead of the user settings file—for example, `/settings --repo model gpt-6-astra`. Only [repo-overridable keys](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#repository-settings-githubcopilotsettingsjson) can be set this way. Rows governed by an active organization or MDM managed policy render read-only with a `(managed)` tag. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/change-settings). | -| `/share [link\|off\|file\|html\|gist\|research] [...]`, `/export [...]` | Share the current session. With no subcommand, generates a shareable {% data variables.product.github %} link when you're logged in and synced (falls back to Markdown file export otherwise). `off` stops sharing. `link` is an explicit alias for the default link flow; `link off` stops link sharing. `file [session\|research] [PATH]` exports to a Markdown file. `html [session\|research] [PATH]` exports to an HTML file. `gist [session\|research]` creates a {% data variables.product.github %} gist. `research [PATH]` exports the research report. | +| `/share [link\|off\|file\|html\|gist\|research] [...]`, `/export [...]` | Share the current session. With no subcommand, opens a sharing menu without sharing or exporting anything. `link` shares the session and prints a shareable {% data variables.product.github %} link. `off` or `link off` stops link sharing. `file [session\|research] [PATH]` exports to a Markdown file. `html [session\|research] [PATH]` exports to an HTML file. `gist [session\|research]` creates a {% data variables.product.github %} gist. `research [PATH]` exports the research report. | | `/skills` | Open the plugins dashboard on the Skills tab. | | `/skills list` | List all available skills. | | `/skills info NAME` | Show details of a specific skill. | @@ -717,15 +717,15 @@ Use `/collect-debug-logs [file|gist|share] [PATH]` to gather debug logs for trou | `--no-custom-instructions` | Disable loading of custom instructions from `AGENTS.md` and related files. | | `--no-experimental` | Disable experimental features. | | `--no-mouse` | Disable mouse support. | -| `--no-remote` | Disable remote access for this session. | -| `--no-remote-export` | Disable exporting your session to {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_mobile %} (also disables remote control). | +| `--no-remote` | Removed. Use `/remote off` during an interactive session to end its remote connection. | +| `--no-remote-export` | Renamed to `--sync-session=off`. | | `--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). The exit summary includes a `copilot --resume=SESSION-ID` hint for continuing the session. 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 `--autopilot`. Can be combined with `--mode autopilot` for plan-then-autopilot; any other `--mode` value is rejected. | | `--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). A relative path resolves against the session working directory (the `--resume`, `--worktree`, or `-C` directory), regardless of option order. Agents contributed by a `--plugin-dir` plugin are available in server-mode (`--server`) sessions as well as interactive and `-p` sessions. | -| `--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). | -| `--remote-export` | Export your session to {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_mobile %} (read-only; does not enable remote control). | +| `--remote` | Not supported for interactive startup or with `-p`. Use `/remote on` during an interactive session instead. The flag remains supported for legacy SDK server startup with `--server` or `--headless`. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely). | +| `--remote-export` | Renamed to `--sync-session=on`. | | `-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. Conflicts with `--continue`. Bare `--resume` (no value) shows an interactive session picker, which requires a TTY. If multiple sessions exist and the picker can't be shown (for example under `-p`, a non-TTY `-i`, or piped stdin), the CLI exits with an error instead of silently starting a new session—pass an explicit `--resume=SESSION-ID` or use `--continue`. | | `-s`, `--silent` | Output only the agent response (without usage statistics), useful for scripting with `-p`. | | `--screen-reader` | Enable screen reader optimizations. | @@ -737,6 +737,7 @@ Use `/collect-debug-logs [file|gist|share] [PATH]` to gather debug logs for trou | `--share=PATH` | Share a session to a Markdown file after completion of a programmatic session (default path: `./copilot-session-.md`). | | `--share-gist` | Share a session to a secret {% data variables.product.github %} gist after completion of a programmatic session. | | `--stream=MODE` | Enable or disable streaming mode, which displays {% data variables.product.prodname_copilot_short %}'s response progressively as it is generated rather than waiting for the full response to arrive (mode choices: `on` or `off`, default: `on`). +| `--sync-session[=on\|off]` | Enable or disable read-only session history syncing for this run. Without a value, enables syncing. Does not enable remote control. If omitted, uses your settings and the default behavior. | | `-v`, `--version` | Show version information. | | `-w`, `--worktree[=NAME]` | Create or reuse an isolated Git worktree under `.worktrees/` by default and start the session inside it. Use the `worktreePathTemplate` setting to configure the location. `NAME` is optional—omit it to auto-generate a branch name. By default, branches off the current checkout (`HEAD`); set the `worktreeBaseRef` setting to `"defaultBranch"` to branch off the remote default branch instead. Conflicts with `--resume`, `--continue`, and `--connect`. | | `--yolo` | Enable all permissions (equivalent to `--allow-all`). | @@ -744,9 +745,9 @@ Use `/collect-debug-logs [file|gist|share] [PATH]` to gather debug logs for trou For a complete list of commands and options, run `copilot help`. > [!NOTE] -> The `--remote`, `--no-remote`, `--remote-export`, `--no-remote-export`, and `--connect` options require the remote sessions feature to be available on your account. +> Remote session features require availability on your account. The legacy `--remote` flag is not an interactive-session control, and `--no-remote` is no longer supported. -You can use `--remote` with `--resume ` to resume a remote task locally. This works even when the task was originally created outside a Git repository. +To enable remote control during an interactive session, use `/remote on`. To end the remote connection, use `/remote off`. If a session was still open when its CLI process went away, for example due to a crash or a machine restart, the next time you start `copilot` you're offered the option to restore it. You can review the sessions available to restore or start a fresh session instead. A restored session whose agent was mid-turn automatically resumes that work. diff --git a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md index 2f4607364452..0796a6d5a073 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md @@ -491,10 +491,10 @@ These settings apply across all your sessions and repositories. You can use the | `powershellFlags` | `string[]` | `["-NoProfile", "-NoLogo"]` | Flags passed to PowerShell on startup. On Windows, the CLI prefers PowerShell 7+ (`pwsh`) and falls back to Windows PowerShell (`powershell.exe`) when `pwsh` is unavailable. Windows only. | | `proxyKerberosServicePrincipal` | `string` | unset | Service principal name (SPN) for Kerberos/Negotiate proxy authentication, overriding the derived `HTTP/`. | | `proxyUrl` | `string` | unset | Proxy URL for HTTP(S) requests (for example, `http://proxy.corp.example:3128`). Overridden by the `HTTP_PROXY` or `HTTPS_PROXY` environment variables (any casing). | -| `remote` | `"on"` \| `"off"` | `"on"` | Controls session syncing and remote access. Set to `"off"` to keep session data local only and disable remote control. Can also be set with `--remote` or `--no-remote`. | +| `remoteSessions` | `boolean` | `false` | Enable remote control by default for interactive sessions when remote control is available. Use `/remote on` or `/remote off` to change remote control for the current session. This is separate from the `remoteExport` setting for session syncing. | | `renderHexColors` | `boolean` | `true` | Show six-digit hex color codes written as inline code (for example, `` `#FF0000` ``) as color swatches. | | `renderMarkdown` | `boolean` | `true` | Render Markdown in terminal output. | -| `remoteExport` | `boolean` | `true` | Export sessions remotely when session sync is available. Set to `false` to opt out of remote export by default. The `remoteSessions` setting when set to `true`, or the `--remote` flag, still enables export and steering regardless of this setting. | +| `remoteExport` | `boolean` | `true` | Sync session history to your account when session sync is available. Set to `false` to opt out by default. Enabling remote control with `remoteSessions: true` also enables export, regardless of this setting. Syncing history does not itself enable remote control. Use `--sync-session=on` or `--sync-session=off` to override history syncing for a run. | | `respectGitignore` | `boolean` | `true` | Exclude gitignored files from the `@` file mention picker. When `false`, the picker includes files normally excluded by `.gitignore`. | | `sandbox.allowBypass` | `boolean` | `true` | Allow sandboxed commands to request a bypass for specific operations (displays a permission prompt), so tools like `grep` and `glob` keep working when the sandbox would otherwise block them. The prompt also lets you disable sandboxing for the rest of the current session if the effective policy permits bypass. Set to `false` to opt out. | | `sandbox.enabled` | `boolean` | `false` | Restrict shell commands, MCP/LSP servers, and built-in file/web tools to a sandboxed environment with limited file system and network access. Enable it from the `/sandbox` dialog or with `/sandbox enable`. | 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 65ec0c76f35f..0b613f239bec 100644 --- a/content/copilot/reference/copilot-usage-metrics/copilot-usage-metrics.md +++ b/content/copilot/reference/copilot-usage-metrics/copilot-usage-metrics.md @@ -131,11 +131,11 @@ Per-user reports contain one record per user for the reporting period. The 28-da | `distinct_mcp_use_count` | `integer` | Yes | Number of different Model Context Protocol (MCP) server identifiers with recorded connection activity for the user. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | | `distinct_slash_cmd_use_count` | `integer` | Yes | Number of different slash command identifiers with recorded activity for the user. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | | `distinct_plugin_use_count` | `integer` | Yes | Number of different plugin identifiers with recorded activity for the user. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | -| `totals_by_skill` | `array` | Yes | Top skills used in {% data variables.copilot.copilot_cli_short %}, ordered by interaction count. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | -| `totals_by_custom_agent` | `array` | Yes | Top custom agents used in {% data variables.copilot.copilot_cli_short %}, ordered by interaction count. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | -| `totals_by_mcp` | `array` | Yes | MCP servers with the most connection and reconnection attempts in {% data variables.copilot.copilot_cli_short %}, ordered by interaction count. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | -| `totals_by_slash_cmd` | `array` | Yes | Top slash commands used in {% data variables.copilot.copilot_cli_short %}, ordered by interaction count. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | -| `totals_by_plugin` | `array` | Yes | Top plugins used in {% data variables.copilot.copilot_cli_short %}, ordered by interaction count. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | +| `totals_by_skill` | `array` | Yes | Top skills by recorded interaction count across supported clients. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | +| `totals_by_custom_agent` | `array` | Yes | Top custom agents by recorded interaction count across supported clients. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | +| `totals_by_mcp` | `array` | Yes | MCP servers with the most recorded connection and reconnection attempts across supported clients. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | +| `totals_by_slash_cmd` | `array` | Yes | Top slash commands by recorded interaction count across supported clients. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | +| `totals_by_plugin` | `array` | Yes | Top plugins by recorded interaction count across supported clients. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | | `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_copilot_app` | `object` | Yes | The {% data variables.copilot.github_copilot_app_short %} metrics for the user. Omitted when the user did not use the {% data variables.copilot.github_copilot_app_short %} that day. See [Metrics fields for the {% data variables.copilot.github_copilot_app_short %}](#copilot-app-metrics-fields). | | `totals_by_3rd_party_agent` | `array` | Yes | Per-agent usage metrics for recognized {% data variables.copilot.agent_apps %}. Omitted when the user had no recognized {% data variables.copilot.agent_app %} activity during the reporting period. See [{% data variables.copilot.agent_apps_caps %} metrics fields](#agent-apps-metrics-fields). | @@ -190,11 +190,11 @@ Activity totals and breakdowns: | `distinct_mcp_use_count` | `integer` | Yes | Number of different MCP server identifiers with recorded connection activity across the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | | `distinct_slash_cmd_use_count` | `integer` | Yes | Number of different slash command identifiers with recorded activity across the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | | `distinct_plugin_use_count` | `integer` | Yes | Number of different plugin identifiers with recorded activity across the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | -| `totals_by_skill` | `array` | Yes | Top skills used in {% data variables.copilot.copilot_cli_short %} across the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | -| `totals_by_custom_agent` | `array` | Yes | Top custom agents used in {% data variables.copilot.copilot_cli_short %} across the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | -| `totals_by_mcp` | `array` | Yes | MCP servers with the most connection and reconnection attempts in {% data variables.copilot.copilot_cli_short %} across the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | -| `totals_by_slash_cmd` | `array` | Yes | Top slash commands used in {% data variables.copilot.copilot_cli_short %} across the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | -| `totals_by_plugin` | `array` | Yes | Top plugins used in {% data variables.copilot.copilot_cli_short %} across the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | +| `totals_by_skill` | `array` | Yes | Top skills by recorded interaction count across supported clients in the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | +| `totals_by_custom_agent` | `array` | Yes | Top custom agents by recorded interaction count across supported clients in the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | +| `totals_by_mcp` | `array` | Yes | MCP servers with the most recorded connection and reconnection attempts across supported clients in the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | +| `totals_by_slash_cmd` | `array` | Yes | Top slash commands by recorded interaction count across supported clients in the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | +| `totals_by_plugin` | `array` | Yes | Top plugins by recorded interaction count across supported clients in the enterprise or organization. See [{% data variables.copilot.copilot_cli_short %} customization fields](#copilot-cli-customization-fields-api-only). | | `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). | @@ -310,7 +310,7 @@ The `totals_by_cli` object contains the following nested fields when {% data var ### {% data variables.copilot.copilot_cli_short %} customization fields (API only) -These metrics give enterprise and organization administrators visibility into which {% data variables.copilot.copilot_cli_short %} automations developers use. Use them to understand adoption, identify enablement gaps, and prioritize the skills, Model Context Protocol (MCP) servers, custom agents, slash commands, and plugins that developers find valuable. +These metrics give enterprise and organization administrators visibility into which customizations developers use across {% data variables.copilot.copilot_cli_short %} and other supported clients. Use them to understand adoption, identify enablement gaps, and prioritize the skills, Model Context Protocol (MCP) servers, custom agents, slash commands, and plugins that developers find valuable. To access the reports, the {% data variables.product.prodname_copilot_short %} usage metrics policy must be enabled. For policy configuration instructions, see: @@ -323,9 +323,33 @@ These fields appear in the following enterprise and organization reports: * Aggregated 1-day reports * Each `day_totals` record in aggregated 28-day reports -Each `totals_by_*` array contains up to five entries with the most recorded activity for its record, ordered from highest to lowest `interaction_count`. The values are event counts, not user counts. An entry's absence from an array does not mean that it had zero usage. Do not use these arrays to calculate exact adoption. +In per-user 1-day reports and aggregated 1-day reports, each of the five customization arrays listed below retains up to 25 named entries per record, ordered from highest to lowest `interaction_count`. This limit and ordering also apply to each `day_totals` record in aggregated 28-day reports. -Recognized first-party names can appear when available. Customer-defined identifiers are not exposed. Skills, custom agents, MCP servers, and plugins identified only by customer-specific hashes are grouped under `other` in the arrays. {% data variables.copilot.copilot_cli_short %} telemetry reports customer-defined slash commands as `custom`, so slash command arrays preserve that value. +Entries outside the top 25 are combined into a trailing `other` entry, including for slash commands. This entry can appear in addition to the 25 named entries. It is separate from `custom`, which represents slash commands whose configured names are unavailable. + +Across report types, the values are event counts, not user counts. An entry's absence from a capped array does not mean that it had zero usage. Do not use these arrays to calculate exact adoption. + +In enterprise and organization reports, including per-user 1-day and 28-day reports, aggregated 1-day reports, and `day_totals` in aggregated 28-day reports, these arrays include the configured names of customizations your organization creates. Configured names are also included in the corresponding per-user NDJSON exports. + +Names are reported from these clients when the enterprise's {% data variables.product.prodname_copilot_short %} usage metrics policy is enabled: + +* {% data variables.copilot.copilot_cli_short %} interactive sessions and prompt mode (`-p`). +* The {% data variables.copilot.github_copilot_app_short %}. +* Agent Client Protocol (ACP) integrations, such as {% data variables.product.prodname_copilot_short %} in JetBrains AI Assistant +* The {% data variables.copilot.copilot_sdk_short %}. + +To report customization names: + +* Prompt mode, the app, and ACP integrations require {% data variables.copilot.copilot_cli_short %} 1.0.97 or later. +* The {% data variables.copilot.copilot_sdk_short %} requires version 1.0.21 or later. If an application overrides the CLI bundled with the SDK, that CLI must be version 1.0.97 or later. + +IDEs' built-in {% data variables.product.prodname_copilot_short %} chat integrations do not report customization names. + +Configured names are trimmed and limited to 128 characters. Names that look like file paths remain grouped under `other` or `custom`, as do customizations for which names are unavailable. Review configured names before sharing reports outside your organization. + +Names are available for report days processed after support for customization names was deployed. Earlier days are not automatically backfilled and continue to show `other` or `custom`. Reporting names does not change how `interaction_count` or the `distinct_*_use_count` fields are calculated. + +These metrics depend on client telemetry and can undercount activity, for example when clients are outdated or telemetry is blocked. Use them to understand trends and adoption, not for exact accounting or as a complete audit of customization use. Each array entry contains the name field listed in the table and an integer `interaction_count` field. @@ -341,9 +365,9 @@ Every plugin interaction is already included in `totals_by_skill`, while skill i The distinct-count fields count different item identifiers with activity, not users or uses. In a per-user record, each different identifier that the user used counts once. In an aggregated enterprise or organization record, each different identifier used by anyone in the scope counts once, regardless of how many users used it. Aggregated distinct counts are not sums of per-user distinct counts. -Distinct counts retain the full identifier cardinality, including items outside the top-five array. When customer-defined artifacts are grouped under `other`, each hidden identifier still contributes separately to the corresponding distinct count. +Distinct counts include all different identifiers with recorded activity, even those outside an array's retained named entries. When customizations are grouped under `other` or `custom`, each hidden identifier still contributes separately to the corresponding distinct count. -When these fields are present, empty arrays and distinct counts of `0` mean that no matching activity was recorded. The fields can be null or absent when {% data variables.copilot.copilot_cli_short %} customization data isn't available during rollout. +When these fields are present, empty arrays and distinct counts of `0` mean that no matching activity was recorded. The fields can be null or absent when customization data isn't available during rollout. diff --git a/content/copilot/reference/copilot-usage-metrics/example-schema.md b/content/copilot/reference/copilot-usage-metrics/example-schema.md index 785dd6ec3906..af3a4ae57efa 100644 --- a/content/copilot/reference/copilot-usage-metrics/example-schema.md +++ b/content/copilot/reference/copilot-usage-metrics/example-schema.md @@ -27,7 +27,7 @@ The following examples show schemas for user-, enterprise-, and repository-level "ai_credits_used": 12.5, "code_acceptance_activity_count": 3, "code_generation_activity_count": 3, - "day": "2025-10-01", + "day": "2026-10-19", "distinct_custom_agent_use_count": 2, "distinct_mcp_use_count": 2, "distinct_plugin_use_count": 1, @@ -40,8 +40,8 @@ The following examples show schemas for user-, enterprise-, and repository-level "loc_suggested_to_delete_sum": 6, "totals_by_cli": { "last_known_cli_version": { - "cli_version": "1.0.8", - "sampled_at": "2025-10-01T00:01:43.000Z" + "cli_version": "1.0.97", + "sampled_at": "2026-10-19T00:01:43.000Z" }, "prompt_count": 2, "request_count": 2, @@ -66,7 +66,7 @@ The following examples show schemas for user-, enterprise-, and repository-level "custom_agent": "general-purpose", "interaction_count": 4 }, { - "custom_agent": "other", + "custom_agent": "release-reviewer", "interaction_count": 2 }], "totals_by_3rd_party_agent": [{ @@ -103,12 +103,12 @@ The following examples show schemas for user-, enterprise-, and repository-level "ide": "vscode", "last_known_ide_version": { "ide_version": "1.85.0", - "sampled_at": "2025-10-01T00:00:02.000Z" + "sampled_at": "2026-10-19T00:00:02.000Z" }, "last_known_plugin_version": { "plugin": "", "plugin_version": "", - "sampled_at": "2025-10-01T00:00:02.000Z" + "sampled_at": "2026-10-19T00:00:02.000Z" }, "loc_added_sum": 8, "loc_deleted_sum": 0, @@ -141,7 +141,7 @@ The following examples show schemas for user-, enterprise-, and repository-level "mcp": "github-mcp-server" }, { "interaction_count": 3, - "mcp": "other" + "mcp": "docs-search" }], "totals_by_model_feature": [], "totals_by_vscode_agent": { @@ -150,10 +150,16 @@ The following examples show schemas for user-, enterprise-, and repository-level }, "totals_by_plugin": [{ "interaction_count": 2, - "plugin": "other" + "plugin": "engineering-tools" }], "totals_by_skill": [{ - "interaction_count": 5, + "interaction_count": 2, + "skill": "code-review" + }, { + "interaction_count": 2, + "skill": "release-checks" + }, { + "interaction_count": 1, "skill": "other" }], "totals_by_slash_cmd": [{ @@ -161,7 +167,7 @@ The following examples show schemas for user-, enterprise-, and repository-level "slash_cmd": "/plan" }, { "interaction_count": 1, - "slash_cmd": "custom" + "slash_cmd": "/release-check" }], "used_agent": false, "used_chat": false, @@ -182,7 +188,11 @@ Organization per-user reports use the same `totals_by_3rd_party_agent` entry fie In both enterprise and organization per-user reports, `used_vscode_agent` and `totals_by_vscode_agent` provide dedicated metrics for the {% data variables.product.prodname_vscode_shortname %} Agents window. These fields appear at the top level in both 1-day and 28-day reports. They are omitted when no dedicated {% data variables.product.prodname_vscode_shortname %} Agents-window data is available, and `totals_by_vscode_agent` is omitted unless both of its counts are available. -The {% data variables.copilot.copilot_cli_short %} customization fields shown in this example appear in both 1-day and 28-day per-user reports. +The customization fields shown in this example appear in both 1-day and 28-day per-user reports for enterprises and organizations. Configured names such as `release-reviewer` and `docs-search` identify customizations created by your organization. + +Customizations with unavailable names or names that look like file paths remain grouped under `other` or `custom`. In per-user 1-day reports, each of the five customization arrays retains up to 25 named entries per user. Additional entries are combined into a trailing `other` entry. An entry's absence from a capped array does not mean that it had zero usage. + +For coverage and naming rules, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/copilot-usage-metrics#copilot-cli-customization-fields-api-only). In this example, `used_copilot_code_review_active` and `used_copilot_code_review_passive` are `null` because there was no {% data variables.copilot.copilot_code-review_short %} signal for the user that day. `used_copilot_cloud_agent` and `used_copilot_coding_agent` always carry the same value. @@ -587,7 +597,7 @@ In each `totals_by_ai_adoption_phase` entry, `total_engaged_users` is the subset Organization aggregated reports use the same top-level `copilot_feature_engagement` object, `totals_by_ai_adoption_phase` entry fields, and `totals_by_3rd_party_agent` entry fields, including `session_count`. They also include `organization_id`. -The {% data variables.copilot.copilot_cli_short %} customization fields shown in `day_totals` apply to enterprise and organization aggregated 28-day reports. They also appear directly in enterprise and organization aggregated 1-day reports. +The customization fields shown in `day_totals` apply to enterprise and organization aggregated 28-day reports. They also appear directly in enterprise and organization aggregated 1-day reports. Like per-user reports, these aggregated reports include configured names for customizations created by your organization. The following user-teams report examples are returned by the `user-teams-1-day` endpoints and are intended to be joined with the per-user usage report on `user_id`, `day`, and the relevant entity id (`organization_id` for the organization scope, `enterprise_id` for the enterprise scope) to derive team-level metrics. For more guidance, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics). diff --git a/content/copilot/reference/copilot-usage-metrics/interpret-copilot-metrics.md b/content/copilot/reference/copilot-usage-metrics/interpret-copilot-metrics.md index c7bad3c420b1..a89350c14245 100644 --- a/content/copilot/reference/copilot-usage-metrics/interpret-copilot-metrics.md +++ b/content/copilot/reference/copilot-usage-metrics/interpret-copilot-metrics.md @@ -39,19 +39,21 @@ The "Requests per chat mode" and "Agent adoption" charts show how developers are ## Reviewing {% data variables.copilot.copilot_cli_short %} customization adoption with the API -To assess how developers adopt {% data variables.copilot.copilot_cli_short %} customizations, use the usage metrics API. It reports skills, custom agents, Model Context Protocol (MCP) server connection activity, slash commands, and plugins for enterprises and organizations. The fields appear in per-user and aggregated 1-day reports, per-user 28-day reports, and aggregated 28-day `day_totals`. They are not available in the dashboard. For field definitions, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/copilot-usage-metrics#copilot-cli-customization-fields-api-only). +To assess how developers adopt customizations across {% data variables.copilot.copilot_cli_short %} and other supported clients, use the usage metrics API. It reports skills, custom agents, Model Context Protocol (MCP) server connection activity, slash commands, and plugins for enterprises and organizations. The fields appear in per-user and aggregated 1-day reports, per-user 28-day reports, and aggregated 28-day `day_totals`. They are not available in the dashboard. For field definitions, supported clients, and minimum versions for reporting names, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/copilot-usage-metrics#copilot-cli-customization-fields-api-only). `interaction_count` represents a different event for each category: skill invocations, custom agent starts, MCP connection or reconnection attempts, slash command invocations, or plugin-associated skill invocations. These values count activity events, not users. MCP counts include both successful and failed connection attempts, but not tool calls through an already connected server or ongoing server use. Every plugin interaction is already included in skill interaction counts, while skill interactions that are not associated with a plugin appear only in skill totals. Do not add plugin and skill interaction counts together. -To identify strong adoption signals, look for named customizations that appear in many users' arrays. Each array contains only the five entries with the highest interaction counts for that record. Therefore, do not interpret an absent entry as zero usage or use the arrays to calculate an exact adoption rate. +To identify strong adoption signals, look for configured customization names that appear in many users' arrays. Custom names appear in both per-user and aggregated enterprise and organization reports. Use aggregated reports to see overall adoption and per-user reports to see who uses each customization. Each customization array retains up to 25 named entries per record, plus a trailing `other` entry for remaining activity. + +The data comes from client telemetry and can undercount activity. An absent name does not mean zero usage: the customization may be outside the retained entries, its name may be unavailable, or client telemetry may be missing. Use these reports to understand trends, not to calculate exact adoption rates or verify that only approved customizations are in use. Distinct counts show how many different item identifiers had activity. At enterprise and organization scope, an identifier counts once even if many users interacted with it, so do not add per-user distinct counts to reproduce an aggregate value. Compare distinct counts across records or `day_totals` to see whether the variety of customizations with activity is changing. | Signal | What it suggests | Suggested action | |:--|:--|:--| | A named skill, custom agent, slash command, or plugin has high interaction counts across many users | The customization is broadly useful and may be a good candidate for standardization. | Promote it through internal examples, onboarding materials, or a shared customization library. | -| A named customization appears in the top five for only a few users but has high interaction counts for those users | Observed activity is concentrated among a small group. Other users may have activity outside their top-five entries. | Ask those users to share example workflows. Then use developer feedback or other internal data to assess broader adoption before expanding enablement. | -| Distinct counts are high, but most interactions are grouped under `other` | Developers are using many customer-defined customizations whose names are not exposed in the report. | Review your internal customization sources and catalogs to identify opportunities to consolidate, document, or govern overlapping options. | +| A named customization appears in the retained entries for only a few users but has high interaction counts for those users | Observed activity is concentrated among a small group. Other users may have activity outside their retained named entries. | Ask those users to share example workflows. Then use developer feedback or other internal data to assess broader adoption before expanding enablement. | +| Distinct counts are high, but most interactions are grouped under `other` or `custom` | Custom names may be unavailable, filtered because they look like file paths, or outside the retained entries. | Check client versions and telemetry coverage before drawing conclusions about which customizations are in use. | | Interaction counts remain low for a skill, custom agent, slash command, or plugin you expect developers to use | Developers may not know that the customization exists or when it is useful. | Improve discoverability with task-focused examples and include the customization in relevant onboarding or enablement sessions. | | MCP connection activity is higher or lower than expected | Developers may be reconnecting repeatedly, encountering failed connection attempts, or the planned rollout may not have reached the intended audience. Connection counts alone do not show whether developers are actively using MCP tools. | Check your MCP configuration and rollout process, then use other internal data or developer feedback to assess ongoing server use. | | Adoption grows after an enablement activity | The activity may have helped developers discover useful customizations. | Compare multiple reporting periods and gather developer feedback before deciding whether to expand the activity. | diff --git a/content/graphql/guides/managing-enterprise-accounts.md b/content/graphql/guides/managing-enterprise-accounts.md index 93e9adab8e5c..2d384c496561 100644 --- a/content/graphql/guides/managing-enterprise-accounts.md +++ b/content/graphql/guides/managing-enterprise-accounts.md @@ -35,17 +35,41 @@ With the Enterprise Accounts API, you can: * Invite administrators to your enterprise account. * Create new organizations in your enterprise account. -For a list of the fields available with the Enterprise Accounts API, see [AUTOTITLE](/graphql/guides/managing-enterprise-accounts#graphql-fields-and-types-for-the-enterprise-accounts-api). +For a list of the fields available with the Enterprise Accounts API, see [AUTOTITLE](/enterprise-cloud@latest/graphql/guides/managing-enterprise-accounts#graphql-fields-and-types-for-the-enterprise-accounts-api). + + ## Getting started using GraphQL for enterprise accounts See [AUTOTITLE](/graphql/guides/using-graphql-clients) to get started using GraphQL to manage your enterprise accounts. For some example queries, see [An example query using the Enterprise Accounts API](#an-example-query-using-the-enterprise-accounts-api). -### 1. Authenticate with your {% data variables.product.pat_generic %} +### 1. Choose an authentication method + +{% ifversion enterprise-graphql-github-apps %} + +We recommend using a {% data variables.product.prodname_github_app %} for enterprise GraphQL operations that support it. {% data variables.product.prodname_github_apps %} provide fine-grained permissions and short-lived tokens without relying on an enterprise owner's {% data variables.product.pat_generic %}. Not all enterprise GraphQL queries and mutations support {% data variables.product.prodname_github_apps %}. Use a {% data variables.product.pat_generic %} for operations that do not support them. + +#### Using a {% data variables.product.prodname_github_app %} + +1. Register a {% data variables.product.prodname_github_app %} and select the enterprise permissions needed for your operations. See [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). +1. Install the app on the enterprise you want to manage. If you are not an enterprise owner, you'll need to ask the enterprise owner to install it. See [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-on-your-enterprise). +1. Authenticate with an installation access token or a user access token, depending on the operation and whether the app needs to act on behalf of a user. The Insomnia instructions below use a user access token. + +An enterprise installation grants enterprise permissions only. It does not grant access to organizations or repositories in the enterprise. For organization or repository operations, the app needs separate installations on the relevant organizations and the appropriate permissions. Once installed in the organizations, your app can operate across them in a GraphQL query using a user access token. Installation tokens are locked to a single enterprise or organization account and cannot be used across account boundaries. + +#### Using a {% data variables.product.pat_generic %} -1. To authenticate with GraphQL, you need to generate a {% data variables.product.pat_generic %} from developer settings. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). +Use a {% data variables.product.pat_generic %} if the operation you need does not support {% data variables.product.prodname_github_apps %}, or if you are building automation to access multiple organizations or repository data in a single GraphQL query. + +{% else %} + +To authenticate with GraphQL, use a {% data variables.product.pat_generic %}. + +{% endif %} + +1. To authenticate with GraphQL with a {% data variables.product.pat_generic %}, create one in the developer settings. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). 1. Grant admin and full control permissions to your {% data variables.product.pat_generic %} for areas of your enterprise you'd like to access. For full permission to private repositories, organizations, teams, user data, and access to enterprise billing and profile data, we recommend you select these scopes for your {% data variables.product.pat_generic %}: * `repo` @@ -79,10 +103,57 @@ The next steps will use Insomnia. * For GitHub Enterprise Cloud: `https://api.github.com/graphql` * For GitHub Enterprise Cloud with Data Residency: `https://api.SUBDOMAIN.ghe.com/graphql` -1. Select the "Auth" menu and click **Bearer Token**. If you've previously selected a different authentication method, the menu will be labeled with that method, such as "Basic Auth", instead. - ![Screenshot of the expanded "Auth" menu in Insomnia. The menu label, "Auth", and the "Bearer Token" option are outlined in dark orange.](/assets/images/developer/graphql/insomnia-bearer-token-option.png) +{% ifversion enterprise-graphql-github-apps %} + +#### Authenticate with a {% data variables.product.prodname_github_app %} + +This procedure uses the OAuth 2.0 authorization code flow to obtain a {% data variables.product.prodname_github_app %} **user access token**, not an installation access token. + +1. In your app's settings, set **Callback URL** to `http://localhost`. This must exactly match the **Redirect URL** you use in Insomnia. +1. Copy your app's **Client ID**, not its App ID. Generate and copy a client secret. Keep the secret secure and do not share it in screenshots or source code. This flow does not use the app's private key. +1. In Insomnia, select the **Auth** tab, then select **OAuth 2.0**. If you've previously selected a different authentication method, the tab may be labeled with that method. +1. Configure these settings with your own app's credentials. + + | Setting | Value | + | --- | --- | + | Enabled | ✔️ | + | Grant Type | Authorization Code | + | Authorization URL | `https://github.com/login/oauth/authorize` | + | Access Token URL | `https://github.com/login/oauth/access_token` | + | Client ID | Your app's Client ID | + | Client Secret | Your app's client secret | + | Use PKCE | {% ifversion pkce_support %}Selected{% else %}Deselected{% endif %} | + | {% ifversion pkce_support %} | + | Code Challenge Method | SHA-256 | + | {% endif %} | + | Redirect URL | `http://localhost` | + | Using default browser | Leave unchecked unless your enterprise has SSO enabled, which may fail in Insomnia's embedded browser. If it has SSO enabled, check this box and follow the directions for updating your app's redirect URL | + | Scope | Leave empty. {% data variables.product.prodname_github_apps %} use permissions from the app registration, not OAuth scopes. | + + {% ifversion ghes %} + In both OAuth URLs, replace `https://github.com` with your instance's web URL, such as `https://HOSTNAME`. Do not use an API hostname or add `/api/v3`. + {% else %} + If you use {% data variables.product.prodname_ghe_cloud %} with data residency, replace `https://github.com` in both OAuth URLs with `https://SUBDOMAIN.ghe.com`, where `SUBDOMAIN` is your enterprise's subdomain. Use the web URL, not the `api.SUBDOMAIN.ghe.com` hostname. + {% endif %} + +1. Click **Fetch Tokens**, sign in, and authorize the app as a user with the required enterprise permissions. The user access token is limited to the permissions and resources that both the user and the app can access. Insomnia uses the fetched token for your requests. + +For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). + +#### Authenticate with a {% data variables.product.pat_generic %} + +If you use a {% data variables.product.pat_generic %} instead, configure bearer authentication. + +{% endif %} + +1. Select the **Auth** menu and click **Bearer Token**. If you've previously selected a different authentication method, the menu will be labeled with that method, such as "Basic Auth", instead. 1. In the "TOKEN" field, enter your {% data variables.product.pat_generic %} from an earlier step. ![Screenshot of the "Bearer" authentication settings in Insomnia. The "TOKEN" field is outlined in dark orange.](/assets/images/developer/graphql/insomnia-base-url-and-pat.png) + +#### Set the content type + +After configuring your authentication method, set the request's content type. + 1. Click **Headers**. ![Screenshot of the settings tabs in Insomnia. The "Headers" tab is outlined in dark orange.](/assets/images/developer/graphql/json-content-type-header.png) 1. Under the **Headers** tab, click **Add**. diff --git a/content/pull-requests/how-tos/merge-and-close-pull-requests/automatically-merging-a-pull-request.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/automatically-merging-a-pull-request.md index 870ed8b48ee3..f026e6e8424e 100644 --- a/content/pull-requests/how-tos/merge-and-close-pull-requests/automatically-merging-a-pull-request.md +++ b/content/pull-requests/how-tos/merge-and-close-pull-requests/automatically-merging-a-pull-request.md @@ -20,6 +20,8 @@ contentType: how-tos Auto-merge merges a pull request automatically after all required reviews and status checks pass. Before you use auto-merge, it must be enabled for the repository. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository). +On a branch that requires a merge queue, the repository setting doesn't apply. **Merge when ready** enables auto-merge for a pull request that can't be added to the queue immediately, even if auto-merge isn't allowed for the repository. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request-with-a-merge-queue). + Auto-merge is disabled if someone without write permissions pushes new changes to the head branch or switches the base branch. ## Enabling auto-merge diff --git a/content/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request-with-a-merge-queue.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request-with-a-merge-queue.md index 2820d28e062d..fd6793b6a5e9 100644 --- a/content/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request-with-a-merge-queue.md +++ b/content/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request-with-a-merge-queue.md @@ -40,7 +40,9 @@ A merge queue helps merge pull requests into a busy protected branch after requi ![Screenshot of the merge queue options for a pull request.](/assets/images/help/pull_requests/merge-queue-options.png) > [!NOTE] - > You can click **Merge when ready** before all requirements pass. {% data variables.product.github %} adds the pull request to the queue when requirements are met. + > You can click **Merge when ready** before all requirements pass. If the pull request can't be added to the queue immediately, {% data variables.product.github %} enables auto-merge and adds the pull request to the queue when requirements are met, even if **Allow auto-merge** is disabled for the repository. + + To cancel this waiting state, click **Disable auto-merge** in the merge box. 1. Confirm you want to add the pull request to the merge queue by clicking **Confirm merge when ready**. @@ -50,6 +52,8 @@ A merge queue helps merge pull requests into a busy protected branch after requi With {% data variables.product.prodname_cli %}, use the `gh pr merge` command to add a pull request to a merge queue. If you are targeting a branch that requires a merge queue, this command automatically adds the pull request to the queue if required checks have passed. If required checks have not passed, this command enables auto-merge for the pull request. See [`gh pr merge`](https://cli.github.com/manual/gh_pr_merge) in the {% data variables.product.prodname_cli %} manual. +To add a pull request to the queue only if it can be added immediately, without enabling auto-merge, use the [`enqueuePullRequest`](/graphql/reference/pulls#mutation-enqueuepullrequest) GraphQL mutation. If the pull request can't be added, the mutation returns an error that explains why. + {% endcli %} ## Removing a pull request from a merge queue diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository.md b/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository.md index 9b6eaa759ef3..507c70de7678 100644 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository.md +++ b/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository.md @@ -18,6 +18,8 @@ category: If you allow auto-merge for pull requests in your repository, people with write permissions can configure individual pull requests in the repository to merge automatically when all merge requirements are met. If someone who does not have write permissions pushes changes to a pull request that has auto-merge enabled, auto-merge will be disabled for that pull request. For more information, see [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/automatically-merging-a-pull-request). +The **Allow auto-merge** setting doesn't apply to branches that require a merge queue. On those branches, **Merge when ready** can enable auto-merge for a pull request even when this setting is disabled. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request-with-a-merge-queue). + ## Managing auto-merge {% data reusables.pull_requests.auto-merge-requires-branch-protection %} diff --git a/data/features/enterprise-graphql-github-apps.yml b/data/features/enterprise-graphql-github-apps.yml new file mode 100644 index 000000000000..fd47f863f716 --- /dev/null +++ b/data/features/enterprise-graphql-github-apps.yml @@ -0,0 +1,4 @@ +# GitHub App authentication for supported enterprise GraphQL operations +versions: + ghec: '*' + ghes: '>=3.24' diff --git a/src/content-pipelines/state/copilot-cli.sha b/src/content-pipelines/state/copilot-cli.sha index 32b895154e8d..32c0cb67ae0c 100644 --- a/src/content-pipelines/state/copilot-cli.sha +++ b/src/content-pipelines/state/copilot-cli.sha @@ -1 +1 @@ -394f59ad9f91b3772c5ca6d45ebd8ce48150e9b7 +a0cbc17f81ef21de58842d0aeace7e2b6dbebb27