From 20524d5019f1525d233dad591078e233bae28792 Mon Sep 17 00:00:00 2001 From: Kevin Heis Date: Thu, 16 Jul 2026 13:48:49 -0700 Subject: [PATCH 01/12] Step webapp maxSurge 50% -> 100% to speed deploys (#62293) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a672a7f9-31cb-4c55-b615-9caee7452b61 --- config/kubernetes/production/deployments/webapp.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/kubernetes/production/deployments/webapp.yaml b/config/kubernetes/production/deployments/webapp.yaml index f494d099cfae..c8d52bddf369 100644 --- a/config/kubernetes/production/deployments/webapp.yaml +++ b/config/kubernetes/production/deployments/webapp.yaml @@ -14,7 +14,7 @@ spec: # Prevents capacity loss during deploys. Safe because we're over-provisioned. maxUnavailable: 0 # Percentage so it scales with replica count changes. - maxSurge: '50%' + maxSurge: '100%' selector: matchLabels: app: webapp From ae22ec720e4005d53463f1a0690b37ed9fda0db9 Mon Sep 17 00:00:00 2001 From: "release-controller[bot]" <110195724+release-controller[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 20:48:53 +0000 Subject: [PATCH 02/12] Patch release notes for GitHub Enterprise Server (#62283) Co-authored-by: Release-Controller Co-authored-by: isaacmbrown Co-authored-by: Pallavi <96553709+pallsama@users.noreply.github.com> Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com> Co-authored-by: Shilpa Kumari <82128924+shilpakum@users.noreply.github.com> --- .../enterprise-server/3-17/17.yml | 2 - .../enterprise-server/3-17/18.yml | 91 +++++++++++++++ .../enterprise-server/3-18/12.yml | 97 ++++++++++++++++ .../enterprise-server/3-18/5.yml | 40 +++---- .../enterprise-server/3-19/2.yml | 42 +++---- .../enterprise-server/3-19/9.yml | 107 ++++++++++++++++++ .../enterprise-server/3-20/5.yml | 103 +++++++++++++++++ .../enterprise-server/3-21/2.yml | 2 - .../enterprise-server/3-21/3.yml | 96 ++++++++++++++++ 9 files changed, 535 insertions(+), 45 deletions(-) create mode 100644 data/release-notes/enterprise-server/3-17/18.yml create mode 100644 data/release-notes/enterprise-server/3-18/12.yml create mode 100644 data/release-notes/enterprise-server/3-19/9.yml create mode 100644 data/release-notes/enterprise-server/3-20/5.yml create mode 100644 data/release-notes/enterprise-server/3-21/3.yml diff --git a/data/release-notes/enterprise-server/3-17/17.yml b/data/release-notes/enterprise-server/3-17/17.yml index d271411d409e..4b646b3faa39 100644 --- a/data/release-notes/enterprise-server/3-17/17.yml +++ b/data/release-notes/enterprise-server/3-17/17.yml @@ -66,8 +66,6 @@ sections: When restoring from a backup snapshot, a large number of `mapper_parsing_exception` errors may be displayed. - | When initializing a new GHES cluster, nodes with the `consul-server` role should be added to the cluster before adding additional nodes. Adding all nodes simultaneously creates a race condition between nomad server registration and nomad client registration. - - | - When initializing a new GHES cluster, nodes with the `consul-server` role should be added to the cluster before adding additional nodes. Adding all nodes simultaneously creates a race condition between nomad server registration and nomad client registration. - | In a cluster, the host running restore requires access to the storage nodes via their private IPs. - | diff --git a/data/release-notes/enterprise-server/3-17/18.yml b/data/release-notes/enterprise-server/3-17/18.yml new file mode 100644 index 000000000000..576a00fa6a30 --- /dev/null +++ b/data/release-notes/enterprise-server/3-17/18.yml @@ -0,0 +1,91 @@ +date: '2026-07-16' +intro: | + > [!NOTE] As part of a security enhancement to {% data variables.product.prodname_ghe_server %} support bundle uploads, {% data variables.product.company_short %} will begin rejecting uploads from older unpatched appliances on August 18, 2026. Please update to this patch release to avoid interruptions when submitting support bundles with `ghe-support-bundle`, `ghe-cluster-support-bundle`, or `ghe-support-upload`. The minimum required patch versions to submit support bundles are 3.21.3, 3.20.5, 3.19.9, 3.18.12, and 3.17.18. If you cannot update to the required patch version before August 18, 2026, and need to upload a support bundle, contact [GitHub Support](https://support.github.com/enterprise-and-teams#enterprise-administrators-server) for guidance. +sections: + features: + - | + Site administrators can configure a customer-managed cloud object store (Amazon S3, Azure Blob Storage, or Google Cloud Storage) as an Elasticsearch snapshot repository. This enables incremental Elasticsearch snapshots for backup, restore, and disaster recovery. Management scripts are available for manual snapshot operations and testing. + security_fixes: + - | + **HIGH**: An attacker who had code execution inside the Dependabot updater container could write attacker-controlled files to arbitrary paths in a repository that Dependabot updates, including GitHub Actions workflow files. This was possible because dependency-file path validation checked only the declared file name and not the effective path derived from the file's directory and symlink target. If the repository used a pull_request_target workflow or had auto-merge enabled, the injected workflow could execute with access to the repository's GitHub Actions secrets. GitHub has requested CVE ID [CVE-2026-15343](https://www.cve.org/cverecord?id=CVE-2026-15343) for this vulnerability. + - | + **MEDIUM**: An attacker could render a GitHub Enterprise Server instance unresponsive, causing a denial of service, by adding a repository release notes configuration file containing deeply nested YAML and then generating release notes. GitHub has requested CVE ID [CVE-2026-15007](https://www.cve.org/cverecord?id=CVE-2026-15007) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + - | + **MEDIUM**: An attacker with write access to any repository on a GitHub Enterprise Server instance could read metadata from private repositories they could not access, including repository owners and names, branch names, commit SHAs, commit messages, and the pushing actor because the delegated bypass endpoint resolved a rule suite from an attacker-supplied identifier without checking that the user could read its repository, and these sequential identifiers could be enumerated. GitHub has requested CVE ID [CVE-2026-15783](https://www.cve.org/cverecord?id=CVE-2026-15783) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + - | + Packages have been updated to the latest security versions. + bugs: + - | + Administrators experienced "Permission denied" errors when the `ghes-manage-agent` attempted to write logs under `/var/log/license-upgrade` during license upgrade restart tasks. + - | + Users experienced `ghe-maintenance -q` reporting that maintenance mode was not set when only `maintenance-git.html` remained after a replication restart. GHES now removes the dangling git maintenance lock during `ghe-repl-start` and reports maintenance mode correctly. + - | + On an instance where an administrator configured `logrotate.maxsize` via `ghe-config` with a non-gigabyte unit suffix (for example, `256M` or `512k`), the resulting logrotate configuration was invalid, which silently stopped log rotation and could allow logs to fill the disk. + - | + `ghe-config-apply` showed a validation warning when more than one `github-stream-processors` container ran, even when multiple allocations are expected to be scheduled. + - | + After an upgrade, `ghe-config-apply` could fail with `rake aborted! VERSIONS must be a comma-separated list of integers` when completing post-upgrade live migrations due to corrupted command output in the transitions value. + - | + On an instance with clustering or high availability configured, setting up MySQL replication on a replica node sometimes failed during a configuration apply. The failure occurred intermittently when MySQL restarted before the setup process could complete. + - | + Organization owners, security managers, and enterprise administrators in some configurations experienced validation errors when they tried to modify code security configurations after upgrading GitHub Enterprise Server if the instance had uninstalled security products. + - | + Suspended users were listed in an organization team's list of members. + - | + On instances that served GraphQL API requests over an extended period without restarting, memory usage on the appliance grew continuously without an upper bound. This could lead to degraded performance or resource exhaustion on long-running instances. Deferred GraphQL query state is now properly released after each request completes. + - | + When multiple users updated labels on the same issue or pull request at the same time, labels added by one user could be lost. + changes: + - | + Organization owners can configure source and target access tokens for Enterprise Live Migrations in their organization settings. Previously, these tokens needed to be configured in the terminal over SSH. + - | + The default `maxconn` (maximum connections) value for HAProxy has increased from 1,024 to 8,192 across all proxies. Previously, large customers reported surpassing the limit on high-traffic services. + - | + Administrators who lose access to both SSH and the Management Console can recover their instance by selecting recovery mode from the GRUB boot menu, which is now displayed during boot for 10 seconds. + known_issues: + - | + During an upgrade of GitHub Enterprise Server, custom firewall rules are removed. If you use custom firewall rules, you must reapply them after upgrading. + - | + During the validation phase of a configuration run, a `No such object` error may occur for the Notebook and Viewscreen services. This error can be ignored as the services should still correctly start. + - | + If the root site administrator is locked out of the Management Console after failed login attempts, the account does not unlock automatically after the defined lockout time. Someone with administrative SSH access to the instance must unlock the account using the administrative shell. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-web-ui/troubleshooting-access-to-the-management-console#unlocking-the-root-site-administrator-account). + - | + On an instance with the HTTP `X-Forwarded-For` header configured for use behind a load balancer, all client IP addresses in the instance's audit log erroneously appear as 127.0.0.1. + - | + {% data reusables.release-notes.large-adoc-files-issue %} + - | + Admin stats REST API endpoints may timeout on appliances with many users or repositories. Retrying the request until data is returned is advised. + - | + When following the steps for [Replacing the primary MySQL node](/admin/monitoring-managing-and-updating-your-instance/configuring-clustering/replacing-a-cluster-node#replacing-the-primary-mysql-node), step 14 (running `ghe-cluster-config-apply`) might fail with errors. If this occurs, re-running `ghe-cluster-config-apply` is expected to succeed. + - | + Running a config apply as part of the steps for [Replacing a node in an emergency](/admin/monitoring-managing-and-updating-your-instance/configuring-clustering/replacing-a-cluster-node#replacing-a-node-in-an-emergency) may fail with errors if the node being replaced is still reachable. If this occurs, shutdown the node and repeat the steps. + - | + {% data reusables.release-notes.2024-06-possible-frontend-5-minute-outage-during-hotpatch-upgrade %} + - | + When restoring data originally backed up from a 3.13 or greater appliance version, the Elasticsearch indices need to be reindexed before some of the data will show up. This happens via a nightly scheduled job. It can also be forced by running `/usr/local/share/enterprise/ghe-es-search-repair`. + - | + An organization-level code scanning configuration page is displayed on instances that do not use GitHub Advanced Security or code scanning. + - | + When enabling automatic update checks for the first time in the Management Console, the status is not dynamically reflected until the "Updates" page is reloaded. + - | + When restoring from a backup snapshot, a large number of `mapper_parsing_exception` errors may be displayed. + - | + When initializing a new GHES cluster, nodes with the `consul-server` role should be added to the cluster before adding additional nodes. Adding all nodes simultaneously creates a race condition between nomad server registration and nomad client registration. + - | + In a cluster, the host running restore requires access the storage nodes via their private IPs. + - | + On an instance hosted on Azure, commenting on an issue via email meant the comment was not added to the issue. + - | + After a restore, existing outside collaborators cannot be added to repositories in a new organization. This issue can be resolved by running `/usr/local/share/enterprise/ghe-es-search-repair` on the appliance. + - | + After a geo-replica is promoted to be a primary by running `ghe-repl-promote`, the actions workflow of a repository does not have any suggested workflows. + - | + Unexpected elements may appear in the UI on the repository overview page for locked repositories. + - | + When publishing npm packages in a workflow after restoring from a backup to GitHub Enterprise Server 3.13.5.gm4 or 3.14.2.gm3, you may encounter a `401 Unauthorized` error from the GitHub Packages service. This can happen if the restore is from an N-1 or N-2 version and the workflow targets the npm endpoint on the backup instance. To avoid this issue, ensure the access token is valid and includes the correct scopes for publishing to GitHub Packages. + - | + When applying an enterprise security configuration to all repositories (for example, enabling Secret Scanning or Code Scanning across all repositories), the system immediately enqueues enablement jobs for every organization in the enterprise simultaneously. For enterprises with a large number of repositories, this can result in significant system load and potential performance degradation. If you manage a large enterprise with many organizations and repositories, we recommend applying security configurations at the organization level rather than at the enterprise level in the UI. This allows you to enable security features incrementally and monitor system performance as you roll out changes. + - | + Git versions are mismatched between containers on the instance. + - | + Administrators upgrading to certain patch releases encountered a "Failed to generate an OIDC token" error during the `Update Servicing Resources` step when GitHub Actions was configured with Google Cloud Storage (GCS) or AWS S3 using OpenID Connect (OIDC) authentication. The upgrade was blocked and could not complete. To work around this issue, administrators could apply a manual patch by running `sudo sed -i.bak 's|ghe-actions-console -s -c Update-Service|ghe-actions-console -s --no-blob-creds -c Update-Service|g' /usr/local/bin/ghe-actions-update` followed by `ghe-config-apply`. diff --git a/data/release-notes/enterprise-server/3-18/12.yml b/data/release-notes/enterprise-server/3-18/12.yml new file mode 100644 index 000000000000..ffb24c202111 --- /dev/null +++ b/data/release-notes/enterprise-server/3-18/12.yml @@ -0,0 +1,97 @@ +date: '2026-07-16' +intro: | + > [!NOTE] As part of a security enhancement to {% data variables.product.prodname_ghe_server %} support bundle uploads, {% data variables.product.company_short %} will begin rejecting uploads from older unpatched appliances on August 18, 2026. Please update to this patch release to avoid interruptions when submitting support bundles with `ghe-support-bundle`, `ghe-cluster-support-bundle`, or `ghe-support-upload`. The minimum required patch versions to submit support bundles are 3.21.3, 3.20.5, 3.19.9, 3.18.12, and 3.17.18. If you cannot update to the required patch version before August 18, 2026, and need to upload a support bundle, contact [GitHub Support](https://support.github.com/enterprise-and-teams#enterprise-administrators-server) for guidance. +sections: + features: + - | + Site administrators can configure a customer-managed cloud object store (Amazon S3, Azure Blob Storage, or Google Cloud Storage) as an Elasticsearch snapshot repository. This enables incremental Elasticsearch snapshots for backup, restore, and disaster recovery. Management scripts are available for manual snapshot operations and testing. + security_fixes: + - | + **HIGH**: An attacker who had code execution inside the Dependabot updater container could write attacker-controlled files to arbitrary paths in a repository that Dependabot updates, including GitHub Actions workflow files. This was possible because dependency-file path validation checked only the declared file name and not the effective path derived from the file's directory and symlink target. If the repository used a pull_request_target workflow or had auto-merge enabled, the injected workflow could execute with access to the repository's GitHub Actions secrets. GitHub has requested CVE ID [CVE-2026-15343](https://www.cve.org/cverecord?id=CVE-2026-15343) for this vulnerability. + - | + **MEDIUM**: An attacker could render a GitHub Enterprise Server instance unresponsive, causing a denial of service, by adding a repository release notes configuration file containing deeply nested YAML and then generating release notes. GitHub has requested CVE ID [CVE-2026-15007](https://www.cve.org/cverecord?id=CVE-2026-15007) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + - | + **MEDIUM**: An attacker with write access to any repository on a GitHub Enterprise Server instance could read metadata from private repositories they could not access, including repository owners and names, branch names, commit SHAs, commit messages, and the pushing actor because the delegated bypass endpoint resolved a rule suite from an attacker-supplied identifier without checking that the user could read its repository, and these sequential identifiers could be enumerated. GitHub has requested CVE ID [CVE-2026-15783](https://www.cve.org/cverecord?id=CVE-2026-15783) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + - | + Packages have been updated to the latest security versions. + bugs: + - | + Users experienced `ghe-maintenance -q` reporting that maintenance mode was not set when only `maintenance-git.html` remained after a replication restart. GHES now removes the dangling git maintenance lock during `ghe-repl-start` and reports maintenance mode correctly. + - | + On an instance where an administrator configured `logrotate.maxsize` via `ghe-config` with a non-gigabyte unit suffix (for example, `256M` or `512k`), the resulting logrotate configuration was invalid, which silently stopped log rotation and could allow logs to fill the disk. + - | + `ghe-config-apply` showed a validation warning when more than one `github-stream-processors` container ran, even when multiple allocations are expected to be scheduled. + - | + After an upgrade, `ghe-config-apply` could fail with `rake aborted! VERSIONS must be a comma-separated list of integers` when completing post-upgrade live migrations due to corrupted command output in the transitions value. + - | + On the Management Consoles monitor dashboard, the Memory and Disk usage panels on the Operational Health dashboard displayed values on the vertical axis as raw bytes (for example, `500000000000`) instead of human-readable units. + - | + On an instance with clustering or high availability configured, setting up MySQL replication on a replica node sometimes failed during a configuration apply. The failure occurred intermittently when MySQL restarted before the setup process could complete. + - | + When multiple users updated labels on the same issue or pull request at the same time, labels added by one user could be lost. + - | + Organization owners, security managers, and enterprise administrators in some configurations experienced validation errors when they tried to modify code security configurations after upgrading GitHub Enterprise Server if the instance had uninstalled security products. + - | + Suspended users were listed in an organization team's list of members. + - | + On instances that served GraphQL API requests over an extended period without restarting, memory usage on the appliance grew continuously without an upper bound. This could lead to degraded performance or resource exhaustion on long-running instances. Deferred GraphQL query state is now properly released after each request completes. + changes: + - | + Organization owners can configure source and target access tokens for Enterprise Live Migrations in their organization settings. Previously, these tokens needed to be configured in the terminal over SSH. + - | + The default `maxconn` (maximum connections) value for HAProxy has increased from 1,024 to 8,192 across all proxies. Previously, large customers reported surpassing the limit on high-traffic services. + - | + Site administrators can configure the maximum size of archives exported by `ghe-migrator` by setting the `GHECM_EXPORT_ARCHIVE_MAX_SIZE_GB` environment variable. Previously, exports were subject to an 80 GB limit, which could prevent large GHES-to-GHES migrations from completing. Setting the variable to `0` removes the limit entirely. + - | + Administrators who lose access to both SSH and the Management Console can recover their instance by selecting recovery mode from the GRUB boot menu, which is now displayed during boot for 10 seconds. + - | + To guard against rare image corruption caused by an unexpected restart or interruption during an upgrade, the integrity of Docker images is now verified after an upgrade completes. If a corrupted image is detected, a warning is logged so an administrator can recover it. + known_issues: + - | + During an upgrade of GitHub Enterprise Server, custom firewall rules are removed. If you use custom firewall rules, you must reapply them after upgrading. + - | + During the validation phase of a configuration run, a `No such object` error may occur for the Notebook and Viewscreen services. This error can be ignored as the services should still correctly start. + - | + If the root site administrator is locked out of the Management Console after failed login attempts, the account does not unlock automatically after the defined lockout time. Someone with administrative SSH access to the instance must unlock the account using the administrative shell. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-web-ui/troubleshooting-access-to-the-management-console#unlocking-the-root-site-administrator-account). + - | + On an instance with the HTTP `X-Forwarded-For` header configured for use behind a load balancer, all client IP addresses in the instance's audit log erroneously appear as 127.0.0.1. + - | + {% data reusables.release-notes.large-adoc-files-issue %} + - | + Admin stats REST API endpoints may timeout on appliances with many users or repositories. Retrying the request until data is returned is advised. + - | + When following the steps for [Replacing the primary MySQL node](/admin/monitoring-managing-and-updating-your-instance/configuring-clustering/replacing-a-cluster-node#replacing-the-primary-mysql-node), step 14 (running `ghe-cluster-config-apply`) might fail with errors. If this occurs, re-running `ghe-cluster-config-apply` is expected to succeed. + - | + Running a config apply as part of the steps for [Replacing a node in an emergency](/admin/monitoring-managing-and-updating-your-instance/configuring-clustering/replacing-a-cluster-node#replacing-a-node-in-an-emergency) may fail with errors if the node being replaced is still reachable. If this occurs, shutdown the node and repeat the steps. + - | + {% data reusables.release-notes.2024-06-possible-frontend-5-minute-outage-during-hotpatch-upgrade %} + - | + When restoring data originally backed up from a 3.13 or greater appliance version, the Elasticsearch indices need to be reindexed before some of the data will show up. This happens via a nightly scheduled job. It can also be forced by running `/usr/local/share/enterprise/ghe-es-search-repair`. + - | + An organization-level code scanning configuration page is displayed on instances that do not use GitHub Advanced Security or code scanning. + - | + When enabling automatic update checks for the first time in the Management Console, the status is not dynamically reflected until the "Updates" page is reloaded. + - | + When restoring from a backup snapshot, a large number of `mapper_parsing_exception` errors may be displayed. + - | + When initializing a new GHES cluster, nodes with the `consul-server` role should be added to the cluster before adding additional nodes. Adding all nodes simultaneously creates a race condition between nomad server registration and nomad client registration. + - | + In a cluster, the host running restore requires access the storage nodes via their private IPs. + - | + On an instance hosted on Azure, commenting on an issue via email meant the comment was not added to the issue. + - | + After a restore, existing outside collaborators cannot be added to repositories in a new organization. This issue can be resolved by running `/usr/local/share/enterprise/ghe-es-search-repair` on the appliance. + - | + After a geo-replica is promoted to be a primary by running `ghe-repl-promote`, the actions workflow of a repository does not have any suggested workflows. + - | + Unexpected elements may appear in the UI on the repository overview page for locked repositories. + - | + When publishing npm packages in a workflow after restoring from a backup to GitHub Enterprise Server 3.13.5.gm4 or 3.14.2.gm3, you may encounter a `401 Unauthorized` error from the GitHub Packages service. This can happen if the restore is from an N-1 or N-2 version and the workflow targets the npm endpoint on the backup instance. To avoid this issue, ensure the access token is valid and includes the correct scopes for publishing to GitHub Packages. + - | + The setting to define private registries at the organization level for code scanning is only available if dependabot is also enabled for the instance. + - | + Custom NTP settings are removed during the upgrade process. + - | + When applying an enterprise security configuration to all repositories (for example, enabling Secret Scanning or Code Scanning across all repositories), the system immediately enqueues enablement jobs for every organization in the enterprise simultaneously. For enterprises with a large number of repositories, this can result in significant system load and potential performance degradation. If you manage a large enterprise with many organizations and repositories, we recommend applying security configurations at the organization level rather than at the enterprise level in the UI. This allows you to enable security features incrementally and monitor system performance as you roll out changes. + - | + Administrators upgrading to certain patch releases encountered a "Failed to generate an OIDC token" error during the `Update Servicing Resources` step when GitHub Actions was configured with Google Cloud Storage (GCS) or AWS S3 using OpenID Connect (OIDC) authentication. The upgrade was blocked and could not complete. To work around this issue, administrators could apply a manual patch by running `sudo sed -i.bak 's|ghe-actions-console -s -c Update-Service|ghe-actions-console -s --no-blob-creds -c Update-Service|g' /usr/local/bin/ghe-actions-update` followed by `ghe-config-apply`. diff --git a/data/release-notes/enterprise-server/3-18/5.yml b/data/release-notes/enterprise-server/3-18/5.yml index 8f6096e2c1b1..43da974bea23 100644 --- a/data/release-notes/enterprise-server/3-18/5.yml +++ b/data/release-notes/enterprise-server/3-18/5.yml @@ -2,53 +2,53 @@ date: '2026-02-10' sections: features: - | - Administrators can configure advanced SMTP settings for improved email delivery performance and reliability. These settings map to Postfix configuration parameters as documented in the Postfix documentation. New options include: + Administrators can configure advanced SMTP settings for improved email delivery performance and reliability. These settings map to Postfix configuration parameters as documented in the Postfix documentation. New options include: - IPv4-only relay: Route email to addresses at a specific email domain through an IPv4-only relay host. Setting `smtp.ipv4-only` to `true` configures Postfix to route all email to the domain specified in `smtp.relay-domain` through `smtp.relay-host` on port `smtp.relay-port` using IPv4 only. - Connection caching: Control connection reuse and caching (`smtp.connection-cache-time-limit`, `smtp.connection-reuse-count-limit`, `smtp.connection-cache-on-demand`). - Delivery concurrency: Tune parallel email delivery limits (`smtp.destination-concurrency-limit`, `smtp.initial-destination-concurrency`, `smtp.destination-concurrency-positive-feedback`). - Queue management: Configure retry timing and queue processing (`smtp.maximal-backoff-time`, `smtp.queue-run-delay`) - Connection limits: Set maximum inbound SMTP connections (`smtp.client-connection-count-limit`). - | - For administrators using geo-replication or high availability (HA), `ghe-repl` tooling supports cross-cluster replication (CCR) for Elasticsearch, improving search index replication between instances. + For administrators using geo-replication or high availability (HA), `ghe-repl` tooling supports cross-cluster replication (CCR) for Elasticsearch, improving search index replication between instances. security_fixes: - | - **MEDIUM:** By supplying the migration identifier, an attacker could upload unauthorized content to another user’s repository migration export due to a missing authorization check. This could cause victims to download attacker-controlled migration archives, potentially impacting the integrity of downstream repository imports. GitHub has requested a CVE ID [CVE-2026-1355](https://www.cve.org/cverecord?id=CVE-2026-1355) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + **MEDIUM:** By supplying the migration identifier, an attacker could upload unauthorized content to another user’s repository migration export due to a missing authorization check. This could cause victims to download attacker-controlled migration archives, potentially impacting the integrity of downstream repository imports. GitHub has requested a CVE ID [CVE-2026-1355](https://www.cve.org/cverecord?id=CVE-2026-1355) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). - | - **LOW:** GitHub Enterprise Server included React versions 19.0, 19.1, and 19.2 in its package, which contain vulnerabilities in the React Server Components protocol ([CVE-2025-55182](https://www.cve.org/cverecord?id=CVE-2025-55182), [CVE-2025-66478](https://www.cve.org/cverecord?id=CVE-2025-66478). GitHub Enterprise Server does not use React Server Components and was not vulnerable to exploitation. React has been updated to version 19.2.1 to address findings from security scanning tools. + **LOW:** GitHub Enterprise Server included React versions 19.0, 19.1, and 19.2 in its package, which contain vulnerabilities in the React Server Components protocol ([CVE-2025-55182](https://www.cve.org/cverecord?id=CVE-2025-55182), [CVE-2025-66478](https://www.cve.org/cverecord?id=CVE-2025-66478). GitHub Enterprise Server does not use React Server Components and was not vulnerable to exploitation. React has been updated to version 19.2.1 to address findings from security scanning tools. - | - **HIGH:** An attacker could merge their own pull request into a repository that allowed forks and for which they didn't have write access, by exploiting an incorrect authorization check in the `enable_auto_merge` mutation for pull requests in specific scenarios. Exploitation required a clean pull request status and only applied to branches without branch protection rules enabled. GitHub has requested CVE ID [CVE-2026-1999](https://www.cve.org/cverecord?id=CVE-2026-1999) for this vulnerability, which was reported via the [GitHub Bug Bounty](https://bounty.github.com/) program. + **HIGH:** An attacker could merge their own pull request into a repository that allowed forks and for which they didn't have write access, by exploiting an incorrect authorization check in the `enable_auto_merge` mutation for pull requests in specific scenarios. Exploitation required a clean pull request status and only applied to branches without branch protection rules enabled. GitHub has requested CVE ID [CVE-2026-1999](https://www.cve.org/cverecord?id=CVE-2026-1999) for this vulnerability, which was reported via the [GitHub Bug Bounty](https://bounty.github.com/) program. - | - **HIGH:** An authenticated attacker could exploit a URL redirection vulnerability in GitHub Enterprise Server to leak privileged authorization tokens by redirecting requests to an attacker-controlled domain. This could allow exfiltration of the `Actions.ManageOrgs` JWT and potential remote code execution. This vulnerability was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + **HIGH:** An authenticated attacker could exploit a URL redirection vulnerability in GitHub Enterprise Server to leak privileged authorization tokens by redirecting requests to an attacker-controlled domain. This could allow exfiltration of the `Actions.ManageOrgs` JWT and potential remote code execution. This vulnerability was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). bugs: - | - The Elasticsearch panel in the Operational Health dashboard of the Management Console did not correctly represent the clusters health. As a result, administrators may have seen inaccurate status indicators for Elasticsearch availability and performance. + The Elasticsearch panel in the Operational Health dashboard of the Management Console did not correctly represent the cluster's health. As a result, administrators may have seen inaccurate status indicators for Elasticsearch availability and performance. - | - Alambic failed to start after reboot or upgrade if legacy multi-disk for alambic was set up. + Alambic failed to start after reboot or upgrade if legacy multi-disk for alambic was set up. - | - GitHub Enterprise Server Backup Service (preview) was disabled after upgrading. + GitHub Enterprise Server Backup Service (preview) was disabled after upgrading. - | - Running `ghe-config-apply` could fail if Redis experienced transient connectivity issues during the configuration process. + Running `ghe-config-apply` could fail if Redis experienced transient connectivity issues during the configuration process. - | - Administrators could not use the "Clear dependencies" tool in the site admin dashboard because the required RESET_MANIFESTS_CONSUMER_GROUP environment variable was missing. + Administrators could not use the "Clear dependencies" tool in the site admin dashboard because the required RESET_MANIFESTS_CONSUMER_GROUP environment variable was missing. - | - When administrators configured password authentication, the Prometheus endpoint for OpenTelemetry metrics failed to expose metrics due to health check failures. + When administrators configured password authentication, the Prometheus endpoint for OpenTelemetry metrics failed to expose metrics due to health check failures. - | - When administrators would apply configuration changes via the management console, the state shown would occasionally briefly flicker to a failure before being marked as successful causing confusion as to whether the configuration had succeeded. + When administrators would apply configuration changes via the management console, the state shown would occasionally briefly flicker to a failure before being marked as successful causing confusion as to whether the configuration had succeeded. - | - Organization creation would fail with a 500 error when the system attempted to verify CAPTCHA responses even when no CAPTCHA challenge would be presented to the user. + Organization creation would fail with a 500 error when the system attempted to verify CAPTCHA responses even when no CAPTCHA challenge would be presented to the user. - | - On an instance configured behind a load balancer, users received unexpected secondary rate limit warnings during authentication when the `X-Forwarded-For` header included port numbers. This occurred because the system incorrectly ignored the header values containing ports, preventing proper client IP address identification. + On an instance configured behind a load balancer, users received unexpected secondary rate limit warnings during authentication when the `X-Forwarded-For` header included port numbers. This occurred because the system incorrectly ignored the header values containing ports, preventing proper client IP address identification. - | - Users with read access to a repository were unable to close issues even when granted the "Close issue" fine-grained permission through custom repository roles. Permission checks were relying solely on the triager role when evaluating a users ability to close issues. + Users with read access to a repository were unable to close issues even when granted the "Close issue" fine-grained permission through custom repository roles. Permission checks were relying solely on the triager role when evaluating a users ability to close issues. - | - Push rejections due to custom pre-receive hooks were not visible in the audit log. + Push rejections due to custom pre-receive hooks were not visible in the audit log. - | - Users could only view webhook deliveries from the previous three days. + Users could only view webhook deliveries from the previous three days. changes: - | - Administrators can configure database connection pool limits for the authentication and authorization services to improve performance on instances experiencing high concurrent request volumes. The limits can be adjusted using `ghe-config` keys: `app.authnd.mysql-max-open-conns`, `app.authnd.mysql-max-idle-conns`, `app.authzd.db-resolver-max-open-conns`, and `app.authzd.db-resolver-max-idle-conns`. The default values remain unchanged (authnd: 100 max open and 100 max idle connections; authzd: 100 max open and 15 max idle connections). These settings should only be adjusted with guidance from GitHub Support. + Administrators can configure database connection pool limits for the authentication and authorization services to improve performance on instances experiencing high concurrent request volumes. The limits can be adjusted using `ghe-config` keys: `app.authnd.mysql-max-open-conns`, `app.authnd.mysql-max-idle-conns`, `app.authzd.db-resolver-max-open-conns`, and `app.authzd.db-resolver-max-idle-conns`. The default values remain unchanged (authnd: 100 max open and 100 max idle connections; authzd: 100 max open and 15 max idle connections). These settings should only be adjusted with guidance from GitHub Support. - | - The `spokesctl status` command displays the current priority of repository issues based on the most recent check. Previously, the command displayed the highest priority the issue had reached since it was first detected, which could be misleading if the issue had been partially resolved. + The `spokesctl status` command displays the current priority of repository issues based on the most recent check. Previously, the command displayed the highest priority the issue had reached since it was first detected, which could be misleading if the issue had been partially resolved. known_issues: - | During an upgrade of GitHub Enterprise Server, custom firewall rules are removed. If you use custom firewall rules, you must reapply them after upgrading. diff --git a/data/release-notes/enterprise-server/3-19/2.yml b/data/release-notes/enterprise-server/3-19/2.yml index 3daef123466d..7a122e23f237 100644 --- a/data/release-notes/enterprise-server/3-19/2.yml +++ b/data/release-notes/enterprise-server/3-19/2.yml @@ -9,50 +9,50 @@ sections: - Queue management: Configure retry timing and queue processing (`smtp.maximal-backoff-time`, `smtp.queue-run-delay`) - Connection limits: Set maximum inbound SMTP connections (`smtp.client-connection-count-limit`). - | - For administrators using geo-replication or high availability (HA), `ghe-repl` tooling supports cross-cluster replication (CCR) for Elasticsearch, improving search index replication between instances. + For administrators using geo-replication or high availability (HA), `ghe-repl` tooling supports cross-cluster replication (CCR) for Elasticsearch, improving search index replication between instances. security_fixes: - | - **MEDIUM:** By supplying the migration identifier, an attacker could upload unauthorized content to another user’s repository migration export due to a missing authorization check. This could cause victims to download attacker-controlled migration archives, potentially impacting the integrity of downstream repository imports. GitHub has requested a CVE ID [CVE-2026-1355](https://www.cve.org/cverecord?id=CVE-2026-1355) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + **MEDIUM:** By supplying the migration identifier, an attacker could upload unauthorized content to another user’s repository migration export due to a missing authorization check. This could cause victims to download attacker-controlled migration archives, potentially impacting the integrity of downstream repository imports. GitHub has requested a CVE ID [CVE-2026-1355](https://www.cve.org/cverecord?id=CVE-2026-1355) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). - | - **LOW:** GitHub Enterprise Server included React versions 19.0, 19.1, and 19.2 in its package, which contain vulnerabilities in the React Server Components protocol ([CVE-2025-55182](https://www.cve.org/cverecord?id=CVE-2025-55182), [CVE-2025-66478](https://www.cve.org/cverecord?id=CVE-2025-66478). GitHub Enterprise Server does not use React Server Components and was not vulnerable to exploitation. React has been updated to version 19.2.1 to address findings from security scanning tools. + **LOW:** GitHub Enterprise Server included React versions 19.0, 19.1, and 19.2 in its package, which contain vulnerabilities in the React Server Components protocol ([CVE-2025-55182](https://www.cve.org/cverecord?id=CVE-2025-55182), [CVE-2025-66478](https://www.cve.org/cverecord?id=CVE-2025-66478). GitHub Enterprise Server does not use React Server Components and was not vulnerable to exploitation. React has been updated to version 19.2.1 to address findings from security scanning tools. - | - **HIGH:** An attacker could merge their own pull request into a repository that allowed forks and for which they didn't have write access, by exploiting an incorrect authorization check in the `enable_auto_merge` mutation for pull requests in specific scenarios. Exploitation required a clean pull request status and only applied to branches without branch protection rules enabled. GitHub has requested CVE ID [CVE-2026-1999](https://www.cve.org/cverecord?id=CVE-2026-1999) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + **HIGH:** An attacker could merge their own pull request into a repository that allowed forks and for which they didn't have write access, by exploiting an incorrect authorization check in the `enable_auto_merge` mutation for pull requests in specific scenarios. Exploitation required a clean pull request status and only applied to branches without branch protection rules enabled. GitHub has requested CVE ID [CVE-2026-1999](https://www.cve.org/cverecord?id=CVE-2026-1999) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). - | - **HIGH:** An authenticated attacker could exploit a URL redirection vulnerability in GitHub Enterprise Server to leak privileged authorization tokens by redirecting requests to an attacker-controlled domain. This could allow exfiltration of the `Actions.ManageOrgs` JWT and potential remote code execution. This vulnerability was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + **HIGH:** An authenticated attacker could exploit a URL redirection vulnerability in GitHub Enterprise Server to leak privileged authorization tokens by redirecting requests to an attacker-controlled domain. This could allow exfiltration of the `Actions.ManageOrgs` JWT and potential remote code execution. This vulnerability was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). bugs: - | - The Elasticsearch panel in the Operational Health dashboard of the Management Console did not correctly represent the clusters health. As a result, administrators may have seen inaccurate status indicators for Elasticsearch availability and performance. + The Elasticsearch panel in the Operational Health dashboard of the Management Console did not correctly represent the cluster's health. As a result, administrators may have seen inaccurate status indicators for Elasticsearch availability and performance. - | - Alambic failed to start after reboot or upgrade if legacy multi-disk for alambic was set up. + Alambic failed to start after reboot or upgrade if legacy multi-disk for alambic was set up. - | - GitHub Enterprise Server Backup Service (preview) was disabled after upgrading. + GitHub Enterprise Server Backup Service (preview) was disabled after upgrading. - | - Running `ghe-config-apply` could fail if Redis experienced transient connectivity issues during the configuration process. + Running `ghe-config-apply` could fail if Redis experienced transient connectivity issues during the configuration process. - | - Resolved an issue in Enterprise Manage where the Backups (Preview) tab failed to open and returned an Internal Server Error. This tab now load as expected. + Resolved an issue in Enterprise Manage where the Backups (Preview) tab failed to open and returned an Internal Server Error. This tab now load as expected. - | - On instances initially configured more than five years ago, administrators were unable to access the Management Console after upgrading due to an outdated session secret that was below the required 64-byte length. + On instances initially configured more than five years ago, administrators were unable to access the Management Console after upgrading due to an outdated session secret that was below the required 64-byte length. - | - Administrators were unable to access the "Updates" tab in the Management Console due to a template rendering error that displayed an Internal Server Error. + Administrators were unable to access the "Updates" tab in the Management Console due to a template rendering error that displayed an Internal Server Error. - | - Administrators could not use the "Clear dependencies" tool in the site admin dashboard because the required RESET_MANIFESTS_CONSUMER_GROUP environment variable was missing. + Administrators could not use the "Clear dependencies" tool in the site admin dashboard because the required RESET_MANIFESTS_CONSUMER_GROUP environment variable was missing. - | - When administrators configured password authentication, the Prometheus endpoint for OpenTelemetry metrics failed to expose metrics due to health check failures. + When administrators configured password authentication, the Prometheus endpoint for OpenTelemetry metrics failed to expose metrics due to health check failures. - | - When administrators would apply configuration changes via the management console, the state shown would occasionally briefly flicker to a failure before being marked as successful causing confusion as to whether the configuration had succeeded. + When administrators would apply configuration changes via the management console, the state shown would occasionally briefly flicker to a failure before being marked as successful causing confusion as to whether the configuration had succeeded. - | - On an instance configured behind a load balancer, users received unexpected secondary rate limit warnings during authentication when the `X-Forwarded-For` header included port numbers. This occurred because the system incorrectly ignored the header values containing ports, preventing proper client IP address identification. + On an instance configured behind a load balancer, users received unexpected secondary rate limit warnings during authentication when the `X-Forwarded-For` header included port numbers. This occurred because the system incorrectly ignored the header values containing ports, preventing proper client IP address identification. - | - Users with read access to a repository were unable to close issues even when granted the "Close issue" fine-grained permission through custom repository roles. Permission checks were relying solely on the triager role when evaluating a users ability to close issues. + Users with read access to a repository were unable to close issues even when granted the "Close issue" fine-grained permission through custom repository roles. Permission checks were relying solely on the triager role when evaluating a users ability to close issues. - | - Push rejections due to custom pre-receive hooks were not visible in the audit log. + Push rejections due to custom pre-receive hooks were not visible in the audit log. - | - Users could only view webhook deliveries from the previous three days. + Users could only view webhook deliveries from the previous three days. changes: - | - Administrators can configure database connection pool limits for the authentication and authorization services to improve performance on instances experiencing high concurrent request volumes. The limits can be adjusted using `ghe-config` keys: `app.authnd.mysql-max-open-conns`, `app.authnd.mysql-max-idle-conns`, `app.authzd.db-resolver-max-open-conns`, and `app.authzd.db-resolver-max-idle-conns`. The default values remain unchanged (authnd: 100 max open and 100 max idle connections; authzd: 100 max open and 15 max idle connections). These settings should only be adjusted with guidance from GitHub Support. + Administrators can configure database connection pool limits for the authentication and authorization services to improve performance on instances experiencing high concurrent request volumes. The limits can be adjusted using `ghe-config` keys: `app.authnd.mysql-max-open-conns`, `app.authnd.mysql-max-idle-conns`, `app.authzd.db-resolver-max-open-conns`, and `app.authzd.db-resolver-max-idle-conns`. The default values remain unchanged (authnd: 100 max open and 100 max idle connections; authzd: 100 max open and 15 max idle connections). These settings should only be adjusted with guidance from GitHub Support. - | - The `spokesctl status` command displays the current priority of repository issues based on the most recent check. Previously, the command displayed the highest priority the issue had reached since it was first detected, which could be misleading if the issue had been partially resolved. + The `spokesctl status` command displays the current priority of repository issues based on the most recent check. Previously, the command displayed the highest priority the issue had reached since it was first detected, which could be misleading if the issue had been partially resolved. known_issues: - | During an upgrade of GitHub Enterprise Server, custom firewall rules are removed. If you use custom firewall rules, you must reapply them after upgrading. diff --git a/data/release-notes/enterprise-server/3-19/9.yml b/data/release-notes/enterprise-server/3-19/9.yml new file mode 100644 index 000000000000..69f5ea94a256 --- /dev/null +++ b/data/release-notes/enterprise-server/3-19/9.yml @@ -0,0 +1,107 @@ +date: '2026-07-16' +intro: | + > [!NOTE] As part of a security enhancement to {% data variables.product.prodname_ghe_server %} support bundle uploads, {% data variables.product.company_short %} will begin rejecting uploads from older unpatched appliances on August 18, 2026. Please update to this patch release to avoid interruptions when submitting support bundles with `ghe-support-bundle`, `ghe-cluster-support-bundle`, or `ghe-support-upload`. The minimum required patch versions to submit support bundles are 3.21.3, 3.20.5, 3.19.9, 3.18.12, and 3.17.18. If you cannot update to the required patch version before August 18, 2026, and need to upload a support bundle, contact [GitHub Support](https://support.github.com/enterprise-and-teams#enterprise-administrators-server) for guidance. +sections: + features: + - | + Site administrators can configure a customer-managed cloud object store (Amazon S3, Azure Blob Storage, or Google Cloud Storage) as an Elasticsearch snapshot repository. This enables incremental Elasticsearch snapshots for backup, restore, and disaster recovery. Management scripts are available for manual snapshot operations and testing. + security_fixes: + - | + **HIGH**: An attacker who had code execution inside the Dependabot updater container could write attacker-controlled files to arbitrary paths in a repository that Dependabot updates, including GitHub Actions workflow files. This was possible because dependency-file path validation checked only the declared file name and not the effective path derived from the file's directory and symlink target. If the repository used a pull_request_target workflow or had auto-merge enabled, the injected workflow could execute with access to the repository's GitHub Actions secrets. GitHub has requested CVE ID [CVE-2026-15343](https://www.cve.org/cverecord?id=CVE-2026-15343) for this vulnerability. + - | + **MEDIUM**: An attacker could render a GitHub Enterprise Server instance unresponsive, causing a denial of service, by adding a repository release notes configuration file containing deeply nested YAML and then generating release notes. GitHub has requested CVE ID [CVE-2026-15007](https://www.cve.org/cverecord?id=CVE-2026-15007) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + - | + **MEDIUM**: An attacker with write access to any repository on a GitHub Enterprise Server instance could read metadata from private repositories they could not access, including repository owners and names, branch names, commit SHAs, commit messages, and the pushing actor because the delegated bypass endpoint resolved a rule suite from an attacker-supplied identifier without checking that the user could read its repository, and these sequential identifiers could be enumerated. GitHub has requested CVE ID [CVE-2026-15783](https://www.cve.org/cverecord?id=CVE-2026-15783) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + - | + Packages have been updated to the latest security versions. + bugs: + - | + Users experienced `ghe-maintenance -q` reporting that maintenance mode was not set when only `maintenance-git.html` remained after a replication restart. GHES now removes the dangling git maintenance lock during `ghe-repl-start` and reports maintenance mode correctly. + - | + During upgrades of high-availability instances, stateless nodes were incorrectly assigned as the primary node. + - | + On an instance where an administrator configured `logrotate.maxsize` via `ghe-config` with a non-gigabyte unit suffix (for example, `256M` or `512k`), the resulting logrotate configuration was invalid, which silently stopped log rotation and could allow logs to fill the disk. + - | + `ghe-config-apply` showed a validation warning when more than one `github-stream-processors` container ran, even when multiple allocations are expected to be scheduled. + - | + After an upgrade, `ghe-config-apply` could fail with `rake aborted! VERSIONS must be a comma-separated list of integers` when completing post-upgrade live migrations due to corrupted command output in the transitions value. + - | + On the Management Consoles monitor dashboard, the Memory and Disk usage panels on the Operational Health dashboard displayed values on the vertical axis as raw bytes (for example, `500000000000`) instead of human-readable units. + - | + On an instance with clustering or high availability configured, setting up MySQL replication on a replica node sometimes failed during a configuration apply. The failure occurred intermittently when MySQL restarted before the setup process could complete. + - | + On an instance with GitHub Actions enabled, repositories that required actions to be pinned to a full-length commit SHA incorrectly blocked workflows that referenced local actions within the same repository (for example, `./.github/actions/my-action`). Local actions are now excluded from the SHA-pinning policy check, since they cannot be pinned to a SHA. + - | + On an instance with a large number of organizations, {% data variables.product.pat_generic %} (PAT) conditional access policy evaluation triggered a full organization enumeration, significantly increasing MySQL load and degrading performance. + - | + When multiple users updated labels on the same issue or pull request at the same time, labels added by one user could be lost. + - | + Organization owners, security managers, and enterprise administrators in some configurations experienced validation errors when they tried to modify code security configurations after upgrading GitHub Enterprise Server if the instance had uninstalled security products. + - | + Suspended users were listed in an organization team's list of members. + - | + On instances that served GraphQL API requests over an extended period without restarting, memory usage on the appliance grew continuously without an upper bound. This could lead to degraded performance or resource exhaustion on long-running instances. Deferred GraphQL query state is now properly released after each request completes. + changes: + - | + Organization owners can configure source and target access tokens for Enterprise Live Migrations in their organization settings. Previously, these tokens needed to be configured in the terminal over SSH. + - | + The default `maxconn` (maximum connections) value for HAProxy has increased from 1,024 to 8,192 across all proxies. Previously, large customers reported surpassing the limit on high-traffic services. + - | + Site administrators can configure the maximum size of archives exported by `ghe-migrator` by setting the `GHECM_EXPORT_ARCHIVE_MAX_SIZE_GB` environment variable. Previously, exports were subject to an 80 GB limit, which could prevent large GHES-to-GHES migrations from completing. Setting the variable to `0` removes the limit entirely. + - | + Administrators who lose access to both SSH and the Management Console can recover their instance by selecting recovery mode from the GRUB boot menu, which is now displayed during boot for 10 seconds. + - | + To guard against rare image corruption caused by an unexpected restart or interruption during an upgrade, the integrity of Docker images is now verified after an upgrade completes. If a corrupted image is detected, a warning is logged so an administrator can recover it. + - | + On instances with multiple nodes, to avoid network overload, the limit of rsync network repairs per host has been lowered from 80 to 10. + + You may notice this limit when adding a new replica node if many repository networks or gists need to be copied. Administrators can increase the limit to speed up replication, at the risk of saturating network connection. + + To configure the limit, update `max-rsync-repairs-per-target-host` in `/data/user/common/github.conf`, then run `ghe-config-apply`. + - | + To reduce failed repairs of large repositories or networks, such as monorepos, the timeout for repository and network repair operations has been increased. + known_issues: + - | + During an upgrade of GitHub Enterprise Server, custom firewall rules are removed. If you use custom firewall rules, you must reapply them after upgrading. + - | + During the validation phase of a configuration run, a `No such object` error may occur for the Notebook and Viewscreen services. This error can be ignored as the services should still correctly start. + - | + If the root site administrator is locked out of the Management Console after failed login attempts, the account does not unlock automatically after the defined lockout time. Someone with administrative SSH access to the instance must unlock the account using the administrative shell. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-web-ui/troubleshooting-access-to-the-management-console#unlocking-the-root-site-administrator-account). + - | + {% data reusables.release-notes.large-adoc-files-issue %} + - | + Admin stats REST API endpoints may timeout on appliances with many users or repositories. Retrying the request until data is returned is advised. + - | + When following the steps for [Replacing the primary MySQL node](/admin/monitoring-managing-and-updating-your-instance/configuring-clustering/replacing-a-cluster-node#replacing-the-primary-mysql-node), step 14 (running `ghe-cluster-config-apply`) might fail with errors. If this occurs, re-running `ghe-cluster-config-apply` is expected to succeed. + - | + Running a config apply as part of the steps for [Replacing a node in an emergency](/admin/monitoring-managing-and-updating-your-instance/configuring-clustering/replacing-a-cluster-node#replacing-a-node-in-an-emergency) may fail with errors if the node being replaced is still reachable. If this occurs, shutdown the node and repeat the steps. + - | + {% data reusables.release-notes.2024-06-possible-frontend-5-minute-outage-during-hotpatch-upgrade %} + - | + When restoring data originally backed up from a 3.13 or greater appliance version, the Elasticsearch indices need to be reindexed before some of the data will show up. This happens via a nightly scheduled job. It can also be forced by running `/usr/local/share/enterprise/ghe-es-search-repair`. + - | + When enabling automatic update checks for the first time in the Management Console, the status is not dynamically reflected until the "Updates" page is reloaded. + - | + When restoring from a backup snapshot, a large number of `mapper_parsing_exception` errors may be displayed. + - | + When initializing a new GHES cluster, nodes with the `consul-server` role should be added to the cluster before adding additional nodes. Adding all nodes simultaneously creates a race condition between nomad server registration and nomad client registration. + - | + In a cluster, the host running restore requires access the storage nodes via their private IPs. + - | + On an instance hosted on Azure, commenting on an issue via email meant the comment was not added to the issue. + - | + After a restore, existing outside collaborators cannot be added to repositories in a new organization. This issue can be resolved by running `/usr/local/share/enterprise/ghe-es-search-repair` on the appliance. + - | + After a geo-replica is promoted to be a primary by running `ghe-repl-promote`, the actions workflow of a repository does not have any suggested workflows. + - | + When publishing npm packages in a workflow after restoring from a backup to GitHub Enterprise Server 3.13.5.gm4 or 3.14.2.gm3, you may encounter a `401 Unauthorized` error from the GitHub Packages service. This can happen if the restore is from an N-1 or N-2 version and the workflow targets the npm endpoint on the backup instance. To avoid this issue, ensure the access token is valid and includes the correct scopes for publishing to GitHub Packages. + - | + The setting to define private registries at the organization level for code scanning is only available if dependabot is also enabled for the instance. + - | + Upgrading or hotpatching to 3.19.1 may fail on nodes that have been continuously upgraded from versions older than 2021 (i.e. 2.17). If this issue occurs, you will see log entries prefixed with `invalid secret` in ghe-config.log. If you are running nodes from these older versions, it is recommended not to upgrade to 3.19.1. + - | + An issue in the Management Console means the Backups (Preview) and Updates tabs may fail to open and instead return an Internal Server Error. We recommend using the command line interface (CLI) for backups and updates. + - | + When applying an enterprise security configuration to all repositories (for example, enabling Secret Scanning or Code Scanning across all repositories), the system immediately enqueues enablement jobs for every organization in the enterprise simultaneously. For enterprises with a large number of repositories, this can result in significant system load and potential performance degradation. If you manage a large enterprise with many organizations and repositories, we recommend applying security configurations at the organization level rather than at the enterprise level in the UI. This allows you to enable security features incrementally and monitor system performance as you roll out changes. + - | + Administrators upgrading to certain patch releases encountered a "Failed to generate an OIDC token" error during the `Update Servicing Resources` step when GitHub Actions was configured with Google Cloud Storage (GCS) or AWS S3 using OpenID Connect (OIDC) authentication. The upgrade was blocked and could not complete. To work around this issue, administrators could apply a manual patch by running `sudo sed -i.bak 's|ghe-actions-console -s -c Update-Service|ghe-actions-console -s --no-blob-creds -c Update-Service|g' /usr/local/bin/ghe-actions-update` followed by `ghe-config-apply`. diff --git a/data/release-notes/enterprise-server/3-20/5.yml b/data/release-notes/enterprise-server/3-20/5.yml new file mode 100644 index 000000000000..08a539de8675 --- /dev/null +++ b/data/release-notes/enterprise-server/3-20/5.yml @@ -0,0 +1,103 @@ +date: '2026-07-16' +intro: | + > [!NOTE] As part of a security enhancement to {% data variables.product.prodname_ghe_server %} support bundle uploads, {% data variables.product.company_short %} will begin rejecting uploads from older unpatched appliances on August 18, 2026. Please update to this patch release to avoid interruptions when submitting support bundles with `ghe-support-bundle`, `ghe-cluster-support-bundle`, or `ghe-support-upload`. The minimum required patch versions to submit support bundles are 3.21.3, 3.20.5, 3.19.9, 3.18.12, and 3.17.18. If you cannot update to the required patch version before August 18, 2026, and need to upload a support bundle, contact [GitHub Support](https://support.github.com/enterprise-and-teams#enterprise-administrators-server) for guidance. +sections: + features: + - | + Site administrators can configure a customer-managed cloud object store (Amazon S3, Azure Blob Storage, or Google Cloud Storage) as an Elasticsearch snapshot repository. This enables incremental Elasticsearch snapshots for backup, restore, and disaster recovery. Management scripts are available for manual snapshot operations and testing. + security_fixes: + - | + **HIGH**: An attacker who had code execution inside the Dependabot updater container could write attacker-controlled files to arbitrary paths in a repository that Dependabot updates, including GitHub Actions workflow files. This was possible because dependency-file path validation checked only the declared file name and not the effective path derived from the file's directory and symlink target. If the repository used a pull_request_target workflow or had auto-merge enabled, the injected workflow could execute with access to the repository's GitHub Actions secrets. GitHub has requested CVE ID [CVE-2026-15343](https://www.cve.org/cverecord?id=CVE-2026-15343) for this vulnerability. + - | + **MEDIUM**: An attacker could render a GitHub Enterprise Server instance unresponsive, causing a denial of service, by adding a repository release notes configuration file containing deeply nested YAML and then generating release notes. GitHub has requested CVE ID [CVE-2026-15007](https://www.cve.org/cverecord?id=CVE-2026-15007) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + - | + **MEDIUM**: An attacker with write access to any repository on a GitHub Enterprise Server instance could read metadata from private repositories they could not access, including repository owners and names, branch names, commit SHAs, commit messages, and the pushing actor because the delegated bypass endpoint resolved a rule suite from an attacker-supplied identifier without checking that the user could read its repository, and these sequential identifiers could be enumerated. GitHub has requested CVE ID [CVE-2026-15783](https://www.cve.org/cverecord?id=CVE-2026-15783) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + - | + Packages have been updated to the latest security versions. + bugs: + - | + During upgrades of high-availability instances, stateless nodes were incorrectly assigned as the primary node. + - | + Users experienced `ghe-maintenance -q` reporting that maintenance mode was not set when only `maintenance-git.html` remained after a replication restart. GHES now removes the dangling git maintenance lock during `ghe-repl-start` and reports maintenance mode correctly. + - | + On an instance where an administrator configured `logrotate.maxsize` via `ghe-config` with a non-gigabyte unit suffix (for example, `256M` or `512k`), the resulting logrotate configuration was invalid, which silently stopped log rotation and could allow logs to fill the disk. + - | + `ghe-config-apply` showed a validation warning when more than one `github-stream-processors` container ran, even when multiple allocations are expected to be scheduled. + - | + After an upgrade, `ghe-config-apply` could fail with `rake aborted! VERSIONS must be a comma-separated list of integers` when completing post-upgrade live migrations due to corrupted command output in the transitions value. + - | + On the Management Consoles monitor dashboard, the Memory and Disk usage panels on the Operational Health dashboard displayed values on the vertical axis as raw bytes (for example, `500000000000`) instead of human-readable units. + - | + On an instance with high availability configured, running `ghe-repl-teardown` or `ghe-repl-decommission` failed to remove the replica node. + - | + On an instance with clustering or high availability configured, setting up MySQL replication on a replica node sometimes failed during a configuration apply. The failure occurred intermittently when MySQL restarted before the setup process could complete. + - | + The Elasticsearch panel in the Operational Health dashboard of the Management Console did not correctly represent the cluster's health. As a result, administrators may have seen inaccurate status indicators for Elasticsearch availability and performance. + - | + On an instance with GitHub Actions enabled, repositories that required actions to be pinned to a full-length commit SHA incorrectly blocked workflows that referenced local actions within the same repository (for example, `./.github/actions/my-action`). Local actions are now excluded from the SHA-pinning policy check, since they cannot be pinned to a SHA. + - | + On an instance with a large number of organizations, {% data variables.product.pat_generic %} (PAT) conditional access policy evaluation triggered a full organization enumeration, significantly increasing MySQL load and degrading performance. + - | + When multiple users updated labels on the same issue or pull request at the same time, labels added by one user could be lost. + - | + Organization owners, security managers, and enterprise administrators in some configurations experienced validation errors when they tried to modify code security configurations after upgrading GitHub Enterprise Server if the instance had uninstalled security products. + - | + Suspended users were listed in an organization team's list of members. + - | + On instances that served GraphQL API requests over an extended period without restarting, memory usage on the appliance grew continuously without an upper bound. This could lead to degraded performance or resource exhaustion on long-running instances. Deferred GraphQL query state is now properly released after each request completes. + - | + Organization administrators experienced unintended member removals from manually managed teams when unlinking a SCIM external group from a team. This occurred specifically when the manually managed teams lacked organization membership records, commonly in teams created before SCIM was enabled. + changes: + - | + Organization owners can configure source and target access tokens for Enterprise Live Migrations in their organization settings. Previously, these tokens needed to be configured in the terminal over SSH. + - | + The default `maxconn` (maximum connections) value for HAProxy has increased from 1,024 to 8,192 across all proxies. Previously, large customers reported surpassing the limit on high-traffic services. + - | + Site administrators can configure the maximum size of archives exported by `ghe-migrator` by setting the `GHECM_EXPORT_ARCHIVE_MAX_SIZE_GB` environment variable. Previously, exports were subject to an 80 GB limit, which could prevent large GHES-to-GHES migrations from completing. Setting the variable to `0` removes the limit entirely. + - | + Administrators who lose access to both SSH and the Management Console can recover their instance by selecting recovery mode from the GRUB boot menu, which is now displayed during boot for 10 seconds. + - | + To guard against rare image corruption caused by an unexpected restart or interruption during an upgrade, the integrity of Docker images is now verified after an upgrade completes. If a corrupted image is detected, a warning is logged so an administrator can recover it. + - | + On instances with multiple nodes, to avoid network overload, the limit of rsync network repairs per host has been lowered from 80 to 10. + + You may notice this limit when adding a new replica node if many repository networks or gists need to be copied. Administrators can increase the limit to speed up replication, at the risk of saturating network connection. + + To configure the limit, update `max-rsync-repairs-per-target-host` in `/data/user/common/github.conf`, then run `ghe-config-apply`. + - | + To reduce failed repairs of large repositories or networks, such as monorepos, the timeout for repository and network repair operations has been increased. + known_issues: + - | + During an upgrade of GitHub Enterprise Server, custom firewall rules are removed. If you use custom firewall rules, you must reapply them after upgrading. + - | + During the validation phase of a configuration run, a `No such object` error may occur for the Notebook and Viewscreen services. This error can be ignored as the services should still correctly start. + - | + If the root site administrator is locked out of the Management Console after failed login attempts, the account does not unlock automatically after the defined lockout time. Someone with administrative SSH access to the instance must unlock the account using the administrative shell. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-web-ui/troubleshooting-access-to-the-management-console#unlocking-the-root-site-administrator-account). + - | + {% data reusables.release-notes.large-adoc-files-issue %} + - | + Admin stats REST API endpoints may timeout on appliances with many users or repositories. Retrying the request until data is returned is advised. + - | + When following the steps for [Replacing the primary MySQL node](/admin/monitoring-managing-and-updating-your-instance/configuring-clustering/replacing-a-cluster-node#replacing-the-primary-mysql-node), step 14 (running `ghe-cluster-config-apply`) might fail with errors. If this occurs, re-running `ghe-cluster-config-apply` is expected to succeed. + - | + Running a config apply as part of the steps for [Replacing a node in an emergency](/admin/monitoring-managing-and-updating-your-instance/configuring-clustering/replacing-a-cluster-node#replacing-a-node-in-an-emergency) may fail with errors if the node being replaced is still reachable. If this occurs, shutdown the node and repeat the steps. + - | + When restoring data originally backed up from a 3.13 or greater appliance version, the Elasticsearch indices need to be reindexed before some of the data will show up. This happens via a nightly scheduled job. It can also be forced by running `/usr/local/share/enterprise/ghe-es-search-repair`. + - | + When initializing a new GHES cluster, nodes with the `consul-server` role should be added to the cluster before adding additional nodes. Adding all nodes simultaneously creates a race condition between nomad server registration and nomad client registration. + - | + In a cluster, the host running restore requires access the storage nodes via their private IPs. + - | + On an instance hosted on Azure, commenting on an issue via email meant the comment was not added to the issue. + - | + After a restore, existing outside collaborators cannot be added to repositories in a new organization. This issue can be resolved by running `/usr/local/share/enterprise/ghe-es-search-repair` on the appliance. + - | + After a geo-replica is promoted to be a primary by running `ghe-repl-promote`, the actions workflow of a repository does not have any suggested workflows. + - | + When publishing npm packages in a workflow after restoring from a backup to GitHub Enterprise Server 3.13.5.gm4 or 3.14.2.gm3, you may encounter a `401 Unauthorized` error from the GitHub Packages service. This can happen if the restore is from an N-1 or N-2 version and the workflow targets the npm endpoint on the backup instance. To avoid this issue, ensure the access token is valid and includes the correct scopes for publishing to GitHub Packages. + - | + When applying an enterprise security configuration to all repositories (for example, enabling Secret Scanning or Code Scanning across all repositories), the system immediately enqueues enablement jobs for every organization in the enterprise simultaneously. For enterprises with a large number of repositories, this can result in significant system load and potential performance degradation. If you manage a large enterprise with many organizations and repositories, we recommend applying security configurations at the organization level rather than at the enterprise level in the UI. This allows you to enable security features incrementally and monitor system performance as you roll out changes. + - | + On instances with multiple Git storage nodes in a voting configuration, including cluster and geo-replication high availability topologies, upgrading may fail to correctly install Actions that ship with the new version. In some cases, previous versions of these Actions remain on the instance. To resolve this issue, run the following commands on the primary node: `ghe-config --unset 'app.actions.actions-repos-sha1sum'`, `ghe-config-apply`, and `/usr/local/share/enterprise/ghe-run-init-actions-graph`. + - | + Administrators upgrading to certain patch releases encountered a "Failed to generate an OIDC token" error during the `Update Servicing Resources` step when GitHub Actions was configured with Google Cloud Storage (GCS) or AWS S3 using OpenID Connect (OIDC) authentication. The upgrade was blocked and could not complete. To work around this issue, administrators could apply a manual patch by running `sudo sed -i.bak 's|ghe-actions-console -s -c Update-Service|ghe-actions-console -s --no-blob-creds -c Update-Service|g' /usr/local/bin/ghe-actions-update` followed by `ghe-config-apply`. diff --git a/data/release-notes/enterprise-server/3-21/2.yml b/data/release-notes/enterprise-server/3-21/2.yml index 3a5d22a28916..ae78e002fd98 100644 --- a/data/release-notes/enterprise-server/3-21/2.yml +++ b/data/release-notes/enterprise-server/3-21/2.yml @@ -69,8 +69,6 @@ sections: When restoring data originally backed up from a 3.13 or greater appliance version, the Elasticsearch indices need to be reindexed before some of the data will show up. This happens via a nightly scheduled job. It can also be forced by running `/usr/local/share/enterprise/ghe-es-search-repair`. - | When initializing a new GHES cluster, nodes with the `consul-server` role should be added to the cluster before adding additional nodes. Adding all nodes simultaneously creates a race condition between nomad server registration and nomad client registration. - - | - When initializing a new GHES cluster, nodes with the `consul-server` role should be added to the cluster before adding additional nodes. Adding all nodes simultaneously creates a race condition between nomad server registration and nomad client registration. - | In a cluster, the host running restore requires access the storage nodes via their private IPs. - | diff --git a/data/release-notes/enterprise-server/3-21/3.yml b/data/release-notes/enterprise-server/3-21/3.yml new file mode 100644 index 000000000000..5ee844463026 --- /dev/null +++ b/data/release-notes/enterprise-server/3-21/3.yml @@ -0,0 +1,96 @@ +date: '2026-07-16' +intro: | + > [!NOTE] As part of a security enhancement to {% data variables.product.prodname_ghe_server %} support bundle uploads, {% data variables.product.company_short %} will begin rejecting uploads from older unpatched appliances on August 18, 2026. Please update to this patch release to avoid interruptions when submitting support bundles with `ghe-support-bundle`, `ghe-cluster-support-bundle`, or `ghe-support-upload`. The minimum required patch versions to submit support bundles are 3.21.3, 3.20.5, 3.19.9, 3.18.12, and 3.17.18. If you cannot update to the required patch version before August 18, 2026, and need to upload a support bundle, contact [GitHub Support](https://support.github.com/enterprise-and-teams#enterprise-administrators-server) for guidance. +sections: + security_fixes: + - | + **HIGH**: An attacker who had code execution inside the Dependabot updater container could write attacker-controlled files to arbitrary paths in a repository that Dependabot updates, including GitHub Actions workflow files. This was possible because dependency-file path validation checked only the declared file name and not the effective path derived from the file's directory and symlink target. If the repository used a pull_request_target workflow or had auto-merge enabled, the injected workflow could execute with access to the repository's GitHub Actions secrets. GitHub has requested CVE ID [CVE-2026-15343](https://www.cve.org/cverecord?id=CVE-2026-15343) for this vulnerability. + - | + **MEDIUM**: An attacker could render a GitHub Enterprise Server instance unresponsive, causing a denial of service, by adding a repository release notes configuration file containing deeply nested YAML and then generating release notes. GitHub has requested CVE ID [CVE-2026-15007](https://www.cve.org/cverecord?id=CVE-2026-15007) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + - | + **MEDIUM**: An attacker with write access to any repository on a GitHub Enterprise Server instance could read metadata from private repositories they could not access, including repository owners and names, branch names, commit SHAs, commit messages, and the pushing actor because the delegated bypass endpoint resolved a rule suite from an attacker-supplied identifier without checking that the user could read its repository, and these sequential identifiers could be enumerated. GitHub has requested CVE ID [CVE-2026-15783](https://www.cve.org/cverecord?id=CVE-2026-15783) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com/). + - | + Packages have been updated to the latest security versions. + bugs: + - | + Users experienced `ghe-maintenance -q` reporting that maintenance mode was not set when only `maintenance-git.html` remained after a replication restart. GHES now removes the dangling git maintenance lock during `ghe-repl-start` and reports maintenance mode correctly. + - | + `ghe-config-apply` showed a validation warning when more than one `github-stream-processors` container ran, even when multiple allocations are expected to be scheduled. + - | + On an instance where an administrator configured `logrotate.maxsize` via `ghe-config` with a non-gigabyte unit suffix (for example, `256M` or `512k`), the resulting logrotate configuration was invalid, which silently stopped log rotation and could allow logs to fill the disk. + - | + Site administrators upgrading a high-availability instance with stateless nodes experienced replica upgrade pre-check failures. + - | + Site administrators encountered a 503 error when accessing the monitoring dashboard after upgrading from GitHub Enterprise Server 3.19 to 3.21. This error occurred because Grafana 12 changed how it matches datasources, now using UIDs in addition to datasource IDs instead of just datasource IDs. + - | + The `ghe-add-node` script displayed a message indicating that the command was "experimental and not recommended for production use." This message was left behind after the high availability (HA) stateless feature reached general availability and is no longer accurate. + - | + After an upgrade, `ghe-config-apply` could fail with `rake aborted! VERSIONS must be a comma-separated list of integers` when completing post-upgrade live migrations due to corrupted command output in the transitions value. + - | + On an instance with high availability configured, running `ghe-repl-teardown` or `ghe-repl-decommission` failed to remove the replica node. + - | + On the Management Consoles monitor dashboard, the Memory and Disk usage panels on the Operational Health dashboard displayed values on the vertical axis as raw bytes (for example, `500000000000`) instead of human-readable units. + - | + On an instance with clustering or high availability configured, setting up MySQL replication on a replica node sometimes failed during a configuration apply. The failure occurred intermittently when MySQL restarted before the setup process could complete. + - | + On an instance with GitHub Actions enabled, repositories that required actions to be pinned to a full-length commit SHA incorrectly blocked workflows that referenced local actions within the same repository (for example, `./.github/actions/my-action`). Local actions are now excluded from the SHA-pinning policy check, since they cannot be pinned to a SHA. + - | + On an instance with a large number of organizations, {% data variables.product.pat_generic %} (PAT) conditional access policy evaluation triggered a full organization enumeration, significantly increasing MySQL load and degrading performance. + - | + Suspended users were listed in an organization team's list of members. + - | + Applying a security configuration to a large number of repositories at once could overwhelm background job processing and leave some repositories stuck in the `attaching` state. Security configuration applies are now throttled and staggered so they complete reliably across all selected repositories. + - | + Organization administrators experienced unintended member removals from manually managed teams when unlinking a SCIM external group from a team. This occurred specifically when the manually managed teams lacked organization membership records, commonly in teams created before SCIM was enabled. + - | + On instances that served GraphQL API requests over an extended period without restarting, memory usage on the appliance grew continuously without an upper bound. This could lead to degraded performance or resource exhaustion on long-running instances. Deferred GraphQL query state is now properly released after each request completes. + changes: + - | + Organization owners can configure source and target access tokens for Enterprise Live Migrations in their organization settings. Previously, these tokens needed to be configured in the terminal over SSH. + - | + Site administrators can configure the maximum size of archives exported by `ghe-migrator` by setting the `GHECM_EXPORT_ARCHIVE_MAX_SIZE_GB` environment variable. Previously, exports were subject to an 80 GB limit, which could prevent large GHES-to-GHES migrations from completing. Setting the variable to `0` removes the limit entirely. + - | + Administrators who lose access to both SSH and the Management Console can recover their instance by selecting recovery mode from the GRUB boot menu, which is now displayed during boot for 10 seconds. + - | + To guard against rare image corruption caused by an unexpected restart or interruption during an upgrade, the integrity of Docker images is now verified after an upgrade completes. If a corrupted image is detected, a warning is logged so an administrator can recover it. + - | + Site administrators who need to diagnose message queue backlogs can run the new `ghe-broker-lens` command-line utility. The read-only tool displays queue depth, message age, dropped messages, and per-request traces across the instances internal message brokers, without requiring direct Redis access or changing appliance state. + - | + To avoid overload, the limit of rsync network repairs per host has been lowered from 80 to 10. + + You may notice this limitation when adding a new replica node if many repository networks or gists need to be copied. Administrators can increase the limit to speed up replication, at the risk of saturating network connection. + + To configure the limit, update `max-rsync-repairs-per-target-host` in `/data/user/common/github.conf`, then run `ghe-config-apply`. + known_issues: + - | + During an upgrade of GitHub Enterprise Server, custom firewall rules are removed. If you use custom firewall rules, you must reapply them after upgrading. + - | + During the validation phase of a configuration run, a `No such object` error may occur for the Notebook and Viewscreen services. This error can be ignored as the services should still correctly start. + - | + If the root site administrator is locked out of the Management Console after failed login attempts, the account does not unlock automatically after the defined lockout time. Someone with administrative SSH access to the instance must unlock the account using the administrative shell. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-web-ui/troubleshooting-access-to-the-management-console#unlocking-the-root-site-administrator-account). + - | + {% data reusables.release-notes.large-adoc-files-issue %} + - | + Admin stats REST API endpoints may timeout on appliances with many users or repositories. Retrying the request until data is returned is advised. + - | + When following the steps for [Replacing the primary MySQL node](/admin/monitoring-managing-and-updating-your-instance/configuring-clustering/replacing-a-cluster-node#replacing-the-primary-mysql-node), step 14 (running `ghe-cluster-config-apply`) might fail with errors. If this occurs, re-running `ghe-cluster-config-apply` is expected to succeed. + - | + Running a config apply as part of the steps for [Replacing a node in an emergency](/admin/monitoring-managing-and-updating-your-instance/configuring-clustering/replacing-a-cluster-node#replacing-a-node-in-an-emergency) may fail with errors if the node being replaced is still reachable. If this occurs, shutdown the node and repeat the steps. + - | + When restoring data originally backed up from a 3.13 or greater appliance version, the Elasticsearch indices need to be reindexed before some of the data will show up. This happens via a nightly scheduled job. It can also be forced by running `/usr/local/share/enterprise/ghe-es-search-repair`. + - | + When initializing a new GHES cluster, nodes with the `consul-server` role should be added to the cluster before adding additional nodes. Adding all nodes simultaneously creates a race condition between nomad server registration and nomad client registration. + - | + In a cluster, the host running restore requires access the storage nodes via their private IPs. + - | + On an instance hosted on Azure, commenting on an issue via email meant the comment was not added to the issue. + - | + After a restore, existing outside collaborators cannot be added to repositories in a new organization. This issue can be resolved by running `/usr/local/share/enterprise/ghe-es-search-repair` on the appliance. + - | + After a geo-replica is promoted to be a primary by running `ghe-repl-promote`, the actions workflow of a repository does not have any suggested workflows. + - | + When publishing npm packages in a workflow after restoring from a backup to GitHub Enterprise Server 3.13.5.gm4 or 3.14.2.gm3, you may encounter a `401 Unauthorized` error from the GitHub Packages service. This can happen if the restore is from an N-1 or N-2 version and the workflow targets the npm endpoint on the backup instance. To avoid this issue, ensure the access token is valid and includes the correct scopes for publishing to GitHub Packages. + - | + When applying an enterprise security configuration to all repositories (for example, enabling Secret Scanning or Code Scanning across all repositories), the system immediately enqueues enablement jobs for every organization in the enterprise simultaneously. For enterprises with a large number of repositories, this can result in significant system load and potential performance degradation. If you manage a large enterprise with many organizations and repositories, we recommend applying security configurations at the organization level rather than at the enterprise level in the UI. This allows you to enable security features incrementally and monitor system performance as you roll out changes. + - | + On instances with multiple Git storage nodes in a voting configuration, including cluster and geo-replication high availability topologies, upgrading may fail to correctly install Actions that ship with the new version. In some cases, previous versions of these Actions remain on the instance. To resolve this issue, run the following commands on the primary node: `ghe-config --unset 'app.actions.actions-repos-sha1sum'`, `ghe-config-apply`, and `/usr/local/share/enterprise/ghe-run-init-actions-graph`. From 61a400f2bad0ca30a548ca2a5b8ce7e98eeab492 Mon Sep 17 00:00:00 2001 From: Kevin Heis Date: Thu, 16 Jul 2026 13:51:27 -0700 Subject: [PATCH 03/12] Revert enterprise-release-issue workflow to DOCS_BOT_PAT_BASE (#62294) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a672a7f9-31cb-4c55-b615-9caee7452b61 --- .github/workflows/enterprise-release-issue.yml | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/.github/workflows/enterprise-release-issue.yml b/.github/workflows/enterprise-release-issue.yml index 2595d2e35079..07f112a2dee6 100644 --- a/.github/workflows/enterprise-release-issue.yml +++ b/.github/workflows/enterprise-release-issue.yml @@ -20,26 +20,18 @@ jobs: steps: - name: Checkout repository code uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - - name: Generate GitHub App token - id: app-token - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 - with: - app-id: ${{ secrets.DOCS_BOT_APP_ID }} - private-key: ${{ secrets.DOCS_BOT_APP_PRIVATE_KEY }} - owner: github - repositories: docs-content,docs-engineering,enterprise-releases - uses: ./.github/actions/node-npm-setup - name: Create an enterprise release issue run: npm run create-enterprise-issue -- release env: - GITHUB_TOKEN: ${{ steps.app-token.outputs.token }} + GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }} - name: Create an enterprise deprecation issue run: npm run create-enterprise-issue -- deprecation env: - GITHUB_TOKEN: ${{ steps.app-token.outputs.token }} + GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }} - uses: ./.github/actions/slack-alert if: ${{ failure() && github.event_name != 'workflow_dispatch' }} @@ -49,4 +41,4 @@ jobs: - uses: ./.github/actions/create-workflow-failure-issue if: ${{ failure() && github.event_name != 'workflow_dispatch' }} with: - token: ${{ steps.app-token.outputs.token }} + token: ${{ secrets.DOCS_BOT_PAT_BASE }} From 2d3346a0bbc0eb9a670038e76b5fd93238ae4ae5 Mon Sep 17 00:00:00 2001 From: Kevin Heis Date: Thu, 16 Jul 2026 13:51:50 -0700 Subject: [PATCH 04/12] Fix Russian translated 'data reusables' Liquid tag prefixes (#62266) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 031a122f-ce90-4f05-8641-f98155428219 Copilot-Session: 5e383daf-e1a9-4d8c-95c7-a81a3cbb18b1 --- src/languages/lib/correct-translation-content.ts | 10 ++++++++++ src/languages/tests/correct-translation-content.ts | 13 +++++++++++++ 2 files changed, 23 insertions(+) diff --git a/src/languages/lib/correct-translation-content.ts b/src/languages/lib/correct-translation-content.ts index 53774987d7ea..6f0460e70c1a 100644 --- a/src/languages/lib/correct-translation-content.ts +++ b/src/languages/lib/correct-translation-content.ts @@ -934,6 +934,16 @@ export function correctTranslatedContentStrings( content = content.replaceAll('{% данные variables.', '{% data variables.') content = content.replaceAll('{% данных reusables', '{% data reusables') content = content.replaceAll('{% данные reusables', '{% data reusables') + // Fully translated "data reusables" phrases used as Liquid tag prefixes. + // `данных, многократно используемых` ("data, repeatedly used") and + // `данных, которые можно использовать повторно` ("data that can be reused") + // are both translations of `data reusables`; the English reusable path + // that follows is untranslated, so restoring the keyword is deterministic. + content = content.replaceAll('{% данных, многократно используемых.', '{% data reusables.') + content = content.replaceAll( + '{% данных, которые можно использовать повторно.', + '{% data reusables.', + ) content = content.replaceAll('{% данных переменных.', '{% data variables.') // Broaden `{% данных.X` → `{% data variables.X` (covers .product., .dependency-review., .code-scanning., etc.) content = content.replaceAll('{% данных.', '{% data variables.') diff --git a/src/languages/tests/correct-translation-content.ts b/src/languages/tests/correct-translation-content.ts index acd373748f98..1c78b797a1cc 100644 --- a/src/languages/tests/correct-translation-content.ts +++ b/src/languages/tests/correct-translation-content.ts @@ -687,6 +687,19 @@ describe('correctTranslatedContentStrings', () => { expect(fix('{% данные reusables.foo %}', 'ru')).toBe('{% data reusables.foo %}') }) + test('fixes fully translated "data reusables" tag prefixes', () => { + // "данных, многократно используемых" = "data, repeatedly used" + expect(fix('{% данных, многократно используемых.copilot.jetbrains-settings %}', 'ru')).toBe( + '{% data reusables.copilot.jetbrains-settings %}', + ) + // "данных, которые можно использовать повторно" = "data that can be reused" + expect( + fix('{% данных, которые можно использовать повторно.projects.what-gets-copied %}', 'ru'), + ).toBe('{% data reusables.projects.what-gets-copied %}') + // already-correct input is left unchanged + expect(fix('{% data reusables.copilot.foo %}', 'ru')).toBe('{% data reusables.copilot.foo %}') + }) + test('fixes broadened данных. pattern', () => { expect(fix('{% данных.product.github %}', 'ru')).toBe('{% data variables.product.github %}') }) From d8dd7373a4658ddcc99102435fe1ef855c3f377b Mon Sep 17 00:00:00 2001 From: Pallavi <96553709+pallsama@users.noreply.github.com> Date: Thu, 16 Jul 2026 15:17:55 -0700 Subject: [PATCH 05/12] Add hotpatch version requirement for support bundles (#62254) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 04bb96f3-f063-47b5-a87e-10e7fef24760 --- .../monitoring-your-instance/about-support-bundles.md | 10 ++++++++++ data/variables/contact.yml | 2 ++ 2 files changed, 12 insertions(+) diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-support-bundles.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-support-bundles.md index a593e217e1bc..2539be2b3a56 100644 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-support-bundles.md +++ b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-support-bundles.md @@ -13,6 +13,11 @@ category: A support bundle is a compressed archive of diagnostic data from your {% data variables.product.prodname_ghe_server %} instance. You can use support bundles to work with {% data variables.contact.github_support %} on issues and to generate Health Check reports that summarize your instance's configuration, health, and activity. + +> [!IMPORTANT] +> Beginning August 18, 2026, the `ghe-support-bundle`, `ghe-cluster-support-bundle`, and `ghe-support-upload` commands require you to be on 3.21.3, 3.20.5, 3.19.9, 3.18.12, or 3.17.18 (or later). Please update your {% data variables.product.prodname_ghe_server %} instance to the latest patch for your version line before August 18, 2026. If you cannot update to the required patch version before August 18, 2026, and need to upload a support bundle, contact {% data variables.contact.contact_ent_server_support %} for guidance. + + ## When to generate a support bundle Generate a support bundle in several scenarios: @@ -118,6 +123,11 @@ The Monitor page in the {% data variables.enterprise.management_console %} provi ## Generating and sharing support bundles + +> [!IMPORTANT] +> Beginning August 18, 2026, the `ghe-support-bundle`, `ghe-cluster-support-bundle`, and `ghe-support-upload` commands require you to be on 3.21.3, 3.20.5, 3.19.9, 3.18.12, or 3.17.18 (or later). Please update your {% data variables.product.prodname_ghe_server %} instance to the latest patch for your version line before August 18, 2026. If you cannot update to the required patch version before August 18, 2026, and need to upload a support bundle, contact {% data variables.contact.contact_ent_server_support %} for guidance. + + You can generate and share support bundles using the {% data variables.enterprise.management_console %} or the command line. For detailed instructions, see [AUTOTITLE](/support/contacting-github-support/providing-data-to-github-support#creating-and-sharing-support-bundles). ### Considerations for clustering diff --git a/data/variables/contact.yml b/data/variables/contact.yml index 39c32bb825ec..e1227ff49cb7 100644 --- a/data/variables/contact.yml +++ b/data/variables/contact.yml @@ -1,5 +1,7 @@ contact_ent_support: '[GitHub Enterprise Support](https://support.github.com)' +contact_ent_server_support: '[GitHub Enterprise Server Support](https://support.github.com/enterprise-and-teams#enterprise-administrators-server)' + # GitHub Support (with versioning for GHES) - when users need to open a ticket through the support portal contact_support: >- {% ifversion fpt or ghec %}us through the [GitHub Support portal](https://support.github.com){% elsif ghes %}your site administrator{% endif %} From 2a9f8eecd818b9c519fe51ca3a96d77d6e225038 Mon Sep 17 00:00:00 2001 From: boxofyellow <54955040+boxofyellow@users.noreply.github.com> Date: Fri, 17 Jul 2026 02:14:22 -0400 Subject: [PATCH 06/12] Update troubleshooting instructions for GitHub Actions (#62302) Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com> --- .../troubleshooting-github-actions-for-your-enterprise.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md b/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md index 4eef7766b604..5612f5250f97 100644 --- a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md +++ b/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md @@ -95,7 +95,7 @@ A part of the Actions setup had problems and needs an administrator to resolve. To install the official bundled actions and workflow templates within a designated organization in {% data variables.product.prodname_ghe_server %}, follow this procedure. -1. Identify an organization that will store the official bundled actions and workflow templates. You can create a new organization or reuse an existing one. +1. Identify an organization that will store the official bundled actions and workflow templates. You can create a new organization or reuse an existing one, as long as that organization is active and hasn't been deleted. * To create a new organization, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). * For assistance with choosing a name for this organization, see [AUTOTITLE](/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#reserved-names). From a3f8a89a3ae0d2e09ea2e8c8b5612b41f79f0aa0 Mon Sep 17 00:00:00 2001 From: Eboni <32157169+EboniLM@users.noreply.github.com> Date: Fri, 17 Jul 2026 02:35:11 -0400 Subject: [PATCH 07/12] Removing Conflicting cost center information (#62304) Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com> Copilot-Session: 62f73add-3a83-4fa0-97a7-38a2ac797641 --- content/billing/how-tos/products/use-cost-centers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/billing/how-tos/products/use-cost-centers.md b/content/billing/how-tos/products/use-cost-centers.md index f71bf6df0a3c..8804394545f1 100644 --- a/content/billing/how-tos/products/use-cost-centers.md +++ b/content/billing/how-tos/products/use-cost-centers.md @@ -23,7 +23,7 @@ category: > [!NOTE] > An enterprise can create up to 500 cost centers. -Create cost centers to monitor and manage expenses for specific organizations or repositories. Multiple organizations, repositories, users, and enterprise teams can be assigned to one cost center. +Create cost centers to monitor and manage expenses for specific organizations or repositories. A single cost center can include multiple resources of any type, such as organizations, repositories, users, and enterprise teams. When you create a cost center, you can add **organizations**, **repositories**, **users**, or **enterprise teams**. The cost center will then track spending for the selected entities. @@ -37,7 +37,7 @@ When you create a cost center, you can add **organizations**, **repositories**, 1. Under **Resources**, select the organizations, repositories, users, and/or enterprise teams that will be a part of the cost center. > [!NOTE] - > A resource (organization, repository, user, or enterprise team) can only be assigned to one cost center at a time. If you add a resource that belongs to a different cost center, it will be moved to the new cost center and you will be notified. + > A resource (organization, repository, user, or enterprise team) can belong to only one cost center at a time. A cost center can hold many resources, but each resource lives in a single cost center. If you add a resource that belongs to a different cost center, it will be moved to the new cost center and you will be notified. {% data reusables.billing.cost-center-create-button %} From 5862bc333aaa97293ac84e67f0416ea6c90134ae Mon Sep 17 00:00:00 2001 From: Cory Calahan Date: Fri, 17 Jul 2026 02:48:47 -0700 Subject: [PATCH 08/12] added ghe-* commands to command line utilities reference (#61990) Co-authored-by: Ryan Trauntvein Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> --- .../command-line-utilities.md | 558 +++++++++++++++++- 1 file changed, 557 insertions(+), 1 deletion(-) diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md b/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md index 1ef76801af63..e01105b00607 100644 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md +++ b/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md @@ -18,6 +18,8 @@ category: You can execute these commands from anywhere on the VM after signing in as an SSH admin user. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh). +All utilities accept `-h` or `--help` to display usage information. + ## General ### ghe-announce @@ -77,6 +79,21 @@ $ ghe-aqueduct resume --queue QUEUE # resumes the specified queue ``` +### ghe-aqueduct-info + +This utility displays the distribution of queued background jobs across queues, along with the jobs currently being processed. + +```shell +ghe-aqueduct-info +``` + +You can use the following flags with `ghe-aqueduct-info`. + +Flag | Description +---- | ---------- +`-v/--verbose` | Run in verbose mode. +`-p/--pretty` | Display in table format. + ### ghe-check-disk-usage This utility checks the disk for large files or files that have been deleted but still have open file handles. This should be run when you're trying to free up space on the root partition. @@ -140,6 +157,39 @@ This utility applies {% data variables.enterprise.management_console %} settings ghe-config-apply ``` +### ghe-config-check + +This utility validates {% data variables.product.prodname_ghe_server %} configuration files and checks individual options. + +```shell +ghe-config-check +``` + +To check a specific file: + +```shell +ghe-config-check /PATH/TO/github.conf +``` + +To output results in JSON format: + +```shell +ghe-config-check json +``` + +To check specific configuration keys: + +```shell +ghe-config-check github-ssl. +``` + +You can use the following flags with `ghe-config-check`. + +Flag | Description +---- | ---------- +`--error-checks-only` | Only run high severity checks that should be treated as blocking errors. +`--warning-checks-only` | Only run low severity checks that can be treated as warnings. + {% ifversion ghes > 3.18 %} ### ghe-crypto @@ -679,6 +729,106 @@ To show the full hook payload, result, and any exceptions for the delivery: ghe-webhook-logs -g DELIVERY_GUID ``` +### ghe-governor-summary + +This utility uses data from `ghe-governor` to display a Git activity summary, including top repositories, users, and IP addresses. + +```shell +ghe-governor-summary +``` + +You can use the following flags with `ghe-governor-summary`. + +Flag | Description +---- | ---------- +`-t/--threshold FLOAT` | Only show the activity summary if the number of Git requests per second exceeds the threshold. Defaults to `1.0`. +`-p/--hours INTEGER` | Specify the time period considered in hours. Defaults to `24`. +`-r/--show-repos` | Always show top repositories regardless of threshold. +`-u/--show-users` | Always show top users regardless of threshold. +`-i/--show-ips` | Always show top IP addresses regardless of threshold. + +### ghe-redis-usage + +This utility calculates memory usage of keys in Redis. + +```shell +ghe-redis-usage +``` + +You can use the following flags with `ghe-redis-usage`. + +Flag | Description +---- | ---------- +`-n/--database N` | Specify the database number. +`-c/--count` | Count the number of keys instead of calculating size. +`-s/--summarize` | Display only a total. +`-H/--human-readable` | Print sizes in human-readable format. + +### ghe-snmpv3-add-user + +This utility adds a read-only user to the SNMPv3 configuration on {% data variables.location.product_location %}. + +```shell +ghe-snmpv3-add-user -A PASSPHRASE -X PASSPHRASE USERNAME +``` + +You can use the following flags with `ghe-snmpv3-add-user`. + +Flag | Description +---- | ---------- +`-A PASSPHRASE` | Set the authentication passphrase. Must be 8 or more characters. +`-X PASSPHRASE` | Set the encryption passphrase. Must be 8 or more characters. If empty, the authentication passphrase is used. +`-a MD5\|SHA` | Set the authentication protocol. Defaults to `SHA`. +`-x DES\|AES` | Set the encryption protocol. Defaults to `AES`. + +### ghe-snmpv3-hash-password + +This utility hashes a password according to RFC 2574 for use with SNMPv3. + +```shell +ghe-snmpv3-hash-password -s PASSWORD +``` + +You can use the following flags with `ghe-snmpv3-hash-password`. + +Flag | Description +---- | ---------- +`-m/--md5` | Hash using the MD5 algorithm. +`-s/--sha` | Hash using the SHA1 algorithm (default). + +### ghe-snmpv3-remove-user + +This utility removes a user from the SNMPv3 configuration on {% data variables.location.product_location %}. + +```shell +ghe-snmpv3-remove-user USERNAME +``` + +### ghe-ssh-audit-login + +This utility retrieves authorized key users and fingerprints for SSH login auditing on {% data variables.location.product_location %}. + +```shell +ghe-ssh-audit-login +``` + +You can use the following flags with `ghe-ssh-audit-login`. + +Flag | Description +---- | ---------- +`-a/--all` | Get all authorized key users and fingerprints. +`-f/--fingerprint FINGERPRINT` | Look up a single fingerprint. +`-d/--date` | Include last login date. +`-j/--json` | Output in JSON format. + +### ghe-system-info + +This utility outputs system information for {% data variables.location.product_location %} in JSON format. + +```shell +ghe-system-info +``` + {% ifversion ghes > 3.21 %} ## Backup and restore @@ -747,6 +897,106 @@ To display a short description of the utility and any valid subcommands: ghe-cluster-balance help ``` +### ghe-cluster-block-ip + +This utility adds firewall rules on a cluster node that block all traffic to and from a given IP address. Currently only supports IPv4 addresses. + +```shell +ghe-cluster-block-ip IP-ADDRESS +``` + +To remove the block, use `ghe-cluster-unblock-ip`. + +### ghe-cluster-config-apply + +This utility validates your `/data/user/common/cluster.conf` configuration file, copies it to each node in the cluster, and configures each node based on the modified file. + +```shell +ghe-cluster-config-apply +``` + +You can use the following flags with `ghe-cluster-config-apply`. + +Flag | Description +---- | ---------- +`-f/--force` | Force all conditional configuration logic to execute. + +### ghe-cluster-config-check + +This utility validates your cluster configuration file and checks individual options. + +```shell +ghe-cluster-config-check +``` + +To check a specific file: + +```shell +ghe-cluster-config-check /PATH/TO/cluster.conf +``` + +To output results in JSON format: + +```shell +ghe-cluster-config-check json +``` + +### ghe-cluster-config-init + +This utility initializes a cluster using the configuration in `/data/user/common/cluster.conf`. SSL must be configured before running this command. + +```shell +ghe-cluster-config-init +``` + +### ghe-cluster-diagnostics + +This utility iterates over all nodes in the cluster and collects diagnostics output from each node. + +```shell +ghe-cluster-diagnostics +``` + +You can use the following flags with `ghe-cluster-diagnostics`. + +Flag | Description +---- | ---------- +`-q/--quiet` | Do not print info messages. +`-v/--verbose` | Run in verbose mode. + +### ghe-cluster-each + +This utility iterates over all nodes in the cluster and executes a command in parallel. + +```shell +ghe-cluster-each -- COMMAND +``` + +You can use the following flags with `ghe-cluster-each`. + +Flag | Description +---- | ---------- +`-o/--offline` | Try running the command on nodes marked offline. +`-r/--role ROLE` | Run only on hosts that provide the specified role. +`-d/--datacenter DC` | Only include nodes within the specified datacenter. +`--primary` | Return only primary hosts. +`--replica` | Return only replica hosts. +`-x/--exclude` | Exclude the local host. + +### ghe-cluster-host-check + +This utility verifies that all hosts in a cluster are ready to be configured. + +```shell +ghe-cluster-host-check +``` + +You can use the following flags with `ghe-cluster-host-check`. + +Flag | Description +---- | ---------- +`-v` | Run with verbose output. + ### ghe-cluster-maintenance With the `ghe-cluster-maintenance` utility, you can set or unset maintenance mode for every node in a cluster. @@ -766,6 +1016,28 @@ $ ghe-cluster-maintenance -u # Unsets maintenance mode ``` +### ghe-cluster-nodes + +This utility lists nodes in the cluster, with options to filter by role, datacenter, or status. + +```shell +ghe-cluster-nodes +``` + +You can use the following flags with `ghe-cluster-nodes`. + +Flag | Description +---- | ---------- +`-o/--offline` | Include offline nodes. +`-i/--ip` | Return hosts along with IP addresses. +`-u/--uuid` | Return hosts along with UUIDs. +`-r/--role ROLE` | Only include nodes with the specified role. +`-d/--datacenter DC` | Only include nodes within the specified datacenter. +`--primary` | Return only primary hosts. +`--replica` | Return only replica hosts. +`-x/--exclude` | Exclude the local host. +`--no-cache` | Exclude cache replicas. + ### ghe-cluster-repl-bootstrap This utility configures high availability replication to a secondary set of cluster nodes. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-clustering/configuring-high-availability-replication-for-a-cluster). @@ -782,6 +1054,29 @@ This utility disables replication to replica nodes for a cluster in a high avail ghe-cluster-repl-teardown ``` +### ghe-cluster-repl-status + +This utility displays the replication status for a cluster in a high availability configuration. + +```shell +ghe-cluster-repl-status +``` + +### ghe-cluster-set-password + +This utility updates the administrator and {% data variables.enterprise.management_console %} password interactively on all cluster nodes. + +```shell +ghe-cluster-set-password +``` + +You can use the following flags with `ghe-cluster-set-password`. + +Flag | Description +---- | ---------- +`--sync` | Copy password files to other servers without setting a new password. +`--clear` | Clear the password for the administrator and {% data variables.enterprise.management_console %} on all servers. + ### ghe-cluster-status Check the health of your nodes and services in a cluster deployment of {% data variables.product.prodname_ghe_server %}. @@ -826,6 +1121,14 @@ To send a bundle to {% data variables.contact.github_support %} and associate th ssh -p 122 admin@HOSTNAME -- 'ghe-cluster-support-bundle -t TICKET_ID' ``` +### ghe-cluster-unblock-ip + +This utility removes firewall rules from a cluster node that block all traffic to and from a given IP address. Currently only supports IPv4 addresses. + +```shell +ghe-cluster-unblock-ip IP-ADDRESS +``` + ### ghe-cluster-failover With the `ghe-cluster-failover` utility, you can fail over to your replica cluster. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-clustering/initiating-a-failover-to-your-replica-cluster). @@ -874,7 +1177,6 @@ Flag | Description ---- | ---------- `-ne/--no-evacuate` | Skips evacuation of data services (warning: may result in data loss). `-v/--verbose` | Prints additional information to the console. -`-h/--help` | Displays help text for the command. > [!NOTE] > * This command can only be used to remove a node from a cluster configuration. It cannot be used to remove a node from a high availability configuration. @@ -1083,6 +1385,81 @@ If your system is configured correctly, you'll see the following output: Actions was enabled! ``` +### ghe-actions-cache-disable + +This utility disables the {% data variables.product.prodname_actions %} cache service on {% data variables.location.product_location %} and stops the associated jobs. + +```shell +ghe-actions-cache-disable +``` + +You can use the following flags with `ghe-actions-cache-disable`. + +Flag | Description +---- | ---------- +`-y/--yes` | Skip the warning prompt. +`-f/--force` | Ignore the current state of the service. + +### ghe-actions-cache-enable + +This utility enables the {% data variables.product.prodname_actions %} cache service on {% data variables.location.product_location %} and starts the associated jobs. + +```shell +ghe-actions-cache-enable +``` + +You can use the following flags with `ghe-actions-cache-enable`. + +Flag | Description +---- | ---------- +`-y/--yes` | Skip the warning prompt. +`-f/--force` | Ignore the current state of the service. + +### ghe-actions-check-connectivity + +This utility checks network connectivity between {% data variables.product.prodname_actions %} services on {% data variables.location.product_location %}. + +```shell +ghe-actions-check-connectivity +``` + +You can use the following flags with `ghe-actions-check-connectivity`. + +Flag | Description +---- | ---------- +`-s/--source` | The name of the source service (`actions`, `mps`, `token`, `artifactcache`). Defaults to `token`. +`-t/--target` | The name of the target service (`actions`, `mps`, `token`, `artifactcache`). Defaults to `mps`. + +{% ifversion ghes > 3.19 %} + +### ghe-actions-diagnostics + +This utility collects diagnostic information specific to {% data variables.product.prodname_actions %} on {% data variables.location.product_location %} that you can send to {% data variables.contact.github_support %} to help investigate issues. + +```shell +ghe-actions-diagnostics +``` + +{% endif %} + +### ghe-actions-dump + +This utility creates a dump of {% data variables.product.prodname_actions %} services on {% data variables.location.product_location %}. You can also use this command to upload the dump directly to {% data variables.contact.github_support %}. + +```shell +ghe-actions-dump +``` + +You can use the following flags with `ghe-actions-dump`. + +Flag | Description +---- | ---------- +`-u/--upload` | Upload the bundle to {% data variables.contact.github_support %}. +`-t/--ticket` | Upload the bundle to {% data variables.contact.github_support %} with a ticket ID. +`-s/--service` | The service name (`actions`, `mps`, `token`, `artifactcache`, `launch-deployer`, `launch-receiver`, `launch-worker`, or `launch-hydro-consumer`). Defaults to `actions`. +`-r/--role` | Role (`frontend`, `backend`, `none`). Defaults to `frontend`. +`-y/--yes` | Skip the warning prompt. + ## {% data variables.product.prodname_registry %} ### ghe-check-blob-connection @@ -1105,6 +1482,22 @@ If your system is configured correctly, you'll see the following output: All Storage tests passed ``` +### ghe-packages-precheck + +This utility checks that a blob storage provider for {% data variables.product.prodname_registry %} is valid on {% data variables.location.product_location %}. Use this to verify your storage configuration before enabling {% data variables.product.prodname_registry %}. + +```shell +ghe-packages-precheck -p PROVIDER -cs "CONNECTION-STRING" +``` + +You can use the following flags with `ghe-packages-precheck`. + +Flag | Description +---- | ---------- +`-p/--provider` | The name of the storage provider (`Azure`, `S3`, or `MinIO`). Defaults to `S3`. +`-cs/--connection-string` | The connection string to the storage provider. +`-cn/--container-name` | The Azure container name to use. + ## High availability {% ifversion ghes > 3.17 %} @@ -1192,6 +1585,26 @@ ghe-repl-teardown This utility disables replication of all datastores on all replica nodes. Run this utility from the primary node before upgrading replicas. For more information, see [AUTOTITLE](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package). +### ghe-repl-node + +This utility manages node-specific replication settings, including enabling active-replica mode, configuring cache servers, and setting datacenter assignments. + +```shell +ghe-repl-node +``` + +You can use the following flags with `ghe-repl-node`. + +Flag | Description +---- | ---------- +`-a/--active` | Enable the active-replica setting on this node. +`-i/--inactive` | Disable the active-replica setting on this node. +`-c/--cache LOCATION` | Make this node a cache server and set its location. +`--cache-domain DOMAIN` | Set the external domain name for the cache location (requires `--cache`). +`-d/--datacenter DATACENTER` | Set the datacenter for this node. +`--default-datacenter` | Reset the datacenter to the default value. +`-v/--verbose` | Run with verbose output. + ### ghe-repl-start-all This utility begins replication of all datastores on all replica nodes. Run this utility from the primary node after upgrading replicas. For more information, see [AUTOTITLE](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package). @@ -1329,6 +1742,23 @@ Currently, this utility's output is similar to downloading the diagnostics info ghe-diagnostics ``` +### ghe-diagnostics-io + +This utility gathers an I/O diagnostics bundle from {% data variables.location.product_location %}. The bundle includes disk I/O performance data that can help {% data variables.contact.github_support %} investigate storage-related issues. + +> [!TIP] +> {% data reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command %} + +```shell +ghe-diagnostics-io +``` + +You can optionally specify a timeout in seconds for data collection. Defaults to 120 seconds. + +```shell +ghe-diagnostics-io TIMEOUT +``` + ### ghe-support-bundle {% data reusables.enterprise_enterprise_support.use_ghe_cluster_support_bundle %} @@ -1554,3 +1984,129 @@ This utility unsuspends the specified user, granting them access to login, push, ```shell ghe-user-unsuspend USERNAME ``` + +## Database and storage + + +{% ifversion ghes > 3.17 %} + +### ghe-elasticsearch-watermarks + +This utility configures Elasticsearch disk watermark settings via API. This is an emergency break-glass solution that allows modification of watermark settings without requiring a configuration run. + +> [!TIP] +> {% data reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command %} + +To set watermark percentages: + +```shell +ghe-elasticsearch-watermarks set LOW-PERCENT HIGH-PERCENT +``` + +To remove all watermark settings and use defaults: + +```shell +ghe-elasticsearch-watermarks remove +``` + +To show current watermark settings: + +```shell +ghe-elasticsearch-watermarks status +``` + +{% endif %} + +{% ifversion ghes > 3.20 %} + +### ghe-es-repair-status + +This utility displays the status of Elasticsearch search index repair operations on {% data variables.location.product_location %}. + +```shell +ghe-es-repair-status +``` + +{% endif %} + +### ghe-es-usage + +This utility calculates disk usage of indices in Elasticsearch on {% data variables.location.product_location %}. + +```shell +ghe-es-usage +``` + +You can use the following flags with `ghe-es-usage`. + +Flag | Description +---- | ---------- +`-s/--summarize` | Display only a total. +`-H/--human-readable` | Print sizes in human-readable format. + + +### ghe-mssql-console + +This utility opens a Microsoft SQL Server database session on {% data variables.location.product_location %}. The MSSQL database is used by {% data variables.product.prodname_actions %} services. + +> [!NOTE] +> {% data reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command %} + +```shell +ghe-mssql-console +``` + +You can use the following flags with `ghe-mssql-console`. + +Flag | Description +---- | ---------- +`-p/--primary` | Connect to the primary MSSQL instance. +`-q/--query` | The string query to execute. +`-i/--input` | Input script file to execute. +`-n/--no-headers` | Do not display column headers. +`-r/--read-only` | Read-only mode for connecting to read-only replicas. +`-y/--yes` | Skip the warning prompt. + +### ghe-mssql-diagnostics + +This utility displays diagnostic information for Microsoft SQL Server to help {% data variables.contact.github_support %} investigate {% data variables.product.prodname_actions %} issues. + +> [!NOTE] +> {% data reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command %} + +```shell +ghe-mssql-diagnostics +``` + +### ghe-mssql-health-check + +This utility runs checks on the state of the Microsoft SQL Server instance on {% data variables.location.product_location %}, including backups and transaction logs. + +```shell +ghe-mssql-health-check +``` + + +## Dependencies + +### ghe-dep-graph-enable + +This utility enables the Dependency Graph service on {% data variables.location.product_location %}. + +```shell +ghe-dep-graph-enable +``` + +## Monitoring + +{% ifversion ghes > 3.17 %} + +### ghe-otelcol-validate + +This utility validates the OpenTelemetry Collector configuration file on {% data variables.location.product_location %}. + +```shell +ghe-otelcol-validate +``` + +{% endif %} From f1224fd4f0beb178fb5d1973390fc8b433c57586 Mon Sep 17 00:00:00 2001 From: "docs-engineering-bot[bot]" <285023527+docs-engineering-bot[bot]@users.noreply.github.com> Date: Fri, 17 Jul 2026 12:01:43 +0100 Subject: [PATCH 09/12] docs: update copilot-cli content from source docs (#62331) Co-authored-by: github-actions[bot] Co-authored-by: hubwriter --- .../cli-command-reference.md | 99 +++++++++++++++---- .../cli-config-dir-reference.md | 39 +++++++- .../cli-plugin-reference.md | 2 +- content/copilot/reference/hooks-reference.md | 8 +- src/content-pipelines/state/copilot-cli.sha | 2 +- 5 files changed, 123 insertions(+), 27 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 42add5338360..7b50b782e02d 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md @@ -26,6 +26,7 @@ docsTeamMetrics: | `copilot login` [OPTION] | Authenticate with {% data variables.product.prodname_copilot_short %} via the OAuth device flow. See [`copilot login` options](#copilot-login-options). | | `copilot mcp` | Manage MCP server configurations from the command line. | | `copilot plugin` | Manage plugins and plugin marketplaces. | +| `copilot plugins list` | Non-interactively inspect every plugin, MCP server, skill, instruction source, and language server discovered for the current working directory—the same resources the in-CLI plugins dashboard shows. See [Using `copilot plugins list`](#using-copilot-plugins-list). | | `copilot skill` | Manage agent skills from the command line (list, add, and remove skills). See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-skills). | | `copilot update` | Download and install the latest version. | | `copilot version` | Display version information and check for updates. | @@ -87,6 +88,30 @@ Fish: copilot completion fish > ~/.config/fish/completions/copilot.fish ``` +### Using `copilot plugins list` + +Run `copilot plugins list` to inspect every plugin, MCP server, skill, instruction source, and language server discovered for the current working directory. Output is grouped by kind, then by configuration scope (user, repository, organization, plugin-contributed, built-in, or unknown). + +```bash +# List everything for the current workspace +copilot plugins list + +# Only MCP servers and skills +copilot plugins list --kind mcp --kind skill + +# Only user-scoped resources, as JSON +copilot plugins list --scope user --json +``` + +| Option | Description | +|-----------------------|------------------------------------------------------------------------------------| +| `--kind KINDS` | Filter by kind. Repeatable or comma-separated: `mcp`, `skill`, `instruction`, `plugin`, `lsp`. | +| `--scope SCOPES` | Filter by configuration scope. Repeatable or comma-separated. | +| `--json` | Emit machine-readable JSON instead of grouped text. | +| `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. | + +Custom agents and session-scoped hooks aren't covered by `copilot plugins list`; both require a live session. + ## Global shortcuts in the interactive interface | Shortcut | Purpose | @@ -95,7 +120,7 @@ copilot completion fish > ~/.config/fish/completions/copilot.fish | `# NUMBER` | Include a {% data variables.product.github %} issue or pull request in the context. | | `! COMMAND` | Execute a command in your local shell, bypassing {% data variables.product.prodname_copilot_short %}. Enter `!` alone on an empty prompt to enter shell mode for running multiple shell commands in sequence. Press Esc or Ctrl+C on an empty prompt to exit shell mode. | | `?` | Open quick help (on an empty prompt). | -| Esc | Cancel the current operation. | +| Esc | Cancel the current operation. Press twice to interrupt the running turn, or to stop background agents when the main agent is idle. | | Ctrl+C | Cancel operation / clear input. Press twice to exit. | | Ctrl+D | Shutdown. | | Ctrl+G | Edit the prompt in an external editor (`$EDITOR`). | @@ -163,6 +188,7 @@ When diff mode is open (entered via `/diff`): | Ctrl+D | Scroll down half a page. | | `Click` | Select the clicked diff line (requires mouse support). | | Mouse scroll | Scroll up or down. | +| Alt/Option+scroll | Scroll one line at a time for fine-grained control. | | `c` | Add or edit a comment on the selected line. | | `s` | Show comments summary (when comments exist). | | `b` | Toggle between unstaged changes and branch diff. | @@ -204,7 +230,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/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). | | `/changelog [summarize] [VERSION\|last N\|since VERSION]`, `/release-notes [summarize] [VERSION\|last N\|since VERSION]` | Display the CLI changelog. Optionally specify a version, a count of recent releases, or a starting version. Add the keyword `summarize` for an AI-generated summary. | -| `/chronicle ` | Session history tools and insights. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/chronicle). | +| `/chronicle ` | Session history tools and insights. The `skills` subcommands draft, review, and track the status of repository skill proposals generated from observed usage. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/chronicle). | | `/clear [PROMPT]`, `/new [PROMPT]`, `/reset [PROMPT]` | Start a new conversation. | | `/clikit [COMPONENT]` | Preview CLI business components (for example, quota info). | | `/compact [FOCUS-INSTRUCTIONS]` | Summarize the conversation history to reduce context window usage. Optionally provide focus instructions to steer the summary—for example, `/compact focus on the auth module`. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/context-management#compaction). | @@ -226,16 +252,19 @@ These are the slash commands you can use from within an interactive CLI session. | `/init` | Initialize {% data variables.product.prodname_copilot_short %} custom instructions and agentic features for this repository. See [Project initialization for {% data variables.product.prodname_copilot_short %}](#project-initialization-for-copilot). | | `/instructions` | View and toggle custom instruction files. | | `/keep-alive [on\|off\|busy\|DURATION]`, `/caffeinate [on\|off\|busy\|DURATION]` | Prevent the machine from going to sleep: while a CLI session is active, while the agent is busy, or for a defined length of time. Accepts durations like `30`, `30m`, `2h`, `1d` (bare numbers default to minutes). | +| `/limits` | Open the interactive response limits dialog. | +| `/limits set max-ai-credits VALUE` | Set a soft maximum for AI Credits allowed per response. Response limits are soft limits that reset for each user message. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/set-session-limit). | +| `/limits unset [max-ai-credits\|all]` | Remove a specific response limit, or all response limits. | | `/list-dirs` | Display all of the directories for which file access has been allowed. | | `/login` | Log in to {% data variables.product.prodname_copilot_short %}. | | `/logout` | Log out of {% data variables.product.prodname_copilot_short %}. | -| `/lsp [show\|test\|reload\|help] [SERVER-NAME]` | Manage the language server configuration. | -| `/mcp [show\|add\|edit\|delete\|disable\|enable\|auth\|reload\|search] [SERVER-NAME]` | Manage the MCP server configuration. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#managing-mcp-servers). | +| `/lsp [show\|test\|reload\|logs\|help] [SERVER-NAME]` | Manage the language server configuration. The `logs` subcommand opens the live LSP services log panel. | +| `/mcp [list\|show\|add\|edit\|delete\|disable\|enable\|auth\|reload\|search] [SERVER-NAME]` | Manage the MCP server configuration. `list` (alias `ls`) lists attached MCP servers and their live status, and is read-only, so it can run while the agent is busy processing a turn; all other subcommands are blocked until the turn finishes. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#managing-mcp-servers). | | `/model`, `/models [MODEL]` | Select the AI model you want to use, or choose **Auto**. See [AUTOTITLE](/copilot/concepts/models/auto-model-selection). | | `/permissions [show\|reset]` | View or clear in-memory tool and path approvals for the current session. | | `/plan [PROMPT]` | Create an implementation plan before coding. | -| `/plugin [marketplace\|install\|uninstall\|update\|list] [ARGS...]` | Manage plugins and plugin marketplaces. See [AUTOTITLE](/copilot/concepts/agents/about-plugins). | -| `/pr [view\|create\|fix\|auto]` | Manage pull requests for the current branch. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests). | +| `/plugin [marketplace\|install\|uninstall\|update\|list] [ARGS...]` | Manage plugins and plugin marketplaces. `list` (alias `ls`, including bare `/plugin`) is read-only and can run while the agent is busy processing a turn; all other subcommands are blocked until the turn finishes. See [AUTOTITLE](/copilot/concepts/agents/about-plugins). | +| `/pr [view\|create\|fix\|auto\|automerge]` | Manage pull requests for the current branch. `auto` drives the pull request to green and stops; `automerge` (alias: `agentmerge`) drives the pull request to green and merges it. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests). | | `/remote [on\|off]` | Show the remote control status (if no argument provided), enable remote steering (`on`), or end the remote connection (`off`). See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely). | | `/rename [NAME]` | Rename the current session (auto-generates a name if omitted; alias for `/session rename`). | | `/research TOPIC` | Run a deep research investigation using {% data variables.product.github %} search and web sources. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/research). | @@ -249,7 +278,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 [show KEY\|KEY\|KEY VALUE]`,
`/config [show KEY\|KEY\|KEY VALUE]` | Open the settings editor, open it focused on a specific setting (`KEY`), set a setting inline (`KEY VALUE`), or display a setting's current value (`show KEY`). See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/change-settings). | -| `/share [file\|html\|gist] [session\|research] [PATH]`, `/export [file\|html\|gist] [session\|research] [PATH]` | Share the session to a Markdown file, interactive HTML file, or {% data variables.product.github %} gist. | +| `/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. | | `/skills [list\|info\|add\|remove\|reload] [ARGS...]` | Manage skills for enhanced capabilities. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-skills). | | `/statusline`, `/footer` | Configure which items appear in the status line. | | `/subagents`, `/agents` | Configure default and per-agent subagent models. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings). | @@ -263,7 +292,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/user [show\|list\|switch]` | Manage the current {% data variables.product.github %} user. | | `/version` | Display version information and check for updates. | | `/fork [NAME]`, `/branch [NAME]` | Fork the current session into a new session, optionally with a name. {% 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 %} | +| `/worktree [branch\|task]`, `/move [branch\|task]` | Create a new Git worktree and switch to it, moving any uncommitted changes along. Pass a branch name, a task description (multiline supported, used as the opening prompt in the new worktree), or omit the argument to auto-generate a branch name 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. @@ -299,7 +328,6 @@ For a complete list of available slash commands enter `/help` in the CLI's inter | `--disable-builtin-mcps` | Disable all built-in MCP servers (currently: `github-mcp-server`). | | `--disable-mcp-server=SERVER-NAME` | Disable a specific MCP server (can be used multiple times). | | `--disallow-temp-dir` | Prevent automatic access to the system temporary directory. | -| `--dynamic-retrieval=CATEGORY=on\|off` | Enable or disable embeddings-based dynamic retrieval per category and persist the choice. Supported category: `skills`. Repeatable—for example, `--dynamic-retrieval skills=off`. | | `--effort=LEVEL`, `--reasoning-effort=LEVEL` | Set the reasoning effort level (`low`, `medium`, `high`, `xhigh`, `max`). `max` is the highest-depth tier for Anthropic models. | | `--enable-all-github-mcp-tools` | Enable all {% data variables.product.github %} MCP server tools, instead of the default CLI subset. Overrides the `--add-github-mcp-toolset` and `--add-github-mcp-tool` options. | | `--enable-memory` | Enable memory in prompt mode (disabled by default). | @@ -311,6 +339,7 @@ For a complete list of available slash commands enter `/help` in the CLI's inter | `-i PROMPT`, `--interactive=PROMPT` | Start an interactive session and automatically execute this prompt. | | `--log-dir=DIRECTORY` | Set the log file directory (default: `~/.copilot/logs/`). | | `--log-level=LEVEL` | Set the log level (choices: `none`, `error`, `warning`, `info`, `debug`, `all`, `default`). | +| `--max-ai-credits=CREDITS` | Set a soft maximum for AI Credits allowed for each response. The limit resets per user message and can be adjusted mid-session with `/limits`. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/set-session-limit). | | `--max-autopilot-continues=COUNT` | Maximum number of continuation messages in autopilot mode (default: unlimited). See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/autopilot). | | `--mode=MODE` | Set the initial agent mode (choices: `interactive`, `plan`, `autopilot`). Cannot be combined with `--autopilot` or `--plan`. | | `--model=MODEL` | Set the AI model you want to use. Pass `auto` as the value to let {% data variables.product.prodname_copilot_short %} pick the best available model automatically. See [AUTOTITLE](/copilot/concepts/models/auto-model-selection). | @@ -326,7 +355,7 @@ For a complete list of available slash commands enter `/help` in the CLI's inter | `--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). | | `--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). | +| `-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 `--mode` or `--autopilot`. | | `--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). | @@ -469,8 +498,7 @@ copilot --allow-tool='MyMCP' | `COPILOT_MODEL` | Set the AI model. | | `COPILOT_PROMPT_FRAME` | Set to `1` to enable the decorative UI frame around the input prompt, or `0` to disable it. Overrides the `PROMPT_FRAME` experimental feature flag for the current session. | | `COPILOT_SKILLS_DIRS` | Comma-separated list of additional directories for skills. | -| `COPILOT_SUBAGENT_MAX_CONCURRENT` | Maximum concurrent subagents across the entire session tree. Default varies by plan (see [Subagent limits](#subagent-limits)). Range: `1`–`256`. | -| `COPILOT_SUBAGENT_MAX_DEPTH` | Maximum subagent nesting depth. Default: `6`. Range: `1`–`256`. | +| `COPILOT_STRIP_REASONING_ON_RESUME` | Set to `0` or `false` to keep BYOK reasoning tokens across a session resume instead of stripping them. Defaults to stripping them. | | `GH_HOST` | {% data variables.product.github %} hostname for both {% data variables.product.prodname_cli %} and {% data variables.copilot.copilot_cli_short %} (default: `github.com`). Set to your {% data variables.product.prodname_ghe_cloud %} with data residency hostname. Override with `COPILOT_GH_HOST` for {% data variables.copilot.copilot_cli_short %} only. | | `GH_TOKEN` | Authentication token. Takes precedence over `GITHUB_TOKEN`. | | `GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS` | Set to `true` to load project extensions and allow extension management tools in prompt mode (`-p`). Disabled by default to prevent running repository-controlled extension code without interactive trust. | @@ -509,6 +537,10 @@ If you don't want to create this file, you can permanently hide this startup mes For more information, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions). +### Custom instructions imports + +Instruction files support `@path` imports. Prefix a line with `@` followed by a path to inline the contents of another file. Paths can be relative to the instruction file's directory or absolute. Imports are resolved recursively, up to a depth limit, with cycle and size guards. This is supported in `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`. + ## Hooks reference For detailed information about hooks—including hook configuration formats, hook events, input payloads, and decision control—see [AUTOTITLE](/copilot/reference/hooks-reference). @@ -745,6 +777,14 @@ pwsh -NoProfile -Command "`$json = Get-Content '.vscode/mcp.json' -Raw | Convert On Windows, replace `pwsh` with `powershell` if you are using Windows PowerShell instead of PowerShell Core. +### Stdio server output + +The MCP stdio transport reserves stdout exclusively for newline-delimited JSON-RPC frames. The CLI automatically filters out any non-JSON lines—plain-text logs, exception stack traces, or whitespace-only lines—before passing output to the protocol parser. + +Write all diagnostic output to **stderr**, not stdout. A server that writes logs or error messages to stdout can trigger a parse-error feedback loop that stalls the initialization handshake; the filter prevents this by silently dropping non-JSON frames. + +Lines longer than 1 MB bypass the structural check and are forwarded as-is, to avoid splitting or dropping oversized but valid protocol frames (for example, a large `tools/list` response). + ## Skills reference Skills are Markdown files that extend what the CLI can do. Each skill lives in its own directory containing a `SKILL.md` file. When invoked (via `/SKILL-NAME` or automatically by the agent), the skill's content is injected into the conversation. @@ -779,6 +819,8 @@ Skills are loaded from these locations in priority order (first found wins for d Remote skills are projected alongside local skills and follow the same name-based priority when a local skill has the same name. +When two plugins provide skills with the same name, both coexist using plugin-qualified invocation names such as `/my-plugin/search` and `/other-plugin/search`. The bare name routes to the higher-priority plugin. This applies to skills only; commands keep the standard tier-based deduplication, where the higher-priority source wins. + ### Commands (alternative skill format) Commands are an alternative to skills stored as individual `.md` files in `.claude/commands/`. The command name is derived from the filename. Command files use a simplified format (no `name` field required) and support `argument-hint`, `description`, `allowed-tools`, and `disable-model-invocation`. Commands have lower priority than skills with the same name. @@ -876,11 +918,12 @@ write_agent(agent_id="explore-auth", message="Focus on token refresh flow and re The CLI enforces depth and concurrency limits to prevent runaway agent spawning. -| Limit | Default | Environment variable | -|-------|---------|---------------------| -| Max depth | `6` | `COPILOT_SUBAGENT_MAX_DEPTH` | +| Limit | Default | Max | +|-------|---------|-----| +| Max depth | `6` | `256` | +| Max concurrent | plan-based | `32` | -**Depth** counts how many agents are nested within one another. When the depth limit is reached, the innermost agent cannot spawn further subagents. **Concurrency** counts how many subagents are running simultaneously across the entire session tree. When the limit is reached, new subagent requests are rejected until an active agent completes. Values are clamped between `1` and `256`. +**Depth** counts how many agents are nested within one another. When the depth limit is reached, the innermost agent cannot spawn further subagents. **Concurrency** counts how many subagents are running simultaneously across the entire session tree. When the limit is reached, new subagent requests are rejected until an active agent completes. The default concurrency limit depends on your {% data variables.product.prodname_copilot_short %} plan: @@ -893,7 +936,18 @@ The default concurrency limit depends on your {% data variables.product.prodname | Enterprise | `32` | | Usage-based billing | `32` | -Override the concurrency limit by setting the `COPILOT_SUBAGENT_MAX_CONCURRENT` environment variable before starting the CLI. +Usage-based billing users can override these limits with the `subagents.maxConcurrency` and `subagents.maxDepth` settings: + +```json +{ + "subagents": { + "maxConcurrency": 16, + "maxDepth": 10 + } +} +``` + +Values outside the valid range are clamped: `maxConcurrency` is capped at `32`, and `maxDepth` is capped at `256`. These settings are ignored for plans that don't use usage-based billing. See [Configuration file settings](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings). ## Sidekick agents @@ -908,6 +962,8 @@ description: Gathers relevant context when the working directory changes sidekick: triggers: - session.context_changed + - event: user.message + limit: 1 behavior: persistent maxSendsPerTurn: 2 --- @@ -918,16 +974,23 @@ Summarize recent changes and any relevant project structure. ### Sidekick triggers +Each entry in `triggers` is either a bare event-name string, which fires an unlimited number of times, or an object with `event` and an optional `limit`. + | Event | Description | |-------|-------------| | `user.message` | Fires on every user message. | | `session.context_changed` | Fires when the working directory, repository, or branch changes (for example, after `cd` or switching Git branches). | +| Trigger field | Type | Default | Description | +|----------------|------|---------|-------------| +| `event` | `string` | Required | Session event type that launches this agent. | +| `limit` | `number` | Unlimited | Maximum number of times this trigger may fire per session. Must be a positive integer when set. | + ### Sidekick configuration fields | Field | Type | Default | Description | |-------|------|---------|-------------| -| `triggers` | `string[]` | Required | Session event types that launch this agent. At least one trigger is required. | +| `triggers` | `string[]` or object[] | Required | Session event types that launch this agent. At least one trigger is required. | | `behavior` | `string` | `"restart"` | `"restart"`: cancel any prior run and start fresh on each trigger. `"persistent"`: keep the same long-lived run alive and deliver new messages into the existing loop instead of relaunching. | | `maxSendsPerTurn` | `number` | `1` | Maximum inbox sends allowed per trigger. In `"persistent"` mode, each delivered user message resets this budget. | 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 82fd273f5b00..92caaad08ba7 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 @@ -440,7 +440,7 @@ These settings apply across all your sessions and repositories. You can use the | `beepOnSchedule` | `boolean` | `true` | Play an audible beep when a scheduled `/every` or `/after` run finishes. | | `builtInAgents.rubberDuck` | `boolean` | `true` | Enable the rubber-duck subagent that provides adversarial feedback on agent plans. | | `builtInAgents.rubberDuckAutoInvoke` | `boolean` | `false` | Include proactive prompting for automatic rubber-duck invocation. Set to `true` to opt into additional rubber-duck nudges during agent turns. | -| `colorMode` | `"default"` \| `"github"` \| `"dim"` \| `"high-contrast"` \| `"colorblind"` | `"github"` | Color palette mode. Managed by the `/settings` and `/theme` slash commands. | +| `colorMode` | `"default"` \| `"github"` \| `"dim"` \| `"high-contrast"` \| `"colorblind"` | `"github"` | Deprecated alias for `theme`. Prefer `theme`. | | `compactPaste` | `boolean` | `true` | Collapse large pastes (more than 10 lines) into compact tokens. | | `companyAnnouncements` | `string[]` | `[]` | Custom messages shown randomly on startup. One message is randomly selected each time the CLI starts. Useful for team announcements or reminders. | | `continueOnAutoMode` | `boolean` | `false` | Automatically switch to auto mode when rate-limited. When `true`, eligible rate limit errors trigger an automatic switch to auto mode and retry. Does not apply to global rate limits or BYOK providers. | @@ -450,7 +450,7 @@ These settings apply across all your sessions and repositories. You can use the | `disableAllHooks` | `boolean` | `false` | Disable all hooks (both repository-level and user-level). | | `disabledMcpServers` | `string[]` | `[]` | MCP server names to disable. Listed servers are configured but not started. | | `disabledSkills` | `string[]` | `[]` | Skill names to disable. Listed skills are discovered but not loaded. | -| `dynamicRetrieval` | `{ skills?: boolean }` | unset | Per-category control of embeddings-based dynamic instruction retrieval. Set `skills` to `false` to disable retrieval for skills. Can also be set with `--dynamic-retrieval` (for example, `--dynamic-retrieval skills=off`); using the flag persists the preference to this file. | +| `dynamicRetrieval` | `{ skills?: boolean }` | unset | Per-category control of embeddings-based dynamic instruction retrieval. Set `skills` to `false` to disable retrieval for skills. | | `effortLevel` | `string` | `"medium"` | Reasoning effort level for extended thinking: `"low"`, `"medium"`, `"high"`, or `"xhigh"`. Higher levels use more compute. | | `enabledMcpServers` | `string[]` | `[]` | Enable built-in MCP servers that are disabled by default (for example, `"computer-use"`). | | `enabledPlugins` | `Record` | `{}` | Declarative plugin auto-install. Keys are plugin specs; values are `true` (enabled) or `false` (disabled). | @@ -479,16 +479,19 @@ These settings apply across all your sessions and repositories. You can use the | `showTipsOnStartup` | `boolean` | `true` | Show a random command tip when the CLI starts. | | `skillDirectories` | `string[]` | `[]` | Additional directories to search for custom skill definitions (in addition to `~/.copilot/skills/`). | | `statusLine` | `object` | — | Custom status line display. `type`: must be `"command"`. `command`: path to an executable script that receives session JSON on stdin and prints status content to stdout. `padding`: optional number of left-padding spaces. | +| `stayInAutopilot` | `boolean` | `false` | Stay in autopilot mode after an autopilot task completes, instead of reverting to interactive mode. | | `storeTokenPlaintext` | `boolean` | `false` | Allow authentication tokens to be stored in plain text in `config.json` when no system keychain is available. | | `stream` | `boolean` | `true` | Enable streaming responses. | | `streamerMode` | `boolean` | `false` | Hide preview model names and quota details. Useful when demonstrating {% data variables.copilot.copilot_cli_short %} or screen sharing. | | `subagents.agents` | `object` | `{}` | Per-agent model configuration, keyed by agent name. Each value is an object with optional `model` (string), `effortLevel` (string), and `contextTier` (`"default"`, `"long_context"`, or `"inherit"`) fields. Set any field to `"inherit"` to use the parent session's value at dispatch time. Use the `/subagents` slash command to configure these settings interactively. | | `subagents.disabledSubagents` | `string[]` | `[]` | Agent names to prevent from being dispatched. Only the `rubber-duck` agent cannot be disabled via this setting. All other built-in agents—including `explore`, `task`, `code-review`, `general-purpose`, `research`, and `security-review`—can be disabled. | +| `subagents.maxConcurrency` | `number` | plan-based | Maximum concurrent subagents for this session. Only honored for usage-based billing users; ignored for all other plans. Capped at `32`. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#subagent-limits). | +| `subagents.maxDepth` | `number` | `6` | Maximum subagent nesting depth. Only honored for usage-based billing users; ignored for all other plans. Capped at `256`. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#subagent-limits). | | `tabs.enabled` | `boolean` | `true` | Show the home tab bar. Set to `false` to hide it entirely. | | `tabs.hide` | `string[]` | `[]` | Tab identifiers to hide. Accepted values: `"copilot"`, `"agents"`, `"issues"`, `"pull-requests"`, `"gists"` (matched case-insensitively). | | `tabs.sort` | `string[]` | `[]` | Order in which tabs are displayed. Tabs not listed keep their default relative order after the listed ones. Unknown identifiers are ignored. | | `terminalProgress` | `boolean` | `true` | Emit OSC 9;4 terminal progress indicators while the agent is working. Supported terminals include Windows Terminal, iTerm2, Ghostty, and ConEmu. | -| `theme` | `"auto"` \| `"dark"` \| `"light"` | `"auto"` | Terminal color theme. `"auto"` detects the terminal background and chooses accordingly. | +| `theme` | `"default"` \| `"github"` \| `"dim"` \| `"high-contrast"` \| `"colorblind"` | `"github"` | Color palette for terminal output. Managed by the `/settings` and `/theme` slash commands. `colorMode` is a deprecated alias for this setting. | | `toolSearch` | `boolean` | model- and feature-dependent | Controls tool search (deferred tool loading). Set `toolSearch: false` to opt out of tool search. | | `updateTerminalTitle` | `boolean` | `true` | Show the current intent in the terminal tab or window title. | @@ -510,6 +513,34 @@ Only the keys listed in the following table are supported at the repository leve | `hooks` | `object` | Concatenated—repository hooks run after user hooks | Hook definitions scoped to this repository. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/use-hooks). | | `mergeStrategy` | `"rebase"` \| `"merge"` | Repository takes precedence | Conflict resolution strategy for `/pr fix conflicts`. | +A plugin enabled only through a repository's `enabledPlugins` is scoped to that repository: it auto-installs and activates in the declaring repository, but stays disabled globally, so it never activates in unrelated projects. Leaving the repository, or the repository disabling the plugin, tears down its MCP server and deactivates its agents and skills for the session. + +### Repository-level models allowlist (`.github/allowed_models.txt`) + +Restrict which built-in models a repository can use with a plain-text allowlist at `.github/allowed_models.txt`, resolved from the current working directory's repository root (or the working directory itself outside a repository). + +Each line is a glob pattern matched against model IDs, or a `fallback:` directive naming the model to use when the configured or requested model isn't allowed: + +```text +# .github/allowed_models.txt +fallback: gpt-5.2 +gpt-5.2 +gpt-5.4 +claude-sonnet-* +``` + +| Rule | Description | +|------|-------------| +| `*` | Allow all models (default when no file is present). | +| `MODEL-ID` | Allow an exact model ID. | +| `GLOB-PATTERN` | Allow model IDs matching the glob (for example, `claude-sonnet-*`). | +| `fallback: MODEL-ID` | Required exactly once. The model {% data variables.product.prodname_copilot_short %} uses when the active model isn't allowed. | +| `#` | Comment line. | + +Negated patterns (`!pattern`) aren't supported, the fallback model must be an exact ID (not a glob), and the fallback model must itself match one of the configured globs. {% data variables.copilot.copilot_cli_short %} re-evaluates the policy on `/cd` and rejects an invalid file with an error before running. + +The allowlist governs only {% data variables.product.prodname_copilot_short %}'s built-in models. It cannot filter out custom models added using the bring your own API keys (BYOK) method. BYOK models remain listed and selectable regardless of the patterns you configure, and the `fallback:` directive never applies to them. For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/enable-custom-models) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/enable-custom-models). + ### Local settings (`.github/copilot/settings.local.json`) Create `.github/copilot/settings.local.json` in the repository for personal overrides that should not be committed. Add this file to `.gitignore`. @@ -520,6 +551,8 @@ The local configuration file uses the same schema as the repository configuratio IT administrators can push baseline policy using Mobile Device Management (MDM) managed settings instead of requiring per-user configuration. These settings apply device-level defaults for supported keys and load before user settings. +{% data variables.copilot.copilot_cli_short %} also loads server-managed settings at startup, in addition to MDM. Device-managed (MDM) and server-managed settings are resolved **per key**: MDM's value wins for any key it sets, and the server's value fills in keys MDM leaves unset. This lets an organization set some policy via MDM (for example, `permissions`) while still receiving other managed defaults (for example, `model`) from the server. + ### MDM managed settings sources {% data variables.copilot.copilot_cli_short %} reads managed settings from platform-specific MDM or file-based locations. diff --git a/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md b/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md index 1461723da821..dcb4e0aa56c6 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md @@ -213,7 +213,7 @@ If you install multiple plugins it's possible that some custom agents, skills, M * **MCP servers** use last-wins precedence. - If you install a plugin that defines an MCP server with the same server name as an MCP server you have already installed, the plugin's definition takes precedence. You can use the `--additional-mcp-config` command-line option to override an MCP server configuration with the same name, installed using a plugin. + If you install a plugin that defines an MCP server with the same server name as an MCP server you have already installed, the plugin's definition takes precedence. You can use the `--additional-mcp-config` command-line option to override an MCP server configuration with the same name, installed using a plugin. If two or more plugins declare an MCP server with the same name, the CLI uses the version from the plugin that loaded last and shows a warning naming every prior plugin that defined it. * **Built-in tools and agents** are always present and cannot be overridden by user-defined components. diff --git a/content/copilot/reference/hooks-reference.md b/content/copilot/reference/hooks-reference.md index d6c9ee922ca2..f09509306217 100644 --- a/content/copilot/reference/hooks-reference.md +++ b/content/copilot/reference/hooks-reference.md @@ -364,7 +364,7 @@ Payloads for PascalCase `PreToolUse` report `tool_name` as the Claude tool name Tools with no Claude equivalent keep their runtime names. > [!IMPORTANT] -> **Command vs HTTP fail behavior for `preToolUse`:** Command `preToolUse` hooks are **fail-closed** on errors—a crash or non-zero exit denies the tool call. Command hook **timeouts are fail-open**—a timed-out hook surfaces a warning and lets the tool call proceed through the normal permission flow. 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. +> **Command vs HTTP fail behavior for `preToolUse`:** Command `preToolUse` hooks are **fail-closed** on errors—a crash or non-zero exit (other than exit `2`) denies the tool call. Command hook **timeouts are always fail-open, even for `preToolUse` and admin-deployed policy hooks**—a timed-out hook surfaces a warning and lets the tool call proceed through the normal permission flow instead of denying it. 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. ### `postToolUse` / `PostToolUse` @@ -720,7 +720,7 @@ Several events accept an optional `matcher` regex on each hook entry that filter | `view` | Read file contents. | | `web_fetch` | Fetch web pages. | -If multiple hooks of the same type are configured, they execute in order. For `preToolUse`, if any hook returns `"deny"`, the tool is blocked. For most events, hook failures (non-zero exit codes other than `2`, or timeouts) are logged and skipped. **Exception: `preToolUse` command hooks are fail-closed on errors**—a crash or non-zero exit (other than exit 2) denies the tool call. Timeouts for `preToolUse` command hooks are fail-open: a warning is surfaced and the tool call proceeds through the normal permission flow. +If multiple hooks of the same type are configured, they execute in order. For `preToolUse`, if any hook returns `"deny"`, the tool is blocked. For most events, hook failures (non-zero exit codes other than `2`, or timeouts) are logged and skipped. **Exception: `preToolUse` command hooks are fail-closed on non-timeout errors**—a crash or non-zero exit (other than exit 2) denies the tool call. **Timeouts are always fail-open, including for `preToolUse` and admin-deployed policy hooks**: a warning is surfaced and the tool call proceeds through the normal permission flow rather than being denied. ## Exit codes for command hooks @@ -729,9 +729,9 @@ If multiple hooks of the same type are configured, they execute in order. For `p | `0` | Success. `stdout` is parsed as the hook output JSON if present. | | `2` | Treated as a warning by default. `stderr` is surfaced to the user but the run continues. For `permissionRequest`, exit `2` is treated as `{"behavior":"deny"}` and any `stdout` JSON is merged in. For `postToolUseFailure`, exit `2` is treated as `additionalContext` and `stdout` is appended to the failure shown to the agent. | | Other non-zero | Logged as a hook failure. The run continues (fail-open). **Exception: `preToolUse` is fail-closed**—a non-zero exit (other than exit 2) denies the tool call with `"Denied by preToolUse hook (hook errored)"`. | -| Timeout | Killed after `timeoutSec`. Error logged, agent continues. **Exception: `preToolUse` command hooks fail-open on timeout**—a warning is surfaced and the tool call proceeds through the normal permission flow rather than being denied. A crashed or explicitly-denying hook still fails-closed. | +| Timeout | Killed after `timeoutSec`. Error logged, execution continues. **Timeouts are fail-open for every event, including `preToolUse` and admin-deployed policy hooks**—a warning is surfaced and processing proceeds as if the hook had not run. For `preToolUse`, the tool call proceeds through the normal permission flow rather than being denied. A crashed or explicitly-denying hook still fails-closed; only timeouts are exempt. | -For most events, non-zero exits and timeouts are logged and skipped—agent execution continues. For `preToolUse` command hooks, crashes and non-zero exits (other than exit 2) fail-closed and deny the tool call, but **timeouts fail-open**—a slow or unreachable hook must not silently block tool calls. Exit 2 is handled per the rules above and does not block execution. +For most events, non-zero exits and timeouts are logged and skipped—agent execution continues. For `preToolUse` command hooks, crashes and non-zero exits (other than exit 2) fail-closed and deny the tool call, but **timeouts always fail-open**—a slow or unreachable hook must not silently block tool calls or work, even when the hook was deployed by an administrator as policy. Exit 2 is handled per the rules above and does not block execution. ## Disable all hooks diff --git a/src/content-pipelines/state/copilot-cli.sha b/src/content-pipelines/state/copilot-cli.sha index ecb47dbfd9f6..5210dbe33807 100644 --- a/src/content-pipelines/state/copilot-cli.sha +++ b/src/content-pipelines/state/copilot-cli.sha @@ -1 +1 @@ -d22bd667d8cc283c28bda93ab28a4b8bfd62040c +d5de6fff1643c40899009b7caf57ce10f9ec6d8b From ca81a7d5633573bf83edd71f7dbdffa44894355f Mon Sep 17 00:00:00 2001 From: Stoney <19228888+ThatStoney@users.noreply.github.com> Date: Fri, 17 Jul 2026 07:04:49 -0400 Subject: [PATCH 10/12] Remove stale HTTPS clone 500 known issue from 3.21.2 release notes (#62333) --- data/release-notes/enterprise-server/3-21/2.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/data/release-notes/enterprise-server/3-21/2.yml b/data/release-notes/enterprise-server/3-21/2.yml index ae78e002fd98..33eefa8fe69d 100644 --- a/data/release-notes/enterprise-server/3-21/2.yml +++ b/data/release-notes/enterprise-server/3-21/2.yml @@ -83,8 +83,6 @@ sections: When applying an enterprise security configuration to all repositories (for example, enabling Secret Scanning or Code Scanning across all repositories), the system immediately enqueues enablement jobs for every organization in the enterprise simultaneously. For enterprises with a large number of repositories, this can result in significant system load and potential performance degradation. If you manage a large enterprise with many organizations and repositories, we recommend applying security configurations at the organization level rather than at the enterprise level in the UI. This allows you to enable security features incrementally and monitor system performance as you roll out changes. - | On instances with multiple Git storage nodes in a voting configuration, including cluster and geo-replication high availability topologies, upgrading may fail to correctly install Actions that ship with the new version. In some cases, previous versions of these Actions remain on the instance. To resolve this issue, run the following commands on the primary node: `ghe-config --unset 'app.actions.actions-repos-sha1sum'`, `ghe-config-apply`, and `/usr/local/share/enterprise/ghe-run-init-actions-graph`. - - | - Users attempting to clone repositories via HTTPS receive an "Internal Server Error" message, and the clone operation fails with a 500 error. This issue affects all deployment topologies including cluster, standalone, high availability, and geo-replication configurations. errata: - | A note about running the pre-upgrade stage outside the maintenance window has been added to the release notes. [Updated: 2026-06-30] From bf2de82cd42ee6a6d7a58bc658dd9ed7584a2c1f Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 17 Jul 2026 06:57:19 -0700 Subject: [PATCH 11/12] Bump github/gh-base-image/gh-base-noble from 20260713-090615-gb0d388add to 20260716-144716-g39f79b427 in the baseimages group (#62330) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index 163187add267..16e4868bb612 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,7 +10,7 @@ # --------------------------------------------------------------- # To update the sha: # https://github.com/github/gh-base-image/pkgs/container/gh-base-image%2Fgh-base-noble -FROM ghcr.io/github/gh-base-image/gh-base-noble:20260713-090615-gb0d388add@sha256:8708e26b53b2304cf8d933be5e8fbca4fa4d07b3ba6e4be238372a5d3029e443 AS base +FROM ghcr.io/github/gh-base-image/gh-base-noble:20260716-144716-g39f79b427@sha256:4c49a03485e03d2976c45a876365e98f3f3f29eb4ba1546cf03434cd5ae8bbca AS base # Install curl for Node install and determining the early access branch # Install git for cloning docs-early-access & translations repos From 0b02cd6336f4eebda1e409b45a89dab5c2193d9a Mon Sep 17 00:00:00 2001 From: "docs-engineering-bot[bot]" <285023527+docs-engineering-bot[bot]@users.noreply.github.com> Date: Fri, 17 Jul 2026 15:07:49 +0100 Subject: [PATCH 12/12] docs: update copilot-cli content from source docs (#62335) Co-authored-by: github-actions[bot] Co-authored-by: hubwriter --- .../cli-command-reference.md | 110 +++++++++++++++--- .../cli-config-dir-reference.md | 29 ++++- .../cli-plugin-reference.md | 51 ++++++-- content/copilot/reference/hooks-reference.md | 38 +++++- src/content-pipelines/state/copilot-cli.sha | 2 +- 5 files changed, 200 insertions(+), 30 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 7b50b782e02d..068af86570bc 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md @@ -37,7 +37,7 @@ docsTeamMetrics: |-------------------------|-----------------------------------------------------------------------------------------------| | `--host HOST` | {% data variables.product.github %} host URL (default: `https://github.com`). Use this to authenticate with a {% data variables.product.prodname_ghe_cloud %} instance that uses data residency (for example, `https://example.ghe.com`). | -The default authentication mode is a web-based browser flow. After completion, an authentication token is stored securely in the system credential store. If a credential store is not found, the token is stored in a plain text config file under `~/.copilot/` (or the directory specified by `COPILOT_HOME` if set). +The default authentication mode is a web-based browser flow. After completion, an authentication token is stored securely in the system credential store. If a credential store is not found, the token is stored in a plain text configuration file under `~/.copilot/` (or the directory specified by `COPILOT_HOME` if set). Alternatively, {% data variables.copilot.copilot_cli_short %} will use an authentication token found in environment variables. The following are checked in order of precedence: `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`. This method is most suitable for headless use such as automation. @@ -112,6 +112,54 @@ copilot plugins list --scope user --json Custom agents and session-scoped hooks aren't covered by `copilot plugins list`; both require a live session. +### `copilot plugins enable` / `copilot plugins disable` + +Enable or disable a plugin, MCP server, or skill by name. The change persists to configuration and applies to future sessions. + +```bash +# Disable an MCP server +copilot plugins disable github --mcp + +# Enable a skill +copilot plugins enable my-skill --skill + +# Enable a plugin (default kind) +copilot plugins enable spark@copilot-plugins +``` + +| Option | Description | +|------------------------|------------------------------------------------------------------------------------| +| `--plugin` | Target a plugin (default). | +| `--mcp` | Target an MCP server. | +| `--skill` | Target a skill. | +| `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. | + +Instructions are session-scoped only and can't be toggled with these commands. Language servers, agents, and hooks are managed elsewhere. + +### `copilot plugins remove` + +Uninstall a plugin, remove an MCP server, or delete a skill by name. + +```bash +# Remove an MCP server +copilot plugins remove github --mcp + +# Delete a personal or project skill +copilot plugins remove my-skill --skill + +# Uninstall a plugin (default kind) +copilot plugins remove spark@copilot-plugins +``` + +| Option | Description | +|------------------------|------------------------------------------------------------------------------------| +| `--plugin` | Remove a plugin (default). | +| `--mcp` | Remove an MCP server. | +| `--skill` | Remove a personal or project skill. | +| `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. | + +With `--skill`, pass either a skill name or the path to a custom skill directory you added. A skill name deletes that skill's files; a custom directory path only unregisters the directory and leaves its files on disk. Only personal and project skills you added can be deleted—skills provided by a plugin or the builtin set can't be removed this way (disable them instead). Instruction sources are discovered from disk and can't be removed here. + ## Global shortcuts in the interactive interface | Shortcut | Purpose | @@ -119,7 +167,7 @@ Custom agents and session-scoped hooks aren't covered by `copilot plugins list`; | `@ FILENAME` | Include file contents in the context. | | `# NUMBER` | Include a {% data variables.product.github %} issue or pull request in the context. | | `! COMMAND` | Execute a command in your local shell, bypassing {% data variables.product.prodname_copilot_short %}. Enter `!` alone on an empty prompt to enter shell mode for running multiple shell commands in sequence. Press Esc or Ctrl+C on an empty prompt to exit shell mode. | -| `?` | Open quick help (on an empty prompt). | +| `?` | Open quick help (on an empty prompt). Press again to dismiss and insert a literal `?`. | | Esc | Cancel the current operation. Press twice to interrupt the running turn, or to stop background agents when the main agent is idle. | | Ctrl+C | Cancel operation / clear input. Press twice to exit. | | Ctrl+D | Shutdown. | @@ -227,7 +275,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/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). | | `/app` | Launch the {% data variables.copilot.github_copilot_app %}, or show the download URL if the app is not installed. | -| `/ask QUESTION` | Ask a quick side question without adding to the conversation history. {% data reusables.copilot.experimental %} | +| `/ask QUESTION` | Ask a quick side question without adding to the conversation history. | | `/allow-all [on\|off\|show]`, `/yolo [on\|off\|show]` | Enable all permissions (tools, paths, and URLs). | | `/changelog [summarize] [VERSION\|last N\|since VERSION]`, `/release-notes [summarize] [VERSION\|last N\|since VERSION]` | Display the CLI changelog. Optionally specify a version, a count of recent releases, or a starting version. Add the keyword `summarize` for an AI-generated summary. | | `/chronicle ` | Session history tools and insights. The `skills` subcommands draft, review, and track the status of repository skill proposals generated from observed usage. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/chronicle). | @@ -259,12 +307,13 @@ These are the slash commands you can use from within an interactive CLI session. | `/login` | Log in to {% data variables.product.prodname_copilot_short %}. | | `/logout` | Log out of {% data variables.product.prodname_copilot_short %}. | | `/lsp [show\|test\|reload\|logs\|help] [SERVER-NAME]` | Manage the language server configuration. The `logs` subcommand opens the live LSP services log panel. | -| `/mcp [list\|show\|add\|edit\|delete\|disable\|enable\|auth\|reload\|search] [SERVER-NAME]` | Manage the MCP server configuration. `list` (alias `ls`) lists attached MCP servers and their live status, and is read-only, so it can run while the agent is busy processing a turn; all other subcommands are blocked until the turn finishes. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#managing-mcp-servers). | -| `/model`, `/models [MODEL]` | Select the AI model you want to use, or choose **Auto**. See [AUTOTITLE](/copilot/concepts/models/auto-model-selection). | +| `/mcp [list\|show\|add\|edit\|delete\|disable\|enable\|auth\|reload\|search] [SERVER-NAME]` | Manage the MCP server configuration. `list` (alias `ls`) prints a plain-text list of configured servers with connection status and live state, and is read-only, so it can run while the agent is busy processing a turn; all other subcommands are blocked until the turn finishes. Sandboxed local servers show a `connected (sandboxed)` status. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#managing-mcp-servers). | +| `/model [--repo\|--local] [MODEL]`, `/models` | Select the AI model you want to use, or choose **Auto**. `--repo`/`--local` pins the default model in repository settings instead of the current session. Press Tab on a model with a long-context variant to toggle its Context column between the default and long-context window. See [AUTOTITLE](/copilot/concepts/models/auto-model-selection). | | `/permissions [show\|reset]` | View or clear in-memory tool and path approvals for the current session. | | `/plan [PROMPT]` | Create an implementation plan before coding. | | `/plugin [marketplace\|install\|uninstall\|update\|list] [ARGS...]` | Manage plugins and plugin marketplaces. `list` (alias `ls`, including bare `/plugin`) is read-only and can run while the agent is busy processing a turn; all other subcommands are blocked until the turn finishes. See [AUTOTITLE](/copilot/concepts/agents/about-plugins). | | `/pr [view\|create\|fix\|auto\|automerge]` | Manage pull requests for the current branch. `auto` drives the pull request to green and stops; `automerge` (alias: `agentmerge`) drives the pull request to green and merges it. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests). | +| `/refine TEXT` | Rewrite a roughly composed prompt into a clear one for review. Run with no arguments (via Ctrl+X then `/refine`) to clean up the current input box. Can be particularly useful for prompts entered by speaking. | | `/remote [on\|off]` | Show the remote control status (if no argument provided), enable remote steering (`on`), or end the remote connection (`off`). See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely). | | `/rename [NAME]` | Rename the current session (auto-generates a name if omitted; alias for `/session rename`). | | `/research TOPIC` | Run a deep research investigation using {% data variables.product.github %} search and web sources. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/research). | @@ -277,7 +326,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/search [QUERY]`, `/find [QUERY]` | Search the conversation timeline. {% data reusables.copilot.experimental %} | | `/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 [show KEY\|KEY\|KEY VALUE]`,
`/config [show KEY\|KEY\|KEY VALUE]` | Open the settings editor, open it focused on a specific setting (`KEY`), set a setting inline (`KEY VALUE`), or display a setting's current value (`show KEY`). See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/change-settings). | +| `/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`). The dialog shows **User**, **Repo**, and **Repo (local)** tabs—switch with Tab/Shift+Tab; a setting overridden in another scope shows a badge naming which scope wins. 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-5.2`. 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. | | `/skills [list\|info\|add\|remove\|reload] [ARGS...]` | Manage skills for enhanced capabilities. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-skills). | | `/statusline`, `/footer` | Configure which items appear in the status line. | @@ -291,8 +340,10 @@ These are the slash commands you can use from within an interactive CLI session. | `/usage` | Display session usage metrics and statistics, including per-model token totals. | | `/user [show\|list\|switch]` | Manage the current {% data variables.product.github %} user. | | `/version` | Display version information and check for updates. | +| `/voice [on\|off\|models\|devices]` | Toggle voice mode, browse available voice models, or choose the input device (microphone). | | `/fork [NAME]`, `/branch [NAME]` | Fork the current session into a new session, optionally with a name. {% data reusables.copilot.experimental %} | -| `/worktree [branch\|task]`, `/move [branch\|task]` | Create a new Git worktree and switch to it, moving any uncommitted changes along. Pass a branch name, a task description (multiline supported, used as the opening prompt in the new worktree), or omit the argument to auto-generate a branch name from the conversation. Requires a Git repository. {% data reusables.copilot.experimental %} | +| `/worktree [branch\|task]` | Create a new Git worktree off `HEAD` and switch to it, leaving uncommitted changes behind in the current worktree. Pass a branch name, a task description (multiline supported, used as the opening prompt in the new worktree), or omit the argument to auto-generate a branch name from the conversation. Requires a Git repository. {% data reusables.copilot.experimental %} | +| `/move [branch\|task]` | Move uncommitted changes into a new Git worktree and switch to it. Pass a branch name, a task description (multiline supported, used as the opening prompt in the new worktree), or omit the argument to auto-generate a branch name 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. @@ -320,9 +371,9 @@ For a complete list of available slash commands enter `/help` in the CLI's inter | `--bash-env` | Enable `BASH_ENV` support for bash shells. | | `-C DIRECTORY` | Change working directory before doing anything else. | | `--connect[=SESSION-ID]` | Connect directly to a remote session (optionally specify a session ID or task ID). Conflicts with `--resume` and `--continue`. | -| `--context TIER`. | Set the context window tier (overrides the persisted setting). Choices: "default", "long_context". | +| `--context TIER`. | Set the context window tier for tiered-pricing models (overrides the persisted setting and is honored in fresh interactive sessions). Choices: "default", "long_context". | | `--config-dir=DIRECTORY` | This option for setting the configuration directory is deprecated. Use the `COPILOT_HOME` environment variable instead. | -| `--continue` | Resume the most recent session in the current working directory, falling back to the globally most recent session. | +| `--continue` | Resume the most recent session in the current working directory, falling back to the globally most recent session. Conflicts with `--resume`. | | `--deny-tool=TOOL ...` | Tools the CLI does not have permission to use. Will not prompt for permission. For multiple tools, use a quoted, comma-separated list. | | `--deny-url=URL ...` | Deny access to specific URLs or domains, takes precedence over `--allow-url`. For multiple URLs, use a quoted, comma-separated list. | | `--disable-builtin-mcps` | Disable all built-in MCP servers (currently: `github-mcp-server`). | @@ -340,7 +391,7 @@ For a complete list of available slash commands enter `/help` in the CLI's inter | `--log-dir=DIRECTORY` | Set the log file directory (default: `~/.copilot/logs/`). | | `--log-level=LEVEL` | Set the log level (choices: `none`, `error`, `warning`, `info`, `debug`, `all`, `default`). | | `--max-ai-credits=CREDITS` | Set a soft maximum for AI Credits allowed for each response. The limit resets per user message and can be adjusted mid-session with `/limits`. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/set-session-limit). | -| `--max-autopilot-continues=COUNT` | Maximum number of continuation messages in autopilot mode (default: unlimited). See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/autopilot). | +| `--max-autopilot-continues=COUNT` | Maximum number of continuation messages in autopilot mode (default: unlimited). Must be a non-negative integer; malformed values (`NaN`, negative, or fractional) are rejected. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/autopilot). | | `--mode=MODE` | Set the initial agent mode (choices: `interactive`, `plan`, `autopilot`). Cannot be combined with `--autopilot` or `--plan`. | | `--model=MODEL` | Set the AI model you want to use. Pass `auto` as the value to let {% data variables.product.prodname_copilot_short %} pick the best available model automatically. See [AUTOTITLE](/copilot/concepts/models/auto-model-selection). | | `--mouse[=VALUE]` | Enable or disable mouse support in the interactive interface. VALUE can be `on` (default) or `off`. When enabled, the CLI captures mouse events—scroll wheel, clicks, and so on—to navigate its own interface, such as scrolling the timeline or clicking tabs. When disabled, the terminal's native mouse behavior, such as text selection and scrollback, is preserved. When you set this option explicitly, the value is persisted to your configuration file. | @@ -361,11 +412,13 @@ For a complete list of available slash commands enter `/help` in the CLI's inter | `--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). | | `--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). | -| `-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. | +| `-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`. | | `-s`, `--silent` | Output only the agent response (without usage statistics), useful for scripting with `-p`. | | `--screen-reader` | Enable screen reader optimizations. | | `--secret-env-vars=VAR ...` | Redact an environment variable from shell and MCP server environments (can be used multiple times). For multiple variables, use a quoted, comma-separated list. The values in the `GITHUB_TOKEN` and `COPILOT_GITHUB_TOKEN` environment variables are redacted from output by default. | | `--session-id ID` | Use an exact session or task ID when you do not want `--resume`'s broader matching by ID prefix or session name. If the ID matches an existing session or task, that session or task is resumed. If nothing matches, a new session is created only when the value is a valid UUID. Names and ID prefixes do not create new sessions. Do not combine this option with other session-selection or session-starting options such as `--resume`, `--continue`, or `--connect`, because they compete to decide which session to open or create. | +| `--sandbox` | Enable the OS-level shell sandbox for this session only, without changing your saved sandbox setting. Useful with `-p`. {% data reusables.copilot.experimental %} | +| `--no-sandbox` | Disable the OS-level shell sandbox for this session only, without changing your saved sandbox setting. {% data reusables.copilot.experimental %} | | `--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`). @@ -477,13 +530,17 @@ copilot --allow-tool='MyMCP(create_issue)' # Allow all tools from a server copilot --allow-tool='MyMCP' + +# Deny writes to a specific path (exact or trailing-path-segment match; no glob support yet) +copilot --deny-tool='write(secret.txt)' ``` +`--deny-tool='write(PATH)'` scopes the denial to that path—other writes are unaffected. The match resolves symlinks and `.`/`..` segments, and is case-insensitive on macOS and Windows. + ## Environment variables | Variable | Description | |----------|-------------| -| `COLORFGBG` | Fallback for dark/light terminal background detection. | | `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. | @@ -499,6 +556,9 @@ copilot --allow-tool='MyMCP' | `COPILOT_PROMPT_FRAME` | Set to `1` to enable the decorative UI frame around the input prompt, or `0` to disable it. Overrides the `PROMPT_FRAME` experimental feature flag for the current session. | | `COPILOT_SKILLS_DIRS` | Comma-separated list of additional directories for skills. | | `COPILOT_STRIP_REASONING_ON_RESUME` | Set to `0` or `false` to keep BYOK reasoning tokens across a session resume instead of stripping them. Defaults to stripping them. | +| `COPILOT_SUBAGENT_MAX_CONCURRENT` | Maximum concurrent subagents per session (default: `32`, range: `1`–`256`). | +| `COPILOT_SUBAGENT_MAX_DEPTH` | Maximum subagent nesting depth (default: `4`, range: `1`–`128`). | +| `COPILOT_TASK_WAIT_TIMEOUT_SECONDS` | Maximum seconds `-p` (and `-p --autopilot`) waits for pending background agents or shell commands to finish before exiting (default: `600`; `0` exits immediately without waiting). | | `GH_HOST` | {% data variables.product.github %} hostname for both {% data variables.product.prodname_cli %} and {% data variables.copilot.copilot_cli_short %} (default: `github.com`). Set to your {% data variables.product.prodname_ghe_cloud %} with data residency hostname. Override with `COPILOT_GH_HOST` for {% data variables.copilot.copilot_cli_short %} only. | | `GH_TOKEN` | Authentication token. Takes precedence over `GITHUB_TOKEN`. | | `GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS` | Set to `true` to load project extensions and allow extension management tools in prompt mode (`-p`). Disabled by default to prevent running repository-controlled extension code without interactive trust. | @@ -537,6 +597,21 @@ If you don't want to create this file, you can permanently hide this startup mes For more information, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions). +### Custom instructions locations + +{% data variables.copilot.copilot_cli_short %} loads custom instructions from these locations simultaneously (all are merged): + +| Location | Notes | +|----------|-------| +| `CLAUDE.md` | In Git root and cwd | +| `GEMINI.md` | In Git root and cwd | +| `AGENTS.md` | In Git root and cwd | +| `.github/instructions/**/*.instructions.md` | In Git root and cwd | +| `.github/copilot-instructions.md` | In Git root and cwd | +| `$HOME/.copilot/copilot-instructions.md` | — | +| `$HOME/.copilot/instructions/**/*.instructions.md` | — | +| `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` | Additional directories via environment variable. | + ### Custom instructions imports Instruction files support `@path` imports. Prefix a line with `@` followed by a path to inline the contents of another file. Paths can be relative to the instruction file's directory or absolute. Imports are resolved recursively, up to a depth limit, with cycle and size guards. This is supported in `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`. @@ -549,6 +624,8 @@ For detailed information about hooks—including hook configuration formats, hoo MCP servers provide additional tools to the CLI agent. Configure persistent servers in `~/.copilot/mcp-config.json`. Use `--additional-mcp-config` to add servers for a single session. +Local (stdio) servers that spawn inside the sandbox (see the `/sandbox` slash command) show a `connected (sandboxed)` status in `copilot mcp list` and `/mcp list`, since remote (HTTP/SSE) servers are never sandboxed. {% data reusables.copilot.experimental %} + ### `copilot mcp` subcommand Use `copilot mcp` to manage MCP server configurations from the command line without starting an interactive session. @@ -617,7 +694,7 @@ Use `--registry` in the `args` array to pull a package from a private npm regist } ``` -The `--registry` flag and other npm config flags (`--userconfig`, `--globalconfig`, `--prefix`, `--cache`, `--node-options`, `--workspace`, `-w`) are treated as value-consuming arguments when computing the server's identity fingerprint. This ensures enterprise allowlist checks and registry verification work correctly when these flags appear before the package name. +The `--registry` flag and other npm configuration flags (`--userconfig`, `--globalconfig`, `--prefix`, `--cache`, `--node-options`, `--workspace`, `-w`) are treated as value-consuming arguments when computing the server's identity fingerprint. This ensures enterprise allowlist checks and registry verification work correctly when these flags appear before the package name. ### Remote server configuration fields @@ -1022,6 +1099,10 @@ Use `/permissions reset` to clear in-memory approvals for the current session. ## Security +### Plan mode + +`/plan` starts a read-only analysis session that prevents write operations and shell command execution while allowing full codebase exploration. Mutating tool calls—editor writes, `apply_patch` to non-plan files, mutating shell commands, and pull request creation—are hard-blocked at the tool layer, not just discouraged by the system prompt. Subagents spawned from a plan-mode session inherit the same restriction. Reads and writes to the plan file itself are still allowed. + ### Command safety analysis Shell commands are analyzed before execution to identify potentially dangerous patterns: @@ -1195,6 +1276,9 @@ One span per tool call. Span kind: `INTERNAL`. | `github.copilot.tool.call.count` | Counter | calls | Tool invocations by `gen_ai.tool.name` and `success` | | `github.copilot.tool.call.duration` | Histogram | s | Tool execution latency by `gen_ai.tool.name` | | `github.copilot.agent.turn.count` | Histogram | turns | LLM round-trips per agent invocation | +| `github.copilot.mcp.server.connection.count` | Counter | attempts | Completed MCP server connection attempts by transport and outcome | +| `github.copilot.code.lines_added` | Counter | lines | Lines added by file-editing tools, recorded in real time | +| `github.copilot.code.lines_removed` | Counter | lines | Lines removed by file-editing tools, recorded in real time | ### Span events 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 92caaad08ba7..8a972f552b27 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 @@ -60,6 +60,9 @@ By default, this file is located in the `~/.copilot` directory, which is the use > [!NOTE] > User-editable settings were originally stored in `config.json`. They have been moved to `settings.json`. Any user settings present in `config.json` on startup are automatically migrated to `settings.json`. +> [!NOTE] +> If `settings.json` fails to read, parse, or validate, {% data variables.copilot.copilot_cli_short %} ignores the invalid values (recognized `config.json` values are still merged in) and shows a startup warning on the timeline identifying the error. Fix the reported issue to restore the affected settings. + For the full list of settings and how they interact with repository-level configuration, see [Configuration file settings](#configuration-file-settings) later in this article. > [!TIP] @@ -441,6 +444,7 @@ These settings apply across all your sessions and repositories. You can use the | `builtInAgents.rubberDuck` | `boolean` | `true` | Enable the rubber-duck subagent that provides adversarial feedback on agent plans. | | `builtInAgents.rubberDuckAutoInvoke` | `boolean` | `false` | Include proactive prompting for automatic rubber-duck invocation. Set to `true` to opt into additional rubber-duck nudges during agent turns. | | `colorMode` | `"default"` \| `"github"` \| `"dim"` \| `"high-contrast"` \| `"colorblind"` | `"github"` | Deprecated alias for `theme`. Prefer `theme`. | +| `commandHistoryMaxSize` | `number` | `50` | Maximum number of recent commands retained for input history and reverse search. Must be an integer between `1` and `1000`. | | `compactPaste` | `boolean` | `true` | Collapse large pastes (more than 10 lines) into compact tokens. | | `companyAnnouncements` | `string[]` | `[]` | Custom messages shown randomly on startup. One message is randomly selected each time the CLI starts. Useful for team announcements or reminders. | | `continueOnAutoMode` | `boolean` | `false` | Automatically switch to auto mode when rate-limited. When `true`, eligible rate limit errors trigger an automatic switch to auto mode and retry. Does not apply to global rate limits or BYOK providers. | @@ -467,6 +471,7 @@ These settings apply across all your sessions and repositories. You can use the | `model` | `string` | varies | AI model to use. Set to `"auto"` to let {% data variables.product.prodname_copilot_short %} pick the best available model automatically. Managed by the `/model` slash command. | | `mouse` | `boolean` | `true` | Enable mouse support. Can also be set with `--mouse` or `--no-mouse`. | | `permissions.disableBypassPermissionsMode` | `string` | — | When set to `"disable"`, all allow-all flags (`--allow-all-tools`, `--allow-all-paths`, `--allow-all-urls`, `--allow-all`, `--yolo`) are suppressed at startup and cannot be used to grant elevated permissions. | +| `pinnedPrompts` | `boolean` | `true` | Pin the current section's user prompt just below the top bar while scrolling the timeline, so it stays clear which request the visible output belongs to. CLI UI only—has no effect on prompts sent to the model. | | `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). | @@ -476,6 +481,7 @@ These settings apply across all your sessions and repositories. You can use the | `respectGitignore` | `boolean` | `true` | Exclude gitignored files from the `@` file mention picker. When `false`, the picker includes files normally excluded by `.gitignore`. | | `screenReader` | `boolean` | `false` | Enable screen reader optimizations. | | `scrollbar` | `boolean` | `true` | Show the scrollbar in scrollable views. Set to `false` to hide it and use the full terminal width. | +| `showTimestamps` | `boolean` | `true` | Show dim `HH:mm` timestamps next to user messages in the timeline. | | `showTipsOnStartup` | `boolean` | `true` | Show a random command tip when the CLI starts. | | `skillDirectories` | `string[]` | `[]` | Additional directories to search for custom skill definitions (in addition to `~/.copilot/skills/`). | | `statusLine` | `object` | — | Custom status line display. `type`: must be `"command"`. `command`: path to an executable script that receives session JSON on stdin and prints status content to stdout. `padding`: optional number of left-padding spaces. | @@ -502,16 +508,26 @@ Repository settings apply to everyone who works in the repository. They are comm > [!NOTE] > The plugin-related keys in the repository configuration file (`enabledPlugins` and `extraKnownMarketplaces`) are also read by {% data variables.copilot.copilot_cloud_agent %}, not only {% data variables.copilot.copilot_cli_short %}. This lets you enable the same plugins for both clients from a single file. For more information about plugins, see [AUTOTITLE](/copilot/concepts/agents/about-plugins). -Only the keys listed in the following table are supported at the repository level. Any other keys—including keys that are valid in the user configuration file—are silently ignored. +Only the keys listed in the following table are supported at the repository level. Any other keys—including keys that are valid in the user configuration file—are silently ignored. Each supported key has a directional merge policy that keeps the override fail-closed and safe. | Key | Type | Merge behavior | Description | |-----|------|---------------|-------------| | `companyAnnouncements` | `string[]` | Replaced—repository takes precedence | Messages shown randomly on startup. | +| `contextTier` | `"default"` \| `"long_context"` | Replaced—repository takes precedence | Pin the default context tier. | +| `deniedUrls` | `string[]` | Union—repository can add entries, never remove | URLs or domains blocked. | | `disableAllHooks` | `boolean` | Repository takes precedence | Disable all hooks. | +| `disabledMcpServers` | `string[]` | Union—repository can add entries, never remove | MCP servers configured but not started. | +| `disabledSkills` | `string[]` | Union—repository can add entries, never remove | Skills discovered but not loaded. | +| `effortLevel` | `string` | Replaced—repository takes precedence | Pin the default reasoning effort. | | `enabledPlugins` | `Record` | Merged—repository overrides user for same key | Declarative plugin auto-install. | | `extraKnownMarketplaces` | `Record` | Merged—repository overrides user for same key | Plugin marketplaces available in this repository. | -| `hooks` | `object` | Concatenated—repository hooks run after user hooks | Hook definitions scoped to this repository. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/use-hooks). | -| `mergeStrategy` | `"rebase"` \| `"merge"` | Repository takes precedence | Conflict resolution strategy for `/pr fix conflicts`. | +| `hooks` | `object` | Merged—repository overrides user for same key | Hook definitions scoped to this repository. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/use-hooks). | +| `includeCoAuthoredBy` | `boolean` | Replaced—repository takes precedence | Add a `Co-authored-by` trailer to commits. | +| `mergeStrategy` | `"rebase"` \| `"merge"` | Replaced—repository takes precedence | Conflict resolution strategy for `/pr fix conflicts`. | +| `model` | `string` | Replaced—repository takes precedence | Pin the default model for this repo. | +| `respectGitignore` | `boolean` | Tighten-only—repository can enable, never disable | Exclude gitignored files from the `@` file mention picker. | + +`model`, `effortLevel`, and `contextTier` overrides only apply when the working directory is [trusted](/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools). A plugin enabled only through a repository's `enabledPlugins` is scoped to that repository: it auto-installs and activates in the declaring repository, but stays disabled globally, so it never activates in unrelated projects. Leaving the repository, or the repository disabling the plugin, tears down its MCP server and deactivates its agents and skills for the session. @@ -553,6 +569,8 @@ IT administrators can push baseline policy using Mobile Device Management (MDM) {% data variables.copilot.copilot_cli_short %} also loads server-managed settings at startup, in addition to MDM. Device-managed (MDM) and server-managed settings are resolved **per key**: MDM's value wins for any key it sets, and the server's value fills in keys MDM leaves unset. This lets an organization set some policy via MDM (for example, `permissions`) while still receiving other managed defaults (for example, `model`) from the server. +Long-running sessions re-fetch and re-apply managed settings hourly, so policy changes—for example, an organization enabling `permissions.disableBypassPermissionsMode`—take effect without restarting the session. + ### MDM managed settings sources {% data variables.copilot.copilot_cli_short %} reads managed settings from platform-specific MDM or file-based locations. @@ -574,12 +592,16 @@ Write file-based managed settings as JSON. ```json { + "model": "auto", "permissions": { "disableBypassPermissionsMode": "disable" } } ``` +> [!NOTE] +> `model` is a top-level key. Older configurations that nested it as `permissions.model` still work—the runtime falls back to that location when the top-level `model` key is absent—but write new configurations with `model` at the top level. + ### Supported keys Only the following keys are supported in MDM managed settings. @@ -590,6 +612,7 @@ Only the following keys are supported in MDM managed settings. | `extraKnownMarketplaces` | Add trusted plugin marketplaces | | `model` | Set a default model for all users (overridden by the `--model` flag or a resumed-session model) | | `permissions` | Set managed permissions, including `disableBypassPermissionsMode` | +| `remoteControl` | Control whether sessions on this device can be controlled from other devices. `mode` is `"enabled"`, `"disabled"`, or `"requireSSO"` (requires `requiredSsoOrganizations` when set). | | `strictKnownMarketplaces` | Restrict plugins to known marketplaces | ## Further reading diff --git a/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md b/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md index dcb4e0aa56c6..94865a249d26 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md @@ -20,7 +20,7 @@ For an overview of what plugins are and how they work across {% data variables.p ## CLI commands -You can use the following commands in the terminal to manage plugins for {% data variables.copilot.copilot_cli_short %}. +You can use the following commands in the terminal to manage plugins for {% data variables.copilot.copilot_cli_short %}. `copilot plugin` and `copilot plugins` are interchangeable—use whichever reads better for the subcommand. | Command | Description | |------------------------------------------------|-------------| @@ -30,10 +30,13 @@ You can use the following commands in the terminal to manage plugins for {% data | `copilot plugin update NAME` | Update a named plugin. Use `--all` to update all installed plugins at once. | | `copilot plugin enable NAME` | Enable a previously disabled plugin | | `copilot plugin disable NAME` | Disable a plugin without uninstalling it | -| `copilot plugin marketplace add SPECIFICATION` | Register a marketplace | +| `copilot plugin marketplace add SPECIFICATION` | Register a marketplace. Use `--name NAME` to set a custom local name. | | `copilot plugin marketplace list` | List registered marketplaces | | `copilot plugin marketplace browse NAME` | Browse marketplace plugins | -| `copilot plugin marketplace remove NAME` | Unregister a marketplace | +| `copilot plugin marketplace update NAME` | Re-fetch a marketplace's plugin catalog. Use `--all` to refresh every registered marketplace. | +| `copilot plugin marketplace remove NAME` | Unregister a marketplace. Refused if plugins from the marketplace are still installed; pass `--force` to also uninstall those plugins. | + +Non-interactively, `copilot plugins enable NAME --plugin`, `copilot plugins disable NAME --plugin`, and `copilot plugins remove NAME --plugin` provide the same enable, disable, and uninstall operations. `--plugin` is the default kind and can be omitted for these three commands. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#using-copilot-plugins-list) for the non-interactive `--mcp` and `--skill` kinds, which extend these commands to MCP servers and skills. ### Plugin specification for `install` command @@ -78,10 +81,10 @@ These tell the CLI where to find your plugin's components. All are optional. The | `agents` | string \| string[] | `agents/` | Path(s) to agent directories (`.agent.md` files). | | `skills` | string \| string[] | `skills/` | Path(s) to skill directories (`SKILL.md` files). | | `commands` | string \| string[] | — | Path(s) to command directories. | -| `hooks` | string \| object | — | Path to a hooks config file, or an inline hooks object. | +| `hooks` | string \| object | — | Path to a hooks configuration file, or an inline hooks object. | | `extensions`| string \| string[] \| object | — | Path(s) to extension directories. Use `{ paths: [...], exclusive: true }` to suppress built-in extensions. | -| `mcpServers`| string \| object | — | Path to an MCP config file (e.g., `.mcp.json`), or inline server definitions. | -| `lspServers`| string \| object | — | Path to an LSP config file, or inline server definitions. | +| `mcpServers`| string \| object | — | Path to an MCP configuration file (e.g., `.mcp.json`), or inline server definitions. | +| `lspServers`| string \| object | — | Path to an LSP configuration file, or inline server definitions. | ### Example `plugin.json` file @@ -183,11 +186,41 @@ For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-cop | `commands` | string \| string[] | No | Path(s) to command directories. | | `agents` | string \| string[] | No | Path(s) to agent directories. | | `skills` | string \| string[] | No | Path(s) to skill directories. | -| `hooks` | string \| object | No | Path to hooks config or inline hooks object. | -| `mcpServers` | string \| object | No | MCP servers to activate when the plugin is installed. Accepts an inline server map or a path to a JSON config file. Used when the plugin source does not ship its own MCP configuration. | -| `lspServers` | string \| object | No | Path to LSP config or inline server definitions. | +| `hooks` | string \| object | No | Path to hooks configuration or inline hooks object. | +| `mcpServers` | string \| object | No | MCP servers to activate when the plugin is installed. Accepts an inline server map or a path to a JSON configuration file. Used when the plugin source does not ship its own MCP configuration. | +| `lspServers` | string \| object | No | Path to LSP configuration or inline server definitions. | | `strict` | boolean | No | When `true` (the default), plugins must conform to the full schema and validation rules. When `false`, relaxed validation is used, allowing more flexibility—especially for direct installs or legacy plugins. | +#### Plugin source types + +The `source` field on a plugin entry accepts a relative path string, or an object describing a {% data variables.product.github %} repository or Git URL source: + +```json +{ + "source": { + "source": "github", + "repo": "owner/repo", + "ref": "v1.0.0", + "path": "plugins/my-plugin" + } +} +``` + +Both the `github` and `url` source types accept an optional `sha` field to pin installs to an exact commit, in addition to (or instead of) `ref`: + +```json +{ + "source": { + "source": "github", + "repo": "owner/repo", + "sha": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3", + "path": "plugins/my-plugin" + } +} +``` + +`sha` must be a full 40-character commit SHA. Pin to a `sha` for reproducible installs that are immune to force-pushes or tag/branch moves. + ## File locations | Item | Path | diff --git a/content/copilot/reference/hooks-reference.md b/content/copilot/reference/hooks-reference.md index f09509306217..f717c684ddf2 100644 --- a/content/copilot/reference/hooks-reference.md +++ b/content/copilot/reference/hooks-reference.md @@ -79,6 +79,9 @@ This section applies to **{% data variables.copilot.copilot_cloud_agent %} only* Hook configuration files use JSON format with version `1`. +> [!NOTE] +> If a hook configuration file loaded from a directory (for example, `.github/hooks/`) contains a malformed hook item, only that item is dropped and logged—valid sibling hooks in the same file still load. Structural errors (invalid JSON, a bad `version`, or a non-array event list) still reject the entire file. Hooks defined inline in `settings.json` remain strict: any item-level validation error rejects the whole `hooks` field. Other configuration files always load independently. + ### Command hooks Command hooks run shell scripts and are supported on all hook types. @@ -225,6 +228,7 @@ The table below lists every supported event. The **Cloud agent** column shows wh | `subagentStart` | A subagent is spawned (before it runs). Supports a `matcher` regex pattern (the value of the `matcher` field) to filter by agent name. | Optional — cannot block creation, but `additionalContext` is prepended to the subagent's prompt. | Fires. | | `subagentStop` | A subagent completes. | Yes — can block and force continuation. | Fires. | | `userPromptSubmitted` | The user submits a prompt. | No | Fires at most once, for the prompt supplied to the job. There is no follow-up user input. | +| `userPromptTransformed` | Fires after the runtime transforms a submitted prompt into its model-facing content, just before that content is emitted and persisted to session history. Runs for the primary message and for every preceding message in a batched submission. Mutation-only — it can rewrite the content the model receives, but not block or handle the turn. System notifications never trigger it. | Yes — can rewrite the model-facing content. | Fires. | ## Hook event input payloads @@ -310,6 +314,32 @@ Each hook event delivers a JSON payload to the hook handler. Two payload formats } ``` +### `userPromptTransformed` + +Fires after the runtime transforms a submitted prompt into its model-facing content, just before that content is emitted and persisted to session history. Runs for the primary message and for every preceding message in a batched submission. Mutation-only—it can rewrite the content the model receives, but not block or handle the turn. System notifications never trigger it. + +**Input:** + +```typescript +{ + sessionId: string; + timestamp: number; // epoch-ms integer + cwd: string; + prompt: string; // user prompt after userPromptSubmitted hooks have run + transformedPrompt: string; // runtime-transformed content the model will receive +} +``` + +**Output:** + +```typescript +{ + modifiedTransformedPrompt?: string; // Replaces the model-facing content +} +``` + +Return `{}` or empty to leave the transformed content unchanged. `modifiedTransformedPrompt` replaces only the content sent to the model and stored in session history—the prompt displayed in the timeline is unaffected—and the replacement is replayed unchanged if the session is resumed. + ### `preToolUse` / `PreToolUse` **camelCase input:** @@ -364,7 +394,7 @@ Payloads for PascalCase `PreToolUse` report `tool_name` as the Claude tool name Tools with no Claude equivalent keep their runtime names. > [!IMPORTANT] -> **Command vs HTTP fail behavior for `preToolUse`:** Command `preToolUse` hooks are **fail-closed** on errors—a crash or non-zero exit (other than exit `2`) denies the tool call. Command hook **timeouts are always fail-open, even for `preToolUse` and admin-deployed policy hooks**—a timed-out hook surfaces a warning and lets the tool call proceed through the normal permission flow instead of denying it. 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. +> **Command vs HTTP fail behavior for `preToolUse`:** Command `preToolUse` hooks are **fail-closed** on errors—a crash or non-zero exit (including exit `2`) denies the tool call, even if the hook's stdout JSON reports `permissionDecision: "allow"`. Command hook **timeouts are always fail-open, even for `preToolUse` and admin-deployed policy hooks**—a timed-out hook surfaces a warning and lets the tool call proceed through the normal permission flow instead of denying it. 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. ### `postToolUse` / `PostToolUse` @@ -720,18 +750,18 @@ Several events accept an optional `matcher` regex on each hook entry that filter | `view` | Read file contents. | | `web_fetch` | Fetch web pages. | -If multiple hooks of the same type are configured, they execute in order. For `preToolUse`, if any hook returns `"deny"`, the tool is blocked. For most events, hook failures (non-zero exit codes other than `2`, or timeouts) are logged and skipped. **Exception: `preToolUse` command hooks are fail-closed on non-timeout errors**—a crash or non-zero exit (other than exit 2) denies the tool call. **Timeouts are always fail-open, including for `preToolUse` and admin-deployed policy hooks**: a warning is surfaced and the tool call proceeds through the normal permission flow rather than being denied. +If multiple hooks of the same type are configured, they execute in order. For `preToolUse`, if any hook returns `"deny"`, the tool is blocked. For most events, hook failures (non-zero exit codes other than `2`, or timeouts) are logged and skipped. **Exception: `preToolUse` command hooks are fail-closed on exit `2` and on non-timeout errors**—exit `2`, a crash, or any other non-zero exit (other than a timeout) denies the tool call, even if the hook's stdout JSON reports `permissionDecision: "allow"`. **Timeouts are always fail-open, including for `preToolUse` and admin-deployed policy hooks**: a warning is surfaced and the tool call proceeds through the normal permission flow rather than being denied. ## Exit codes for command hooks | Exit code | Meaning | |-----------|---------| | `0` | Success. `stdout` is parsed as the hook output JSON if present. | -| `2` | Treated as a warning by default. `stderr` is surfaced to the user but the run continues. For `permissionRequest`, exit `2` is treated as `{"behavior":"deny"}` and any `stdout` JSON is merged in. For `postToolUseFailure`, exit `2` is treated as `additionalContext` and `stdout` is appended to the failure shown to the agent. | +| `2` | Treated as a warning by default. `stderr` is surfaced to the user but the run continues. For `permissionRequest` and `preToolUse`, exit `2` is treated as a deny: any `stdout` JSON is merged with the deny decision and the tool call is denied even if that JSON reports `permissionDecision: "allow"`. For `postToolUseFailure`, exit `2` is treated as `additionalContext` and `stdout` is appended to the failure shown to the agent. | | Other non-zero | Logged as a hook failure. The run continues (fail-open). **Exception: `preToolUse` is fail-closed**—a non-zero exit (other than exit 2) denies the tool call with `"Denied by preToolUse hook (hook errored)"`. | | Timeout | Killed after `timeoutSec`. Error logged, execution continues. **Timeouts are fail-open for every event, including `preToolUse` and admin-deployed policy hooks**—a warning is surfaced and processing proceeds as if the hook had not run. For `preToolUse`, the tool call proceeds through the normal permission flow rather than being denied. A crashed or explicitly-denying hook still fails-closed; only timeouts are exempt. | -For most events, non-zero exits and timeouts are logged and skipped—agent execution continues. For `preToolUse` command hooks, crashes and non-zero exits (other than exit 2) fail-closed and deny the tool call, but **timeouts always fail-open**—a slow or unreachable hook must not silently block tool calls or work, even when the hook was deployed by an administrator as policy. Exit 2 is handled per the rules above and does not block execution. +For most events, non-zero exits and timeouts are logged and skipped—agent execution continues. For `preToolUse` command hooks, exit 2, crashes, and other non-zero exits all fail-closed and deny the tool call—exit 2 always denies, even if the hook's `stdout` JSON reports `permissionDecision: "allow"`—but **timeouts always fail-open**—a slow or unreachable hook must not silently block tool calls or work, even when the hook was deployed by an administrator as policy. ## Disable all hooks diff --git a/src/content-pipelines/state/copilot-cli.sha b/src/content-pipelines/state/copilot-cli.sha index 5210dbe33807..878da12aecef 100644 --- a/src/content-pipelines/state/copilot-cli.sha +++ b/src/content-pipelines/state/copilot-cli.sha @@ -1 +1 @@ -d5de6fff1643c40899009b7caf57ce10f9ec6d8b +0a6e6489329eccb43213166dd5eb8621e877b1a5