diff --git a/assets/images/help/copilot/copilot-sdk/azure-managed-identity-diagram.png b/assets/images/help/copilot/copilot-sdk/azure-managed-identity-diagram.png new file mode 100644 index 000000000000..b9c34d94a0a7 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/azure-managed-identity-diagram.png differ diff --git a/assets/images/help/copilot/copilot-sdk/bundled-cli-authentication-strategies.png b/assets/images/help/copilot/copilot-sdk/bundled-cli-authentication-strategies.png new file mode 100644 index 000000000000..1a838172790a Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/bundled-cli-authentication-strategies.png differ diff --git a/assets/images/help/copilot/copilot-sdk/scaling-container-deployments.png b/assets/images/help/copilot/copilot-sdk/scaling-container-deployments.png new file mode 100644 index 000000000000..73c1f491f6d7 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/scaling-container-deployments.png differ diff --git a/assets/images/help/copilot/copilot-sdk/scaling-core-concepts.png b/assets/images/help/copilot/copilot-sdk/scaling-core-concepts.png new file mode 100644 index 000000000000..71ade9846fbe Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/scaling-core-concepts.png differ diff --git a/assets/images/help/copilot/copilot-sdk/scaling-ephemeral-vs-persistent-sessions.png b/assets/images/help/copilot/copilot-sdk/scaling-ephemeral-vs-persistent-sessions.png new file mode 100644 index 000000000000..8a9faa5814f6 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/scaling-ephemeral-vs-persistent-sessions.png differ diff --git a/assets/images/help/copilot/copilot-sdk/scaling-isolated-cli-pattern.png b/assets/images/help/copilot/copilot-sdk/scaling-isolated-cli-pattern.png new file mode 100644 index 000000000000..c83d29b58b23 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/scaling-isolated-cli-pattern.png differ diff --git a/assets/images/help/copilot/copilot-sdk/scaling-multiple-cli-servers.png b/assets/images/help/copilot/copilot-sdk/scaling-multiple-cli-servers.png new file mode 100644 index 000000000000..a8920682fd15 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/scaling-multiple-cli-servers.png differ diff --git a/assets/images/help/copilot/copilot-sdk/scaling-shared-cli-pattern.png b/assets/images/help/copilot/copilot-sdk/scaling-shared-cli-pattern.png new file mode 100644 index 000000000000..bba78717bd06 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/scaling-shared-cli-pattern.png differ diff --git a/assets/images/help/copilot/copilot-sdk/scaling-shared-sessions.png b/assets/images/help/copilot/copilot-sdk/scaling-shared-sessions.png new file mode 100644 index 000000000000..2b1e355e68a5 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/scaling-shared-sessions.png differ diff --git a/assets/images/help/copilot/copilot-sdk/scaling-stick-and-shared-sessions.png b/assets/images/help/copilot/copilot-sdk/scaling-stick-and-shared-sessions.png new file mode 100644 index 000000000000..02cb6f1991fd Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/scaling-stick-and-shared-sessions.png differ diff --git a/assets/images/help/copilot/copilot-sdk/scaling-vertical-scaling.png b/assets/images/help/copilot/copilot-sdk/scaling-vertical-scaling.png new file mode 100644 index 000000000000..0562834d1af7 Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/scaling-vertical-scaling.png differ diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-advanced-setup-for-code-scanning.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configuring-advanced-setup-for-code-scanning.md similarity index 98% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-advanced-setup-for-code-scanning.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configuring-advanced-setup-for-code-scanning.md index 8f98b00fe7be..c19dd0ed34ea 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-advanced-setup-for-code-scanning.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configuring-advanced-setup-for-code-scanning.md @@ -8,6 +8,7 @@ redirect_from: - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-advanced-setup-for-code-scanning - /code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning - /code-security/code-scanning/creating-an-advanced-setup-for-code-scanning + - /code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-advanced-setup-for-code-scanning versions: fpt: '*' ghes: '*' diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning.md similarity index 98% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning.md index 5db6f3f54727..ede625d63b3c 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning.md @@ -15,6 +15,7 @@ redirect_from: - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning - /code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning + - /code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning permissions: '{% data reusables.permissions.security-repo-enable %}' product: '{% data reusables.gated-features.code-scanning %}' versions: diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/index.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/index.md similarity index 85% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/index.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/index.md index 980c0cf33b1f..0ae7be2fadc5 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/index.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/index.md @@ -11,5 +11,6 @@ children: - /configuring-advanced-setup-for-code-scanning redirect_from: - /code-security/code-scanning/enabling-code-scanning + - /code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning --- diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/index.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/index.md similarity index 54% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/index.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/index.md index 1ba01263e98a..79d44cbab391 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/index.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/index.md @@ -1,6 +1,6 @@ --- -title: Scan code for vulnerabilities -intro: Scan your code for vulnerabilities by configuring code scanning, managing configurations, running scans locally or in your editor, integrating with existing tools, and troubleshooting issues. +title: Find and fix code vulnerabilities +intro: Identify vulnerabilities in your code by configuring and managing code scanning. versions: fpt: '*' ghes: '*' @@ -8,6 +8,7 @@ versions: contentType: how-tos redirect_from: - /code-security/code-scanning + - /code-security/how-tos/scan-code-for-vulnerabilities children: - /configure-code-scanning - /manage-your-configuration @@ -15,4 +16,3 @@ children: - /scan-from-vs-code - /integrate-with-existing-tools --- - diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/index.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/index.md similarity index 90% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/index.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/index.md index bf7f3118a802..3111c90120c8 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/index.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/index.md @@ -11,7 +11,9 @@ redirect_from: - /github/finding-security-vulnerabilities-and-errors-in-your-code/managing-results-from-code-scanning - /github/finding-security-vulnerabilities-and-errors-in-your-code/integrating-with-code-scanning - /code-security/secure-coding/integrating-with-code-scanning + - /code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools children: - /using-code-scanning-with-your-existing-ci-system - /uploading-a-sarif-file-to-github --- + diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github.md similarity index 99% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github.md index ca3dd96980f1..25a7201ab064 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github.md @@ -11,6 +11,7 @@ redirect_from: - /code-security/secure-coding/integrating-with-code-scanning/uploading-a-sarif-file-to-github - /github/finding-security-vulnerabilities-and-errors-in-your-code/integrating-with-code-scanning/uploading-a-sarif-file-to-github - /code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github + - /code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github versions: fpt: '*' ghes: '*' diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/using-code-scanning-with-your-existing-ci-system.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/using-code-scanning-with-your-existing-ci-system.md similarity index 97% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/using-code-scanning-with-your-existing-ci-system.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/using-code-scanning-with-your-existing-ci-system.md index b0250edaf642..72786618096b 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/using-code-scanning-with-your-existing-ci-system.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/using-code-scanning-with-your-existing-ci-system.md @@ -9,6 +9,7 @@ redirect_from: - /code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system - /code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system - /code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system + - /code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/using-code-scanning-with-your-existing-ci-system versions: fpt: '*' ghes: '*' diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/codeql-code-scanning-for-compiled-languages.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/codeql-code-scanning-for-compiled-languages.md similarity index 98% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/codeql-code-scanning-for-compiled-languages.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/codeql-code-scanning-for-compiled-languages.md index 54b693f5e3a3..a8125319731c 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/codeql-code-scanning-for-compiled-languages.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/codeql-code-scanning-for-compiled-languages.md @@ -14,6 +14,7 @@ redirect_from: - /github/finding-security-vulnerabilities-and-errors-in-your-code/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-the-codeql-workflow-for-compiled-languages - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/codeql-code-scanning-for-compiled-languages - /code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages + - /code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/codeql-code-scanning-for-compiled-languages versions: fpt: '*' ghes: '*' diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/configuring-larger-runners-for-default-setup.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/configuring-larger-runners-for-default-setup.md similarity index 97% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/configuring-larger-runners-for-default-setup.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/configuring-larger-runners-for-default-setup.md index ca63c9cd99a9..c3b56408b538 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/configuring-larger-runners-for-default-setup.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/configuring-larger-runners-for-default-setup.md @@ -7,6 +7,7 @@ versions: feature: default-setup-larger-runners redirect_from: - /code-security/code-scanning/managing-your-code-scanning-configuration/configuring-larger-runners-for-default-setup + - /code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/configuring-larger-runners-for-default-setup contentType: how-tos category: - Find and fix code vulnerabilities diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md similarity index 98% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md index c1b3ef2d6809..bd2ab3e6b4e7 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md @@ -9,6 +9,7 @@ versions: ghec: '*' redirect_from: - /code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup + - /code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup contentType: how-tos category: - Find and fix code vulnerabilities diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/index.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/index.md similarity index 88% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/index.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/index.md index 41b77bc95541..277faaa628f3 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/index.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/index.md @@ -8,6 +8,7 @@ versions: contentType: how-tos redirect_from: - /code-security/code-scanning/managing-your-code-scanning-configuration + - /code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration children: - /editing-your-configuration-of-default-setup - /use-the-tools-status-page-for-code-scanning @@ -15,3 +16,4 @@ children: - /configuring-larger-runners-for-default-setup - /codeql-code-scanning-for-compiled-languages --- + diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/set-code-scanning-merge-protection.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/set-code-scanning-merge-protection.md similarity index 89% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/set-code-scanning-merge-protection.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/set-code-scanning-merge-protection.md index 0d600ec4e929..7a19c57e2a58 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/set-code-scanning-merge-protection.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/set-code-scanning-merge-protection.md @@ -1,7 +1,7 @@ --- title: Set code scanning merge protection shortTitle: Set merge protection -intro: 'Secure your codebase by blocking pull requests that fail {% data variables.product.prodname_code_scanning %} checks.' +intro: Secure your codebase by blocking pull requests that fail {% data variables.product.prodname_code_scanning %} checks. permissions: '{% data reusables.permissions.security-org-enable %}' product: '{% data reusables.gated-features.code-scanning %}' versions: @@ -10,6 +10,7 @@ versions: ghes: '*' redirect_from: - /code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection + - /code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/set-code-scanning-merge-protection contentType: how-tos category: - Find and fix code vulnerabilities diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning.md similarity index 95% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning.md index 331f43e8c158..ce3440279a87 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning.md @@ -1,7 +1,7 @@ --- title: Use the tool status page for code scanning shortTitle: Use tool status page -intro: 'View real-time tool status, identify configuration problems, and download reports to keep your {% data variables.product.prodname_code_scanning %} analysis running smoothly.' +intro: View real-time tool status, identify configuration problems, and download reports to keep your {% data variables.product.prodname_code_scanning %} analysis running smoothly. permissions: '{% data reusables.permissions.code-scanning-all-alerts %}' product: '{% data reusables.gated-features.code-scanning %}' allowTitleToDifferFromFilename: true @@ -13,6 +13,7 @@ redirect_from: - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-the-tool-status-page - /code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page - /code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/about-the-tool-status-page + - /code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning contentType: how-tos category: - Find and fix code vulnerabilities diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/check-out-source-code.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/check-out-source-code.md similarity index 97% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/check-out-source-code.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/check-out-source-code.md index 4894c6c04e92..a0eb4e5e54d0 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/check-out-source-code.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/check-out-source-code.md @@ -10,6 +10,8 @@ contentType: how-tos shortTitle: Check out source code category: - Customize vulnerability detection with CodeQL +redirect_from: + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/check-out-source-code --- Some users prefer working with {% data variables.product.prodname_codeql %} query sources directly in order to work on or contribute to open source shared queries. diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/creating-database-bundle-for-troubleshooting.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/creating-database-bundle-for-troubleshooting.md similarity index 94% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/creating-database-bundle-for-troubleshooting.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/creating-database-bundle-for-troubleshooting.md index 50abee26130e..b5eb0d231ceb 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/creating-database-bundle-for-troubleshooting.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/creating-database-bundle-for-troubleshooting.md @@ -10,6 +10,7 @@ versions: ghec: '*' redirect_from: - /code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-database-bundle-for-troubleshooting + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/creating-database-bundle-for-troubleshooting contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/download-databases.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/download-databases.md similarity index 95% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/download-databases.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/download-databases.md index 37f174c6e7ff..ded6b38a2faf 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/download-databases.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/download-databases.md @@ -10,6 +10,8 @@ versions: contentType: how-tos category: - Customize vulnerability detection with CodeQL +redirect_from: + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/download-databases --- {% data variables.product.github %} stores {% data variables.product.prodname_codeql %} databases for over 200,000 repositories on {% data variables.product.prodname_dotcom_the_website %}, which you can download using the REST API. The list of repositories is constantly growing and evolving to make sure that it includes the most interesting codebases for security research. diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/index.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/index.md similarity index 89% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/index.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/index.md index ed828c30e443..cd6900329552 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/index.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/index.md @@ -20,4 +20,6 @@ redirect_from: - /code-security/codeql-cli/using-the-codeql-cli - /code-security/codeql-cli/getting-started-with-the-codeql-cli - /code-security/codeql-cli + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line --- + diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/publish-and-use-packs.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/publish-and-use-packs.md similarity index 99% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/publish-and-use-packs.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/publish-and-use-packs.md index e0bd230368f3..3a25d7398768 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/publish-and-use-packs.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/publish-and-use-packs.md @@ -12,6 +12,7 @@ redirect_from: - /code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs - /code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs - /code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/publish-and-use-packs contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/setting-up-the-codeql-cli.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/setting-up-the-codeql-cli.md similarity index 98% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/setting-up-the-codeql-cli.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/setting-up-the-codeql-cli.md index 95e964bf686d..0d39cfbf79b2 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/setting-up-the-codeql-cli.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/setting-up-the-codeql-cli.md @@ -14,6 +14,7 @@ redirect_from: - /code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system - /code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system - /code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/setting-up-the-codeql-cli contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/specifying-command-options-in-a-codeql-configuration-file.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/specifying-command-options-in-a-codeql-configuration-file.md similarity index 95% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/specifying-command-options-in-a-codeql-configuration-file.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/specifying-command-options-in-a-codeql-configuration-file.md index 9e2f77872d33..5f4493122c01 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/specifying-command-options-in-a-codeql-configuration-file.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/specifying-command-options-in-a-codeql-configuration-file.md @@ -11,6 +11,7 @@ redirect_from: - /code-security/codeql-cli/specifying-command-options-in-a-codeql-configuration-file - /code-security/codeql-cli/using-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file - /code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/specifying-command-options-in-a-codeql-configuration-file contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/testing-custom-queries.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/testing-custom-queries.md similarity index 99% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/testing-custom-queries.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/testing-custom-queries.md index 9c549133c085..36c74425ecff 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/testing-custom-queries.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/testing-custom-queries.md @@ -12,6 +12,7 @@ redirect_from: - /code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries - /code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries - /code-security/tutorials/customize-code-scanning/testing-custom-queries + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/testing-custom-queries contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/testing-query-help-files.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/testing-query-help-files.md similarity index 95% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/testing-query-help-files.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/testing-query-help-files.md index ffca560887d4..33d65044b978 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/testing-query-help-files.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/testing-query-help-files.md @@ -11,6 +11,7 @@ redirect_from: - /code-security/codeql-cli/testing-query-help-files - /code-security/codeql-cli/using-the-codeql-cli/testing-query-help-files - /code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-query-help-files + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/testing-query-help-files contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/write-custom-queries.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/write-custom-queries.md similarity index 97% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/write-custom-queries.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/write-custom-queries.md index a0a05748c6a9..4d610c36f221 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/write-custom-queries.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/write-custom-queries.md @@ -13,6 +13,7 @@ redirect_from: - /code-security/codeql-cli/using-the-codeql-cli/using-custom-queries-with-the-codeql-cli - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/writing-and-sharing-custom-queries-for-the-codeql-cli + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/write-custom-queries contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/accessing-logs.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/accessing-logs.md similarity index 93% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/accessing-logs.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/accessing-logs.md index 0a8c12299e58..39dd224f5859 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/accessing-logs.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/accessing-logs.md @@ -11,6 +11,7 @@ redirect_from: - /code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs - /code-security/how-tos/scan-code-for-vulnerabilities/troubleshooting/troubleshooting-codeql-for-vs-code/accessing-logs - /code-security/reference/code-scanning/codeql/codeql-for-vs-code/accessing-logs + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/accessing-logs contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/configuring-access-to-the-codeql-cli.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/configuring-access-to-the-codeql-cli.md similarity index 95% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/configuring-access-to-the-codeql-cli.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/configuring-access-to-the-codeql-cli.md index f0e7c17381f0..1c1c45ee7d6a 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/configuring-access-to-the-codeql-cli.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/configuring-access-to-the-codeql-cli.md @@ -9,6 +9,7 @@ intro: The {% data variables.product.prodname_codeql %} for {% data variables.pr allowTitleToDifferFromFilename: true redirect_from: - /code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/configuring-access-to-the-codeql-cli contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/creating-a-custom-query.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/creating-a-custom-query.md similarity index 96% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/creating-a-custom-query.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/creating-a-custom-query.md index 15910493febf..e96e95b58f60 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/creating-a-custom-query.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/creating-a-custom-query.md @@ -8,6 +8,7 @@ versions: intro: You can work from a template to write your own code to create a custom query to analyze a specific language. redirect_from: - /code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/creating-a-custom-query + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/creating-a-custom-query contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/customizing-settings.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/customizing-settings.md similarity index 99% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/customizing-settings.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/customizing-settings.md index c83dcafdeaac..32c621c7fc85 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/customizing-settings.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/customizing-settings.md @@ -9,6 +9,7 @@ intro: You can edit the settings for the {% data variables.product.prodname_code redirect_from: - /code-security/codeql-for-vs-code/customizing-settings - /code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/customizing-settings contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/exploring-data-flow-with-path-queries.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/exploring-data-flow-with-path-queries.md similarity index 95% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/exploring-data-flow-with-path-queries.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/exploring-data-flow-with-path-queries.md index e5a06117dde6..c1bfa8eb7b74 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/exploring-data-flow-with-path-queries.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/exploring-data-flow-with-path-queries.md @@ -9,6 +9,7 @@ intro: Detect potential vulnerabilities by running path queries and analyzing yo redirect_from: - /code-security/codeql-for-vs-code/exploring-data-flow-with-path-queries - /code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/exploring-data-flow-with-path-queries contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/exploring-the-structure-of-your-source-code.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/exploring-the-structure-of-your-source-code.md similarity index 94% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/exploring-the-structure-of-your-source-code.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/exploring-the-structure-of-your-source-code.md index 46fd8933b978..68e804c571c0 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/exploring-the-structure-of-your-source-code.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/exploring-the-structure-of-your-source-code.md @@ -9,6 +9,7 @@ intro: Visualize how your code maps to {% data variables.product.prodname_codeql redirect_from: - /code-security/codeql-for-vs-code/exploring-the-structure-of-your-source-code - /code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/exploring-the-structure-of-your-source-code + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/exploring-the-structure-of-your-source-code contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/index.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/index.md similarity index 93% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/index.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/index.md index 1c3730128cae..2fb34372c509 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/index.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/index.md @@ -9,6 +9,7 @@ contentType: how-tos redirect_from: - /code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension - /code-security/codeql-for-vs-code + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code children: - /installing-codeql-for-vs-code - /managing-codeql-databases diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/installing-codeql-for-vs-code.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/installing-codeql-for-vs-code.md similarity index 97% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/installing-codeql-for-vs-code.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/installing-codeql-for-vs-code.md index f04f6e0c615b..2fcb2b3d702b 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/installing-codeql-for-vs-code.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/installing-codeql-for-vs-code.md @@ -12,6 +12,7 @@ redirect_from: - /code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code - /code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code - /code-security/codeql-for-vs-code/setting-up-codeql-in-visual-studio-code + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/installing-codeql-for-vs-code contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/managing-codeql-databases.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/managing-codeql-databases.md similarity index 97% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/managing-codeql-databases.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/managing-codeql-databases.md index 3ce363da3885..fddd485f03ac 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/managing-codeql-databases.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/managing-codeql-databases.md @@ -8,6 +8,7 @@ versions: intro: You can work with {% data variables.product.prodname_codeql %} databases using the extension. redirect_from: - /code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/managing-codeql-databases contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/managing-codeql-packs.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/managing-codeql-packs.md similarity index 97% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/managing-codeql-packs.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/managing-codeql-packs.md index 1468f4718207..f915d8129a19 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/managing-codeql-packs.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/managing-codeql-packs.md @@ -10,6 +10,7 @@ allowTitleToDifferFromFilename: true redirect_from: - /code-security/codeql-for-vs-code/working-with-codeql-packs-in-visual-studio-code - /code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/managing-codeql-packs + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/managing-codeql-packs contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md similarity index 99% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md index cf6539e89349..aeb1e4b6435e 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md @@ -7,6 +7,7 @@ intro: You can run {% data variables.product.prodname_codeql %} queries on a lar redirect_from: - /code-security/codeql-for-vs-code/running-codeql-queries-at-scale-with-mrva - /code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/running-codeql-queries.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/running-codeql-queries.md similarity index 99% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/running-codeql-queries.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/running-codeql-queries.md index 8ddf15dc136b..a10411b5f262 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/running-codeql-queries.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/running-codeql-queries.md @@ -10,6 +10,7 @@ allowTitleToDifferFromFilename: true redirect_from: - /code-security/codeql-for-vs-code/analyzing-your-projects - /code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/running-codeql-queries contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/setting-up-a-codeql-workspace.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/setting-up-a-codeql-workspace.md similarity index 97% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/setting-up-a-codeql-workspace.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/setting-up-a-codeql-workspace.md index 855cd53739a3..8fa1d3f0b0db 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/setting-up-a-codeql-workspace.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/setting-up-a-codeql-workspace.md @@ -9,6 +9,7 @@ intro: When you're working with {% data variables.product.prodname_codeql %}, yo allowTitleToDifferFromFilename: true redirect_from: - /code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/setting-up-a-codeql-workspace + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/setting-up-a-codeql-workspace contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/testing-codeql-queries-in-vs-code.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/testing-codeql-queries-in-vs-code.md similarity index 97% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/testing-codeql-queries-in-vs-code.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/testing-codeql-queries-in-vs-code.md index 284520924414..2157c797b292 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/testing-codeql-queries-in-vs-code.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/testing-codeql-queries-in-vs-code.md @@ -10,6 +10,7 @@ allowTitleToDifferFromFilename: true redirect_from: - /code-security/codeql-for-vs-code/testing-codeql-queries-in-visual-studio-code - /code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/testing-codeql-queries-in-vs-code + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/testing-codeql-queries-in-vs-code contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/using-the-codeql-model-editor.md b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/using-the-codeql-model-editor.md similarity index 99% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/using-the-codeql-model-editor.md rename to content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/using-the-codeql-model-editor.md index bb9d4820a8b6..c210726db3cc 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/using-the-codeql-model-editor.md +++ b/content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/using-the-codeql-model-editor.md @@ -9,6 +9,7 @@ intro: You can view, write, and edit {% data variables.product.prodname_codeql % redirect_from: - /code-security/codeql-for-vs-code/using-the-codeql-model-editor - /code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-vs-code/using-the-codeql-model-editor contentType: how-tos category: - Customize vulnerability detection with CodeQL diff --git a/content/code-security/how-tos/index.md b/content/code-security/how-tos/index.md index 9262ae2c9738..241674135bf6 100644 --- a/content/code-security/how-tos/index.md +++ b/content/code-security/how-tos/index.md @@ -10,10 +10,11 @@ contentType: how-tos children: - /secure-at-scale - /secure-your-secrets - - /scan-code-for-vulnerabilities + - find-and-fix-code-vulnerabilities - secure-your-supply-chain - manage-security-alerts - /maintain-quality-code - /report-and-fix-vulnerabilities - /view-and-interpret-data --- + diff --git a/content/code-security/index.md b/content/code-security/index.md index a23572a96cb5..2aac6cada3d9 100644 --- a/content/code-security/index.md +++ b/content/code-security/index.md @@ -1,7 +1,7 @@ --- title: Security and code quality documentation shortTitle: Security and code quality -intro: Build security and code quality into your {% data variables.product.github %} workflow to secure your software supply chain, prevent data leaks, and automatically find and fix vulnerabilities and code health issues in your codebase. +intro: Build security and code quality into your {% data variables.product.github %} workflow with integrated tooling. redirect_from: - /code-security/guides introLinks: @@ -48,4 +48,3 @@ children: - /tutorials - /responsible-use --- - diff --git a/content/copilot/how-tos/copilot-sdk/index.md b/content/copilot/how-tos/copilot-sdk/index.md index ed2b37f992f0..b0149466bb81 100644 --- a/content/copilot/how-tos/copilot-sdk/index.md +++ b/content/copilot/how-tos/copilot-sdk/index.md @@ -6,9 +6,11 @@ versions: feature: copilot children: - /sdk-getting-started + - /set-up-copilot-sdk - /authenticate-copilot-sdk - /use-copilot-sdk - /use-hooks - /observability + - /troubleshooting contentType: how-tos --- diff --git a/content/copilot/how-tos/copilot-sdk/observability/opentelemetry.md b/content/copilot/how-tos/copilot-sdk/observability/opentelemetry.md index ae63fb4aa904..5dd098536f25 100644 --- a/content/copilot/how-tos/copilot-sdk/observability/opentelemetry.md +++ b/content/copilot/how-tos/copilot-sdk/observability/opentelemetry.md @@ -14,7 +14,7 @@ category: {% data variables.copilot.copilot_sdk %} has built-in support for configuring OpenTelemetry on the CLI process and propagating W3C Trace Context between the SDK and CLI. -For examples in Python, Go, and .NET, see the `github/copilot-sdk` [repository](https://github.com/github/copilot-sdk/blob/main/docs/observability/opentelemetry.md). +For examples in Python, Go, and .NET, see the [`github/copilot-sdk` repository](https://github.com/github/copilot-sdk/blob/main/docs/observability/opentelemetry.md). ## Built-in telemetry support @@ -47,7 +47,7 @@ const client = new CopilotClient({ The SDK can propagate W3C Trace Context (`traceparent`/`tracestate`) on JSON-RPC payloads so that your application's spans and the CLI's spans are linked in one distributed trace. This is useful when, for example, you want to show the SDK call as a child of your request-handling span. -For a detailed sequence diagram of the session flow, see the `github/copilot-sdk` [repository](https://github.com/github/copilot-sdk/blob/main/docs/observability/opentelemetry.md). +For a detailed sequence diagram of the session flow, see the [`github/copilot-sdk` repository](https://github.com/github/copilot-sdk/blob/main/docs/observability/opentelemetry.md). ### SDK to CLI (outbound) diff --git a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/azure-managed-identity.md b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/azure-managed-identity.md new file mode 100644 index 000000000000..45bc84f51bf7 --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/azure-managed-identity.md @@ -0,0 +1,222 @@ +--- +title: Using Azure Managed Identity with Copilot SDK +shortTitle: Azure Managed Identity +intro: Use Azure Managed Identity (Entra ID) to authenticate {% data variables.copilot.copilot_sdk %} with Azure AI Foundry models instead of static API keys. +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +--- + +{% data reusables.copilot.copilot-sdk.release-state-note %} + +Since Azure deployments often use **Managed Identity** (Entra ID) instead of long-lived keys, you need to take extra steps to use BYOK mode in {% data variables.copilot.copilot_sdk_short %}. Because the SDK doesn't natively support Entra ID authentication, you can use a short-lived bearer token via the provider configuration's bearer token field (`bearer_token` in Python, `bearerToken` in Node.js / TypeScript and .NET). + +This guide shows how to use `DefaultAzureCredential` from the [Azure Identity](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential) library to authenticate with Azure AI Foundry models through {% data variables.copilot.copilot_sdk_short %}. + +## How it works + +Azure AI Foundry's OpenAI-compatible endpoint accepts bearer tokens from Entra ID in place of static API keys. The pattern is: + +1. Use `DefaultAzureCredential` to obtain a token for the `https://cognitiveservices.azure.com/.default` scope. +1. Pass the token using the bearer token field in the BYOK provider configuration (`bearer_token` in Python, `bearerToken` in Node.js / TypeScript and .NET). +1. Refresh the token before it expires. Tokens are typically valid for about one hour. + +![Diagram showing the authentication flow for Azure Managed Identity with the Copilot SDK.](/assets/images/help/copilot/copilot-sdk/azure-managed-identity-diagram.png) + +## Prerequisites + +* An Azure subscription with an Azure AI Foundry resource deployed. +* The Azure Identity library installed (`azure-identity` for Python, `@azure/identity` for Node.js, or `Azure.Identity` for .NET). +* {% data variables.copilot.copilot_sdk_short %} installed. For more information, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started). + +## Python example + +### Install dependencies + +```shell +pip install github-copilot-sdk azure-identity +``` + +### Basic usage + +```python +import asyncio +import os + +from azure.identity import DefaultAzureCredential +from copilot import CopilotClient, PermissionHandler + +COGNITIVE_SERVICES_SCOPE = "https://cognitiveservices.azure.com/.default" + + +async def main(): + # Get a token using Managed Identity, Azure CLI, or other credential chain + credential = DefaultAzureCredential() + token = credential.get_token(COGNITIVE_SERVICES_SCOPE).token + + foundry_url = os.environ["AZURE_AI_FOUNDRY_RESOURCE_URL"] + + client = CopilotClient() + await client.start() + + session = await client.create_session( + on_permission_request=PermissionHandler.approve_all, + model="gpt-4.1", + provider={ + "type": "openai", + "base_url": f"{foundry_url.rstrip('/')}/openai/v1/", + "bearer_token": token, # Short-lived bearer token + "wire_api": "responses", + }, + ) + + response = await session.send_and_wait({"prompt": "Hello from Managed Identity!"}) + print(response.data.content) + + await client.stop() + + +asyncio.run(main()) +``` + +Replace `AZURE_AI_FOUNDRY_RESOURCE_URL` with the environment variable holding your Azure AI Foundry resource URL (for example, `https://myresource.openai.azure.com`). + +### Token refresh for long-running applications + +Bearer tokens expire after approximately one hour. For servers or long-running agents, refresh the token before creating each session: + +```python +from azure.identity import DefaultAzureCredential +from copilot import CopilotClient, PermissionHandler + +COGNITIVE_SERVICES_SCOPE = "https://cognitiveservices.azure.com/.default" + + +class ManagedIdentityCopilotAgent: + """Copilot agent that refreshes Entra ID tokens for Azure AI Foundry.""" + + def __init__(self, foundry_url: str, model: str = "gpt-4.1"): + self.foundry_url = foundry_url.rstrip("/") + self.model = model + self.credential = DefaultAzureCredential() + self.client = CopilotClient() + + def _get_provider_config(self) -> dict: + """Build a provider config dict with a fresh bearer token.""" + token = self.credential.get_token(COGNITIVE_SERVICES_SCOPE).token + return { + "type": "openai", + "base_url": f"{self.foundry_url}/openai/v1/", + "bearer_token": token, + "wire_api": "responses", + } + + async def chat(self, prompt: str) -> str: + """Send a prompt and return the response text.""" + # Fresh token for each session + provider = self._get_provider_config() + session = await self.client.create_session( + on_permission_request=PermissionHandler.approve_all, + model=self.model, + provider=provider, + ) + + response = await session.send_and_wait({"prompt": prompt}) + await session.disconnect() + + return response.data.content if response else "" +``` + +## Node.js / TypeScript example + +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { CopilotClient } from "@github/copilot-sdk"; + +const credential = new DefaultAzureCredential(); +const tokenResponse = await credential.getToken( + "https://cognitiveservices.azure.com/.default" +); + +const client = new CopilotClient(); + +const session = await client.createSession({ + model: "gpt-4.1", + provider: { + type: "openai", + baseUrl: `${process.env.AZURE_AI_FOUNDRY_RESOURCE_URL}/openai/v1/`, + bearerToken: tokenResponse.token, + wireApi: "responses", + }, +}); + +const response = await session.sendAndWait({ prompt: "Hello!" }); +console.log(response?.data.content); + +await client.stop(); +``` + +## .NET example + +```csharp +using Azure.Identity; +using GitHub.Copilot; + +var credential = new DefaultAzureCredential(); +var token = await credential.GetTokenAsync( + new Azure.Core.TokenRequestContext( + new[] { "https://cognitiveservices.azure.com/.default" })); + +await using var client = new CopilotClient(); +var foundryUrl = Environment.GetEnvironmentVariable("AZURE_AI_FOUNDRY_RESOURCE_URL"); + +await using var session = await client.CreateSessionAsync(new SessionConfig +{ + Model = "gpt-4.1", + Provider = new ProviderConfig + { + Type = "openai", + BaseUrl = $"{foundryUrl!.TrimEnd('/')}/openai/v1/", + BearerToken = token.Token, + WireApi = "responses", + }, +}); + +var response = await session.SendAndWaitAsync( + new MessageOptions { Prompt = "Hello from Managed Identity!" }); +Console.WriteLine(response?.Data.Content); +``` + +## Environment configuration + +The following environment variable is required: + +| Variable | Description | Example | +|---|---|---| +| `AZURE_AI_FOUNDRY_RESOURCE_URL` | Your Azure AI Foundry resource URL | `https://myresource.openai.azure.com` | + +No API key environment variable is needed—authentication is handled by `DefaultAzureCredential`, which automatically supports: + +* **Managed Identity** (system-assigned or user-assigned) for Azure-hosted apps. +* **Azure CLI** (`az login`) for local development. +* **Environment variables** (`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`) for service principals. +* **Workload Identity** for Kubernetes. + +For the full credential chain, see the [DefaultAzureCredential documentation](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential). + +## When to use this pattern + +| Scenario | Recommendation | +|---|---| +| Azure-hosted app with Managed Identity | Use this pattern. | +| App with existing Azure AD service principal | Use this pattern. | +| Local development with `az login` | Use this pattern. | +| Non-Azure environment with static API key | Use standard BYOK. For more information, see [BYOK](https://github.com/github/copilot-sdk/blob/main/docs/auth/byok.md) in the `github/copilot-sdk` repository. | +| {% data variables.product.prodname_copilot %} subscription available | Use GitHub OAuth. For more information, see [GitHub OAuth](https://github.com/github/copilot-sdk/blob/main/docs/setup/github-oauth.md) in the `github/copilot-sdk` repository. | + +## Further reading + +* For static API key configuration, see [BYOK](https://github.com/github/copilot-sdk/blob/main/docs/auth/byok.md) in the `github/copilot-sdk` repository. +* For server-side deployment, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services). +* For Azure Identity library documentation, see [Azure Identity client library overview](https://learn.microsoft.com/python/api/overview/azure/identity-readme). diff --git a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services.md b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services.md new file mode 100644 index 000000000000..3b083e9bc65f --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services.md @@ -0,0 +1,339 @@ +--- +title: Setting up Copilot SDK for backend services +shortTitle: Backend services +intro: Run {% data variables.copilot.copilot_sdk %} in server-side applications such as APIs, web backends, microservices, and background workers. +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +--- + +{% data reusables.copilot.copilot-sdk.release-state-note %} + +The CLI runs as a headless server that your backend code connects to over the network. + +**Best for:** Web app backends, API services, internal tools, CI/CD integrations, any server-side workload. + +## How it works + +Instead of the SDK spawning a CLI child process, you run the CLI independently in **headless server mode**. Your backend connects to it over TCP using the `cliUrl` option. For detailed diagrams of the headless server architecture and how it compares to the default auto-managed CLI, see the `github/copilot-sdk` [repository](https://github.com/github/copilot-sdk/blob/main/docs/setup/backend-services.md#how-it-works). + +Key characteristics: + +* The CLI runs as a persistent server process, not spawned per request. +* The SDK connects over TCP—the CLI and app can run in different containers. +* Multiple SDK clients can share one CLI server. +* Works with any authentication method ({% data variables.product.github %} tokens, environment variables, BYOK). + +## Step 1: Start the CLI in headless mode + +Run the CLI as a background server. + +```shell +# Start with a specific port +copilot --headless --port 4321 + +# Or let it pick a random port (prints the URL) +copilot --headless +# Output: Listening on http://localhost:52431 +``` + +For production, run it as a system service or in a container: + +```shell +# Docker +docker run -d --name copilot-cli \ + -p 4321:4321 \ + -e COPILOT_GITHUB_TOKEN="$TOKEN" \ + ghcr.io/github/copilot-cli:latest \ + --headless --port 4321 +``` + +```shell +# systemd +[Service] +ExecStart=/usr/local/bin/copilot --headless --port 4321 +Environment=COPILOT_GITHUB_TOKEN=YOUR-GITHUB-TOKEN +Restart=always +``` + +## Step 2: Connect the SDK + +### Node.js / TypeScript + +```typescript +import { CopilotClient } from "@github/copilot-sdk"; + +const client = new CopilotClient({ + cliUrl: "localhost:4321", +}); + +const session = await client.createSession({ + sessionId: `user-${userId}-${Date.now()}`, + model: "gpt-4.1", +}); + +const response = await session.sendAndWait({ prompt: req.body.message }); +res.json({ content: response?.data.content }); +``` + +### Python + +```python +from copilot import CopilotClient + +client = CopilotClient({ + "cli_url": "localhost:4321", +}) +await client.start() + +session = await client.create_session({ + "session_id": f"user-{user_id}-{int(time.time())}", + "model": "gpt-4.1", +}) + +response = await session.send_and_wait({"prompt": message}) +``` + +### Go + +```golang +client := copilot.NewClient(&copilot.ClientOptions{ + CLIUrl: "localhost:4321", +}) +client.Start(ctx) +defer client.Stop() + +session, _ := client.CreateSession(ctx, &copilot.SessionConfig{ + SessionID: fmt.Sprintf("user-%s-%d", userID, time.Now().Unix()), + Model: "gpt-4.1", +}) + +response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: message}) +``` + +### .NET + +```csharp +var client = new CopilotClient(new CopilotClientOptions +{ + CliUrl = "localhost:4321", + UseStdio = false, +}); + +await using var session = await client.CreateSessionAsync(new SessionConfig +{ + SessionId = $"user-{userId}-{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}", + Model = "gpt-4.1", +}); + +var response = await session.SendAndWaitAsync( + new MessageOptions { Prompt = message }); +``` + +## Authentication for backend services + +### Environment variable tokens + +The simplest approach—set a token on the CLI server: + +```shell +# All requests use this token +export COPILOT_GITHUB_TOKEN="YOUR-SERVICE-ACCOUNT-TOKEN" +copilot --headless --port 4321 +``` + +Replace `YOUR-SERVICE-ACCOUNT-TOKEN` with your {% data variables.product.github %} {% data variables.product.pat_generic %} or OAuth token for the service account. + +### Per-user tokens (OAuth) + +Pass individual user tokens when creating sessions: + +```typescript +// Your API receives user tokens from your auth layer +app.post("/chat", authMiddleware, async (req, res) => { + const client = new CopilotClient({ + cliUrl: "localhost:4321", + githubToken: req.user.githubToken, + useLoggedInUser: false, + }); + + const session = await client.createSession({ + sessionId: `user-${req.user.id}-chat`, + model: "gpt-4.1", + }); + + const response = await session.sendAndWait({ + prompt: req.body.message, + }); + + res.json({ content: response?.data.content }); +}); +``` + +### BYOK (no {% data variables.product.github %} authentication) + +Use your own API keys for the model provider: + +```typescript +const client = new CopilotClient({ + cliUrl: "localhost:4321", +}); + +const session = await client.createSession({ + model: "gpt-4.1", + provider: { + type: "openai", + baseUrl: "https://api.openai.com/v1", + apiKey: process.env.OPENAI_API_KEY, + }, +}); +``` + +## Common backend patterns + +### Web API with Express + +```typescript +import express from "express"; +import { CopilotClient } from "@github/copilot-sdk"; + +const app = express(); +app.use(express.json()); + +// Single shared CLI connection +const client = new CopilotClient({ + cliUrl: process.env.CLI_URL || "localhost:4321", +}); + +app.post("/api/chat", async (req, res) => { + const { sessionId, message } = req.body; + + // Create or resume session + let session; + try { + session = await client.resumeSession(sessionId); + } catch { + session = await client.createSession({ + sessionId, + model: "gpt-4.1", + }); + } + + const response = await session.sendAndWait({ prompt: message }); + res.json({ + sessionId, + content: response?.data.content, + }); +}); + +app.listen(3000); +``` + +### Background worker + +```typescript +import { CopilotClient } from "@github/copilot-sdk"; + +const client = new CopilotClient({ + cliUrl: process.env.CLI_URL || "localhost:4321", +}); + +// Process jobs from a queue +async function processJob(job: Job) { + const session = await client.createSession({ + sessionId: `job-${job.id}`, + model: "gpt-4.1", + }); + + const response = await session.sendAndWait({ + prompt: job.prompt, + }); + + await saveResult(job.id, response?.data.content); + await session.disconnect(); // Clean up after job completes +} +``` + +### Docker Compose deployment + +```yaml +version: "3.8" + +services: + copilot-cli: + image: ghcr.io/github/copilot-cli:latest + command: ["--headless", "--port", "4321"] + environment: + - COPILOT_GITHUB_TOKEN=${COPILOT_GITHUB_TOKEN} + ports: + - "4321:4321" + restart: always + volumes: + - session-data:/root/.copilot/session-state + + api: + build: . + environment: + - CLI_URL=copilot-cli:4321 + depends_on: + - copilot-cli + ports: + - "3000:3000" + +volumes: + session-data: +``` + +## Health checks + +Monitor the CLI server's health: + +```typescript +// Periodic health check +async function checkCLIHealth(): Promise { + try { + const status = await client.getStatus(); + return status !== undefined; + } catch { + return false; + } +} +``` + +## Session cleanup + +Backend services should actively clean up sessions to avoid resource leaks: + +```typescript +// Clean up expired sessions periodically +async function cleanupSessions(maxAgeMs: number) { + const sessions = await client.listSessions(); + const now = Date.now(); + + for (const session of sessions) { + const age = now - new Date(session.createdAt).getTime(); + if (age > maxAgeMs) { + await client.deleteSession(session.sessionId); + } + } +} + +// Run every hour +setInterval(() => cleanupSessions(24 * 60 * 60 * 1000), 60 * 60 * 1000); +``` + +## Limitations + +| Limitation | Details | +|---|---| +| **Single CLI server = single point of failure** | Consider high-availability patterns for production deployments. | +| **No built-in auth between SDK and CLI** | Secure the network path (same host, VPC, etc.). | +| **Session state on local disk** | Mount persistent storage for container restarts. | +| **30-minute idle timeout** | Sessions without activity are automatically cleaned up. | + +## Next steps + +* For installation and your first message, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started). +* For information about resuming sessions across restarts, see [Session Persistence](https://github.com/github/copilot-sdk/blob/main/docs/features/session-persistence.md) in the `github/copilot-sdk` repository. +* For information about adding user authentication, see [GitHub OAuth](https://github.com/github/copilot-sdk/blob/main/docs/setup/github-oauth.md) in the `github/copilot-sdk` repository. diff --git a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli.md b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli.md new file mode 100644 index 000000000000..ffaaf4d55b52 --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli.md @@ -0,0 +1,255 @@ +--- +title: Using a bundled CLI with Copilot SDK +shortTitle: Bundled CLI +intro: Package {% data variables.copilot.copilot_cli_short %} alongside your application so that users do not need to install or configure anything separately. +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +--- + +{% data reusables.copilot.copilot-sdk.release-state-note %} + +Ship {% data variables.copilot.copilot_cli_short %} as part of your application so your users can get started with no additional setup. + +**Best for:** Desktop apps, standalone tools, Electron apps, and distributable CLI utilities. + +## How it works + +Instead of relying on a globally installed CLI, you include the CLI binary in your application bundle. The SDK points to your bundled copy via the `cliPath` option. Key characteristics are: + +* The CLI binary ships with your app—no separate install is needed. +* You control the exact CLI version your app uses. +* Users authenticate through your app, environment variables, or BYOK. +* Sessions are managed per user on their machine. + +## Setup + +### Step 1: Include the CLI in your project + +The CLI is distributed as part of the `@github/copilot` npm package. + +```shell +npm install @github/copilot +``` + +### Step 2: Point the SDK to your bundled CLI + +#### Node.js / TypeScript + +```typescript +import { CopilotClient } from "@github/copilot-sdk"; +import path from "path"; + +const client = new CopilotClient({ + // Point to the CLI binary in your app bundle + cliPath: path.join(__dirname, "vendor", "copilot"), +}); + +const session = await client.createSession({ model: "gpt-4.1" }); +const response = await session.sendAndWait({ prompt: "Hello!" }); +console.log(response?.data.content); + +await client.stop(); +``` + +#### Python + +```python +from copilot import CopilotClient, PermissionHandler +from pathlib import Path + +client = CopilotClient({ + "cli_path": str(Path(__file__).parent / "vendor" / "copilot"), +}) +await client.start() + +session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1") +response = await session.send_and_wait({"prompt": "Hello!"}) +print(response.data.content) + +await client.stop() +``` + +#### Go + +```golang +client := copilot.NewClient(&copilot.ClientOptions{ + CLIPath: "./vendor/copilot", +}) +if err := client.Start(ctx); err != nil { + log.Fatal(err) +} +defer client.Stop() + +session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"}) +response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"}) +fmt.Println(*response.Data.Content) +``` + +#### .NET + +```csharp +var client = new CopilotClient(new CopilotClientOptions +{ + CliPath = Path.Combine(AppContext.BaseDirectory, "vendor", "copilot"), +}); + +await using var session = await client.CreateSessionAsync( + new SessionConfig { Model = "gpt-4.1" }); + +var response = await session.SendAndWaitAsync( + new MessageOptions { Prompt = "Hello!" }); +Console.WriteLine(response?.Data.Content); +``` + +## Authentication strategies + +When bundling the CLI, you need to decide how your users will authenticate. The following diagram illustrates common patterns. + +![Diagram showing authentication strategy options for a bundled CLI deployment.](/assets/images/help/copilot/copilot-sdk/bundled-cli-authentication-strategies.png) + +### Option A: User's signed-in credentials (simplest) + +The user signs in to the CLI once, and your bundled app uses those credentials. No extra code needed—this is the default behavior. + +```typescript +const client = new CopilotClient({ + cliPath: path.join(__dirname, "vendor", "copilot"), + // Default: uses signed-in user credentials +}); +``` + +### Option B: Token via environment variable + +Set a token programmatically or instruct users to set one before starting your app: + +```typescript +const client = new CopilotClient({ + cliPath: path.join(__dirname, "vendor", "copilot"), + env: { + COPILOT_GITHUB_TOKEN: getUserToken(), + }, +}); +``` + +Replace `getUserToken()` with the logic in your app that retrieves the user's {% data variables.product.github %} OAuth token. + +### Option C: BYOK (no {% data variables.product.github %} authentication needed) + +If you manage your own model provider keys, users don't need {% data variables.product.github %} accounts: + +```typescript +const client = new CopilotClient({ + cliPath: path.join(__dirname, "vendor", "copilot"), +}); + +const session = await client.createSession({ + model: "gpt-4.1", + provider: { + type: "openai", + baseUrl: "https://api.openai.com/v1", + apiKey: process.env.OPENAI_API_KEY, + }, +}); +``` + +## Session management + +Bundled apps typically want named sessions so users can resume conversations: + +```typescript +const client = new CopilotClient({ + cliPath: path.join(__dirname, "vendor", "copilot"), +}); + +// Create a session tied to the user's project +const sessionId = `project-${projectName}`; +const session = await client.createSession({ + sessionId, + model: "gpt-4.1", +}); + +// Resume the session in a later run +const resumed = await client.resumeSession(sessionId); +``` + +Session state is stored at `~/.copilot/session-state/SESSION-ID/`, where `SESSION-ID` is the session ID you provided. + +## Distribution patterns + +### Desktop app (Electron, Tauri) + +Include the CLI binary in your app's resources directory: + +```typescript +import { app } from "electron"; +import path from "path"; + +const cliPath = path.join( + app.isPackaged ? process.resourcesPath : __dirname, + "copilot" +); + +const client = new CopilotClient({ cliPath }); +``` + +### CLI tool + +For distributable CLI tools, resolve the path relative to your binary: + +```typescript +import { fileURLToPath } from "url"; +import path from "path"; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const cliPath = path.join(__dirname, "..", "vendor", "copilot"); + +const client = new CopilotClient({ cliPath }); +``` + +## Platform-specific binaries + +When distributing for multiple platforms, include the correct binary for each target: + +```text +my-app/ +├── vendor/ +│ ├── copilot-darwin-arm64 # macOS Apple Silicon +│ ├── copilot-darwin-x64 # macOS Intel +│ ├── copilot-linux-x64 # Linux x64 +│ └── copilot-win-x64.exe # Windows x64 +└── src/ + └── index.ts +``` + +```typescript +import os from "os"; + +function getCLIPath(): string { + const platform = process.platform; // "darwin", "linux", "win32" + const arch = os.arch(); // "arm64", "x64" + const ext = platform === "win32" ? ".exe" : ""; + const name = `copilot-${platform}-${arch}${ext}`; + return path.join(__dirname, "vendor", name); +} + +const client = new CopilotClient({ + cliPath: getCLIPath(), +}); +``` + +## Limitations + +| Limitation | Details | +|---|---| +| **Bundle size** | The CLI binary adds to your app's distribution size. | +| **Updates** | You manage CLI version updates in your release cycle. | +| **Platform builds** | Separate binaries are needed for each OS/architecture. | +| **Single user** | Each bundled CLI instance serves one user. | + +## Next steps + +* For users signing in with {% data variables.product.github %} accounts, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth). +* To run on a server instead of user machines, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services). +* For installation and your first message, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started). diff --git a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/choosing-a-setup-path.md b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/choosing-a-setup-path.md new file mode 100644 index 000000000000..e043af62b5da --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/choosing-a-setup-path.md @@ -0,0 +1,98 @@ +--- +title: Choosing a setup path for Copilot SDK +shortTitle: Choosing a setup path +intro: Find the right setup guide that matches how you plan to use {% data variables.copilot.copilot_sdk_short %}. +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +--- + +{% data reusables.copilot.copilot-sdk.release-state-note %} + +## Architecture overview + +Every {% data variables.copilot.copilot_sdk %} integration follows the same core pattern: your application talks to the SDK, which communicates with {% data variables.copilot.copilot_cli_short %} over JSON-RPC. What changes across setups is where the CLI runs, how users authenticate, and how sessions are managed. + +## Who are you? + +### Hobbyist + +You're building a personal assistant, side project, or experimental app. You want the simplest path to getting Copilot in your code. + +**Start with:** + +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/local-cli)—use the CLI already signed in on your machine. +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli)—package everything into a standalone app. + +### Internal app developer + +You're building tools for your team or company. Users are employees who need to authenticate with their enterprise {% data variables.product.github %} accounts or org memberships. + +**Start with:** + +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth)—let employees sign in with their {% data variables.product.github %} accounts. +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services)—run the SDK in your internal services. + +**If scaling beyond a single server:** + +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/scaling)—handle multiple users and services. + +### App developer (ISV) + +You're building a product for customers. You need to handle authentication for your users—either through {% data variables.product.github %} or by managing identity yourself. + +**Start with:** + +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth)—let customers sign in with {% data variables.product.github %}. +1. [BYOK](https://github.com/github/copilot-sdk/blob/main/docs/auth/byok.md) in the `github/copilot-sdk` repository—manage identity with your own model keys. +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services)—power your product from server-side code. + +**For production:** + +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/scaling)—serve many customers reliably. + +### Platform developer + +You're embedding Copilot into a platform—APIs, developer tools, or infrastructure that other developers build on. You need fine-grained control over sessions, scaling, and multi-tenancy. + +**Start with:** + +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services)—core server-side integration. +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/scaling)—session isolation, horizontal scaling, persistence. + +**Depending on your authentication model:** + +1. [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth)—for {% data variables.product.github %}-authenticated users. +1. [BYOK](https://github.com/github/copilot-sdk/blob/main/docs/auth/byok.md) in the `github/copilot-sdk` repository—for self-managed identity and model access. + +## Decision matrix + +Use this table to find the right guide based on what you need to do. + +| What you need | Guide | +|---|---| +| Simplest possible setup | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/local-cli) | +| Ship a standalone app with Copilot | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli) | +| Users sign in with {% data variables.product.github %} | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth) | +| Use your own model keys (OpenAI, Azure, etc.) | [BYOK](https://github.com/github/copilot-sdk/blob/main/docs/auth/byok.md) in the `github/copilot-sdk` repository | +| Azure BYOK with Managed Identity (no API keys) | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/azure-managed-identity) | +| Run the SDK on a server | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services) | +| Serve multiple users or scale horizontally | [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/scaling) | + +## Prerequisites + +All guides assume you have: + +* **{% data variables.copilot.copilot_cli_short %}** installed. For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli). +* **One of the SDKs** installed: + * Node.js: `npm install @github/copilot-sdk` + * Python: `pip install github-copilot-sdk` + * Go: `go get github.com/github/copilot-sdk/go` + * .NET: `dotnet add package GitHub.Copilot.SDK` + +If you're new to the {% data variables.copilot.copilot_sdk %}, start with [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started) first, then return here for production configuration. + +## Next steps + +Pick the guide that matches your situation from the [decision matrix](#decision-matrix) above, or start with the persona description closest to your role. diff --git a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth.md b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth.md new file mode 100644 index 000000000000..2f57944e05ae --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth.md @@ -0,0 +1,270 @@ +--- +title: Using GitHub OAuth with Copilot SDK +shortTitle: GitHub OAuth +intro: Let users authenticate with their {% data variables.product.github %} accounts to use {% data variables.product.prodname_copilot %} through your application. +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +--- + +{% data reusables.copilot.copilot-sdk.release-state-note %} + +"Connect users to {% data variables.product.prodname_copilot %} by providing {% data variables.product.github %} account authentication directly within your application. + +**Best for:** Multi-user apps, internal tools with organization access control, SaaS products, and apps where users already have {% data variables.product.github %} accounts. + +## How it works + +You create a {% data variables.product.github %} OAuth App (or {% data variables.product.prodname_github_app %}), users authorize it, and you pass their access token to the SDK. {% data variables.product.prodname_copilot_short %} requests are made on behalf of each authenticated user, using their {% data variables.product.prodname_copilot_short %} subscription. For detailed sequence diagrams of this flow and architecture, see the `github/copilot-sdk` [repository](https://github.com/github/copilot-sdk/blob/main/docs/setup/github-oauth.md#how-it-works). + +**Key characteristics:** + +* Each user authenticates with their own {% data variables.product.github %} account. +* {% data variables.product.prodname_copilot_short %} usage is billed to each user's subscription. +* Supports {% data variables.product.github %} organizations and enterprise accounts. +* Your app never handles model API keys—{% data variables.product.github %} manages everything. + +## Step 1: Create a GitHub OAuth App + +1. Go to **{% data variables.product.github %} Settings > Developer Settings > OAuth Apps > New OAuth App**. For organizations, go to **Organization Settings > Developer Settings**. +1. Fill in the following fields: + * **Application name**: Your app's name. + * **Homepage URL**: Your app's URL. + * **Authorization callback URL**: Your OAuth callback endpoint (for example, `https://YOUR-APP.com/auth/callback`). Replace `YOUR-APP.com` with your domain. +1. Note your **Client ID** and generate a **Client Secret**. + +> [!NOTE] +> Both {% data variables.product.prodname_github_apps %} and OAuth Apps work with the SDK. {% data variables.product.prodname_github_apps %} offer finer-grained permissions and are recommended for new projects. OAuth Apps are simpler to set up. The token flow is the same from the SDK's perspective. + +## Step 2: Implement the OAuth flow + +Your application handles the standard {% data variables.product.github %} OAuth flow. The following shows the server-side token exchange: + +```typescript +// Server-side: exchange authorization code for user token +async function handleOAuthCallback(code: string): Promise { + const response = await fetch("https://github.com/login/oauth/access_token", { + method: "POST", + headers: { + "Content-Type": "application/json", + Accept: "application/json", + }, + body: JSON.stringify({ + client_id: process.env.GITHUB_CLIENT_ID, + client_secret: process.env.GITHUB_CLIENT_SECRET, + code, + }), + }); + + const data = await response.json(); + return data.access_token; // gho_xxxx or ghu_xxxx +} +``` + +## Step 3: Pass the token to the SDK + +Create an SDK client for each authenticated user, passing their token. + +### Node.js / TypeScript + +```typescript +import { CopilotClient } from "@github/copilot-sdk"; + +// Create a client for an authenticated user +function createClientForUser(userToken: string): CopilotClient { + return new CopilotClient({ + githubToken: userToken, + useLoggedInUser: false, // Don't fall back to CLI sign-in + }); +} + +// Usage +const client = createClientForUser("USER-ACCESS-TOKEN"); +const session = await client.createSession({ + sessionId: `user-${userId}-session`, + model: "gpt-4.1", +}); + +const response = await session.sendAndWait({ prompt: "Hello!" }); +``` + +Replace `USER-ACCESS-TOKEN` with the user's OAuth access token (for example, `gho_xxxx`). + +### Python + +```python +from copilot import CopilotClient, PermissionHandler + +def create_client_for_user(user_token: str) -> CopilotClient: + return CopilotClient({ + "github_token": user_token, + "use_logged_in_user": False, + }) + +# Usage +client = create_client_for_user("USER-ACCESS-TOKEN") +await client.start() + +session = await client.create_session( + on_permission_request=PermissionHandler.approve_all, + model="gpt-4.1", + session_id=f"user-{user_id}-session", +) + +response = await session.send_and_wait({"prompt": "Hello!"}) +``` + +### Go + +```golang +func createClientForUser(userToken string) *copilot.Client { + return copilot.NewClient(&copilot.ClientOptions{ + GithubToken: userToken, + UseLoggedInUser: copilot.Bool(false), + }) +} + +// Usage +client := createClientForUser("USER-ACCESS-TOKEN") +client.Start(ctx) +defer client.Stop() + +session, _ := client.CreateSession(ctx, &copilot.SessionConfig{ + SessionID: fmt.Sprintf("user-%s-session", userID), + Model: "gpt-4.1", +}) +response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"}) +``` + +### .NET + +```csharp +CopilotClient CreateClientForUser(string userToken) => + new CopilotClient(new CopilotClientOptions + { + GithubToken = userToken, + UseLoggedInUser = false, + }); + +// Usage +await using var client = CreateClientForUser("USER-ACCESS-TOKEN"); +await using var session = await client.CreateSessionAsync(new SessionConfig +{ + SessionId = $"user-{userId}-session", + Model = "gpt-4.1", +}); + +var response = await session.SendAndWaitAsync( + new MessageOptions { Prompt = "Hello!" }); +``` + +## Enterprise and organization access + +{% data variables.product.github %} OAuth naturally supports enterprise scenarios. When users authenticate with {% data variables.product.github %}, their organization memberships and enterprise associations are included. + +### Verify organization membership + +After OAuth, you can check that the user belongs to your organization: + +```typescript +async function verifyOrgMembership( + token: string, + requiredOrg: string +): Promise { + const response = await fetch("https://api.github.com/user/orgs", { + headers: { Authorization: `Bearer ${token}` }, + }); + const orgs = await response.json(); + return orgs.some((org: any) => org.login === requiredOrg); +} + +// In your auth flow +const token = await handleOAuthCallback(code); +if (!await verifyOrgMembership(token, "YOUR-ORG")) { + throw new Error("User is not a member of the required organization"); +} +const client = createClientForUser(token); +``` + +Replace `YOUR-ORG` with your {% data variables.product.github %} organization name. + +### Enterprise Managed Users (EMU) + +For {% data variables.enterprise.prodname_managed_users %}, the flow is identical. EMU users authenticate through {% data variables.product.github %} OAuth like any other user, and enterprise policies (IP restrictions, SAML SSO) are enforced by {% data variables.product.github %} automatically. + +```typescript +// No special SDK configuration needed for EMU +const client = new CopilotClient({ + githubToken: emuUserToken, + useLoggedInUser: false, +}); +``` + +## Supported token types + +| Token prefix | Source | Supported | +|---|--------------------------------------------------------------------|---| +| `gho_` | OAuth user access token | Yes | +| `ghu_` | {% data variables.product.prodname_github_app %} user access token | Yes | +| `github_pat_` | {% data variables.product.pat_v2_caps %} | Yes | +| `ghp_` | {% data variables.product.pat_v1_caps %} | No ({% data variables.release-phases.closing_down %}) | + +## Token lifecycle management + +Your application is responsible for token storage, refresh, and expiration handling. The SDK uses whatever token you provide—it doesn't manage the OAuth lifecycle. + +### Token refresh pattern + +```typescript +async function getOrRefreshToken(userId: string): Promise { + const stored = await tokenStore.get(userId); + + if (stored && !isExpired(stored)) { + return stored.accessToken; + } + + if (stored?.refreshToken) { + const refreshed = await refreshGitHubToken(stored.refreshToken); + await tokenStore.set(userId, refreshed); + return refreshed.accessToken; + } + + throw new Error("User must re-authenticate"); +} +``` + +## Multi-user patterns + +### One client per user (recommended) + +Each user gets their own SDK client with their own token. This provides the strongest isolation. + +```typescript +const clients = new Map(); + +function getClientForUser(userId: string, token: string): CopilotClient { + if (!clients.has(userId)) { + clients.set(userId, new CopilotClient({ + githubToken: token, + useLoggedInUser: false, + })); + } + return clients.get(userId)!; +} +``` + +## Limitations + +| Limitation | Details | +|---|---| +| **{% data variables.product.prodname_copilot_short %} subscription required** | Each user needs an active {% data variables.product.prodname_copilot %} subscription. | +| **Token management is your responsibility** | You must store, refresh, and handle token expiration. | +| **{% data variables.product.github %} account required** | Users must have {% data variables.product.github %} accounts. | +| **Rate limits per user** | Usage is subject to each user's {% data variables.product.prodname_copilot_short %} rate limits. | + +## Next steps + +* To run the SDK on servers, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services). +* To handle many concurrent users, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/scaling). +* For installation and your first message, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started). diff --git a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/index.md b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/index.md new file mode 100644 index 000000000000..b170771a7d25 --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/index.md @@ -0,0 +1,16 @@ +--- +title: Set up Copilot SDK +shortTitle: Set up Copilot SDK +intro: Learn how to configure and deploy {% data variables.copilot.copilot_sdk %} for different environments. +versions: + feature: copilot +children: + - /choosing-a-setup-path + - /azure-managed-identity + - /backend-services + - /bundled-cli + - /github-oauth + - /local-cli + - /scaling +contentType: how-tos +--- diff --git a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/local-cli.md b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/local-cli.md new file mode 100644 index 000000000000..d87282a93cbe --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/local-cli.md @@ -0,0 +1,155 @@ +--- +title: Using a local CLI with Copilot SDK +shortTitle: Local CLI +intro: Use {% data variables.copilot.copilot_sdk %} with the CLI already signed in on your machine—the simplest configuration, with no auth code or infrastructure required. +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +--- + +{% data reusables.copilot.copilot-sdk.release-state-note %} + +Connecting {% data variables.copilot.copilot_sdk %} to your locally signed-in CLI is the fastest way to get started. + +**Best for:** Personal projects, prototyping, local development, and learning the SDK. + +## How it works + +When you install {% data variables.copilot.copilot_cli_short %} and sign in, your credentials are stored in the system keychain. The SDK automatically starts the CLI as a child process and uses those stored credentials. Key characteristics: + +* The CLI is spawned automatically by the SDK—no setup needed. +* Authentication uses the signed-in user's credentials from the system keychain. +* Communication happens over stdio (stdin/stdout)—no network ports are opened. +* Sessions are local to your machine. + +## Quick start + +The default configuration requires no options at all. + +### Node.js / TypeScript + +```typescript +import { CopilotClient } from "@github/copilot-sdk"; + +const client = new CopilotClient(); +const session = await client.createSession({ model: "gpt-4.1" }); + +const response = await session.sendAndWait({ prompt: "Hello!" }); +console.log(response?.data.content); + +await client.stop(); +``` + +### Python + +```python +from copilot import CopilotClient, PermissionHandler + +client = CopilotClient() +await client.start() + +session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1") +response = await session.send_and_wait({"prompt": "Hello!"}) +print(response.data.content) + +await client.stop() +``` + +### Go + +```golang +client := copilot.NewClient(nil) +if err := client.Start(ctx); err != nil { + log.Fatal(err) +} +defer client.Stop() + +session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"}) +response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"}) +fmt.Println(*response.Data.Content) +``` + +### .NET + +```csharp +await using var client = new CopilotClient(); +await using var session = await client.CreateSessionAsync( + new SessionConfig { Model = "gpt-4.1" }); + +var response = await session.SendAndWaitAsync( + new MessageOptions { Prompt = "Hello!" }); +Console.WriteLine(response?.Data.Content); +``` + +The SDK handles everything: starting the CLI, authenticating, and managing the session. + +## How does this work internally? + +For more information on the order of interaction between components, see the sequence diagram in the `github/copilot-sdk`[repository](https://github.com/github/copilot-sdk/blob/main/docs/setup/local-cli.md#whats-happening-under-the-hood). + +## Configuration options + +While defaults work for most cases, you can customize the local setup: + +```typescript +const client = new CopilotClient({ + // Override CLI location (default: bundled with @github/copilot) + cliPath: "/usr/local/bin/copilot", + + // Set log level for debugging + logLevel: "debug", + + // Pass extra CLI arguments + cliArgs: ["--log-dir=/tmp/copilot-logs"], + + // Set working directory + cwd: "/path/to/project", +}); +``` + +## Using environment variables + +Instead of the keychain, you can authenticate via environment variables. This is useful for CI or when you don't want interactive sign-in. + +```shell +# Set one of these (in priority order): +export COPILOT_GITHUB_TOKEN="YOUR-GITHUB-TOKEN" # Recommended +export GH_TOKEN="YOUR-GITHUB-TOKEN" # GitHub CLI compatible +export GITHUB_TOKEN="YOUR-GITHUB-TOKEN" # GitHub Actions compatible +``` + +Replace `YOUR-GITHUB-TOKEN` with a valid {% data variables.product.github %} {% data variables.product.pat_generic %} or OAuth token. The SDK picks these up automatically—no code changes are needed. + +## Managing sessions + +With the local CLI, sessions are ephemeral by default. To create resumable sessions, provide a session ID: + +```typescript +// Create a named session +const session = await client.createSession({ + sessionId: "my-project-analysis", + model: "gpt-4.1", +}); + +// Resume it in a later run +const resumed = await client.resumeSession("my-project-analysis"); +``` + +Session state is stored locally at `~/.copilot/session-state/SESSION-ID/`, where `SESSION-ID` is the session ID you provided. + +## Limitations + +| Limitation | Details | +|---|---| +| **Single user** | Credentials are tied to whoever signed in to the CLI. | +| **Local only** | The CLI runs on the same machine as your app. | +| **No multi-tenant** | Cannot serve multiple users from one CLI instance. | +| **Requires CLI sign-in** | User must run `copilot` and authenticate first. | + +## Next steps + +* To ship your app to other users, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/bundled-cli). +* To support multiple users signing in with their own {% data variables.product.github %} accounts, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth). +* To run the SDK on a server, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services). +* For your first message and installation, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started). diff --git a/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/scaling.md b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/scaling.md new file mode 100644 index 000000000000..e97f4a6a01c0 --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/scaling.md @@ -0,0 +1,434 @@ +--- +title: Scaling Copilot SDK deployments +shortTitle: Scaling +intro: Design your {% data variables.copilot.copilot_sdk %} deployment to serve multiple users, handle concurrent sessions, and scale horizontally across infrastructure. +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +--- + +{% data reusables.copilot.copilot-sdk.release-state-note %} + +Consider the different isolation patterns for CLI sessions, and how you want to manage concurrent sessions and resources, when implementing your application. + +**Best for:** Platform developers, SaaS builders, and any deployment serving more than a few concurrent users. + +## Session isolation patterns + +Before choosing a pattern, consider three dimensions: + +* **Isolation**: Who can see which sessions? +* **Concurrency**: How many sessions can run simultaneously? +* **Persistence**: How long do sessions live? + +![Diagram showing the three scaling dimensions for Copilot SDK deployments: isolation, concurrency, and persistence.](/assets/images/help/copilot/copilot-sdk/scaling-core-concepts.png) + +### Pattern 1: Isolated CLI per user + +Each user gets their own CLI server instance. This is the strongest isolation—a user's sessions, memory, and processes are completely separated. + +![Diagram showing the isolated CLI per user pattern, where each user gets a dedicated CLI server instance.](/assets/images/help/copilot/copilot-sdk/scaling-isolated-cli-pattern.png) + +**When to use:** + +* Multi-tenant SaaS where data isolation is critical. +* Users with different authentication credentials. +* Compliance requirements such as SOC 2 or HIPAA. + +```typescript +// CLI pool manager—one CLI per user +class CLIPool { + private instances = new Map(); + private nextPort = 5000; + + async getClientForUser(userId: string, token?: string): Promise { + if (this.instances.has(userId)) { + return this.instances.get(userId)!.client; + } + + const port = this.nextPort++; + + // Spawn a dedicated CLI for this user + await spawnCLI(port, token); + + const client = new CopilotClient({ + cliUrl: `localhost:${port}`, + }); + + this.instances.set(userId, { client, port }); + return client; + } + + async releaseUser(userId: string): Promise { + const instance = this.instances.get(userId); + if (instance) { + await instance.client.stop(); + this.instances.delete(userId); + } + } +} +``` + +### Pattern 2: Shared CLI with session isolation + +Multiple users share one CLI server but have isolated sessions via unique session IDs. This is lighter on resources, but provides weaker isolation. + +![Diagram showing the shared CLI pattern, where multiple users share one CLI server with isolated sessions.](/assets/images/help/copilot/copilot-sdk/scaling-shared-cli-pattern.png) + +**When to use:** + +* Internal tools with trusted users. +* Resource-constrained environments. +* Lower isolation requirements. + +```typescript +const sharedClient = new CopilotClient({ + cliUrl: "localhost:4321", +}); + +// Enforce session isolation through naming conventions +function getSessionId(userId: string, purpose: string): string { + return `${userId}-${purpose}-${Date.now()}`; +} + +// Access control: ensure users can only access their own sessions +async function resumeSessionWithAuth( + sessionId: string, + currentUserId: string +): Promise { + const [sessionUserId] = sessionId.split("-"); + if (sessionUserId !== currentUserId) { + throw new Error("Access denied: session belongs to another user"); + } + return sharedClient.resumeSession(sessionId); +} +``` + +### Pattern 3: Shared sessions (collaborative) + +Multiple users interact with the same session—like a shared chat room with Copilot. This pattern requires application-level session locking. + +![Diagram showing the shared sessions pattern, where multiple users interact with the same session through a message queue and session lock.](/assets/images/help/copilot/copilot-sdk/scaling-shared-sessions.png) + +**When to use:** + +* Team collaboration tools. +* Shared code review sessions. +* Pair programming assistants. + +> [!NOTE] +> The SDK doesn't provide built-in session locking. You must serialize access to prevent concurrent writes to the same session. + +```typescript +import Redis from "ioredis"; + +const redis = new Redis(); + +async function withSessionLock( + sessionId: string, + fn: () => Promise, + timeoutSec = 300 +): Promise { + const lockKey = `session-lock:${sessionId}`; + const lockId = crypto.randomUUID(); + + // Acquire lock + const acquired = await redis.set(lockKey, lockId, "NX", "EX", timeoutSec); + if (!acquired) { + throw new Error("Session is in use by another user"); + } + + try { + return await fn(); + } finally { + // Release lock only if we still own it + const currentLock = await redis.get(lockKey); + if (currentLock === lockId) { + await redis.del(lockKey); + } + } +} + +// Serialize access to a shared session +app.post("/team-chat", authMiddleware, async (req, res) => { + const result = await withSessionLock("team-project-review", async () => { + const session = await client.resumeSession("team-project-review"); + return session.sendAndWait({ prompt: req.body.message }); + }); + + res.json({ content: result?.data.content }); +}); +``` + +## Comparison of isolation patterns + +| | Isolated CLI per user | Shared CLI + session isolation | Shared sessions | +|---|---|---|---| +| **Isolation** | Complete | Logical | Shared | +| **Resource usage** | High (CLI per user) | Low (one CLI) | Low (one CLI and session) | +| **Complexity** | Medium | Low | High (requires locking) | +| **Auth flexibility** | Per-user tokens | Service token | Service token | +| **Best for** | Multi-tenant SaaS | Internal tools | Collaboration | + +## Horizontal scaling + +### Multiple CLI servers behind a load balancer + +To serve more concurrent users, run multiple CLI server instances behind a load balancer. Session state must be on **shared storage** so any CLI server can resume any session. + +![Diagram showing multiple CLI servers behind a load balancer with shared storage for session state.](/assets/images/help/copilot/copilot-sdk/scaling-multiple-cli-servers.png) + +```typescript +// Route sessions across CLI servers +class CLILoadBalancer { + private servers: string[]; + private currentIndex = 0; + + constructor(servers: string[]) { + this.servers = servers; + } + + // Round-robin selection + getNextServer(): string { + const server = this.servers[this.currentIndex]; + this.currentIndex = (this.currentIndex + 1) % this.servers.length; + return server; + } + + // Sticky sessions: same user always hits same server + getServerForUser(userId: string): string { + const hash = this.hashCode(userId); + return this.servers[hash % this.servers.length]; + } + + private hashCode(str: string): number { + let hash = 0; + for (let i = 0; i < str.length; i++) { + hash = (hash << 5) - hash + str.charCodeAt(i); + hash |= 0; + } + return Math.abs(hash); + } +} + +const lb = new CLILoadBalancer([ + "cli-1:4321", + "cli-2:4321", + "cli-3:4321", +]); + +app.post("/chat", async (req, res) => { + const server = lb.getServerForUser(req.user.id); + const client = new CopilotClient({ cliUrl: server }); + + const session = await client.createSession({ + sessionId: `user-${req.user.id}-chat`, + model: "gpt-4.1", + }); + + const response = await session.sendAndWait({ prompt: req.body.message }); + res.json({ content: response?.data.content }); +}); +``` + +### Sticky sessions vs. shared storage + +![Diagram comparing sticky sessions and shared storage approaches for scaling Copilot SDK deployments.](/assets/images/help/copilot/copilot-sdk/scaling-stick-and-shared-sessions.png) + +**Sticky sessions** pin each user to a specific CLI server. No shared storage is needed, but load distribution can be uneven if user traffic varies significantly. + +**Shared storage** enables any CLI to handle any session. Load distribution is more even, but requires networked storage for `~/.copilot/session-state/`. + +## Vertical scaling + +### Tuning a single CLI server + +A single CLI server can handle many concurrent sessions. The key is managing session lifecycle to avoid resource exhaustion: + +![Diagram showing the resource dimensions for vertical scaling: CPU, memory, disk I/O, and network.](/assets/images/help/copilot/copilot-sdk/scaling-vertical-scaling.png) + +```typescript +// Limit concurrent active sessions +class SessionManager { + private activeSessions = new Map(); + private maxConcurrent: number; + + constructor(maxConcurrent = 50) { + this.maxConcurrent = maxConcurrent; + } + + async getSession(sessionId: string): Promise { + // Return existing active session + if (this.activeSessions.has(sessionId)) { + return this.activeSessions.get(sessionId)!; + } + + // Enforce concurrency limit + if (this.activeSessions.size >= this.maxConcurrent) { + await this.evictOldestSession(); + } + + // Create or resume + const session = await client.createSession({ + sessionId, + model: "gpt-4.1", + }); + + this.activeSessions.set(sessionId, session); + return session; + } + + private async evictOldestSession(): Promise { + const [oldestId] = this.activeSessions.keys(); + const session = this.activeSessions.get(oldestId)!; + // Session state is persisted automatically—safe to disconnect + await session.disconnect(); + this.activeSessions.delete(oldestId); + } +} +``` + +## Ephemeral vs. persistent sessions + +![Diagram comparing ephemeral sessions and persistent sessions for Copilot SDK deployments.](/assets/images/help/copilot/copilot-sdk/scaling-ephemeral-vs-persistent-sessions.png) + +**Ephemeral sessions** are created per request and destroyed after use. They are ideal for one-shot tasks and stateless APIs. + +**Persistent sessions** are named, survive restarts, and are resumable. They are ideal for multi-turn chat and long workflows. + +### Ephemeral sessions + +```typescript +app.post("/api/analyze", async (req, res) => { + const session = await client.createSession({ + model: "gpt-4.1", + }); + + try { + const response = await session.sendAndWait({ + prompt: req.body.prompt, + }); + res.json({ result: response?.data.content }); + } finally { + await session.disconnect(); + } +}); +``` + +### Persistent sessions + +```typescript +// Start a conversation +app.post("/api/chat/start", async (req, res) => { + const sessionId = `user-${req.user.id}-${Date.now()}`; + + const session = await client.createSession({ + sessionId, + model: "gpt-4.1", + infiniteSessions: { + enabled: true, + backgroundCompactionThreshold: 0.80, + }, + }); + + res.json({ sessionId }); +}); + +// Continue the conversation +app.post("/api/chat/message", async (req, res) => { + const session = await client.resumeSession(req.body.sessionId); + const response = await session.sendAndWait({ prompt: req.body.message }); + + res.json({ content: response?.data.content }); +}); + +// Clean up when done +app.post("/api/chat/end", async (req, res) => { + await client.deleteSession(req.body.sessionId); + res.json({ success: true }); +}); +``` + +## Container deployments + +### Kubernetes with persistent storage + +The following example deploys three CLI replicas sharing a `PersistentVolumeClaim` so that any replica can resume any session. + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: copilot-cli +spec: + replicas: 3 + selector: + matchLabels: + app: copilot-cli + template: + metadata: + labels: + app: copilot-cli + spec: + containers: + - name: copilot-cli + image: ghcr.io/github/copilot-cli:latest + args: ["--headless", "--port", "4321"] + env: + - name: COPILOT_GITHUB_TOKEN + valueFrom: + secretKeyRef: + name: copilot-secrets + key: github-token + ports: + - containerPort: 4321 + volumeMounts: + - name: session-state + mountPath: /root/.copilot/session-state + volumes: + - name: session-state + persistentVolumeClaim: + claimName: copilot-sessions-pvc +--- +apiVersion: v1 +kind: Service +metadata: + name: copilot-cli +spec: + selector: + app: copilot-cli + ports: + - port: 4321 + targetPort: 4321 +``` + +![Diagram showing a Kubernetes deployment with multiple CLI server pods sharing a PersistentVolumeClaim for session state.](/assets/images/help/copilot/copilot-sdk/scaling-container-deployments.png) + +## Production checklist + +| Concern | Recommendation | +|---|---| +| **Session cleanup** | Run periodic cleanup to delete sessions older than your TTL. | +| **Health checks** | Ping the CLI server periodically; restart if unresponsive. | +| **Storage** | Mount persistent volumes for `~/.copilot/session-state/`. | +| **Secrets** | Use your platform's secret manager (Vault, Kubernetes Secrets, etc.). | +| **Monitoring** | Track active session count, response latency, and error rates. | +| **Locking** | Use Redis or similar for shared session access. | +| **Shutdown** | Drain active sessions before stopping CLI servers. | + +## Limitations + +| Limitation | Details | +|---|---| +| **No built-in session locking** | Implement application-level locking for concurrent access. | +| **No built-in load balancing** | Use an external load balancer or service mesh. | +| **Session state is file-based** | Requires a shared filesystem for multi-server setups. | +| **30-minute idle timeout** | Sessions without activity are auto-cleaned by the CLI. | +| **CLI is single-process** | Scale by adding more CLI server instances, not threads. | + +## Next steps + +* For core server-side setup, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services). +* For multi-user authentication, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/github-oauth). +* For installation and your first message, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started). diff --git a/content/copilot/how-tos/copilot-sdk/troubleshooting/debug-copilot-sdk.md b/content/copilot/how-tos/copilot-sdk/troubleshooting/debug-copilot-sdk.md new file mode 100644 index 000000000000..618dc1b01cbb --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/troubleshooting/debug-copilot-sdk.md @@ -0,0 +1,318 @@ +--- +title: Debugging Copilot SDK +shortTitle: Debug Copilot SDK +intro: Enable debug logging and resolve common connection, authentication, and tool execution issues in {% data variables.copilot.copilot_sdk_short %}. +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +--- + +> [!NOTE] +> {% data reusables.copilot.copilot-sdk.technical-preview-note %} + +## Enable debug logging + +To begin troubleshooting, enable verbose logging to gain visibility into the underlying processes. + +```typescript copy +import { CopilotClient } from "@github/copilot-sdk"; + +const client = new CopilotClient({ + logLevel: "debug", // Options: "none", "error", "warning", "info", "debug", "all" +}); +``` + +For examples in Python, Go, and .NET, see [Debugging Guide](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) in the `github/copilot-sdk` repository. + +### Log directory + +The CLI writes logs to the ABC directory by default. You can specify a different location using the `--log-dir` argument: + +```typescript copy +const client = new CopilotClient({ + cliArgs: ["--log-dir", "/path/to/logs"], +}); +``` + +For Python and Go, which do not currently support passing extra CLI arguments, run the CLI manually with `--log-dir` and connect via the `cliUrl` option. For more information, see [Debugging Guide](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) in the `github/copilot-sdk` repository. + +## Common issues + +### "CLI not found" or "copilot: command not found" + +**Cause:** {% data variables.copilot.copilot_cli %} is not installed or not in PATH. + +**Solution:** + +1. Install the CLI. For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/install-copilot-cli). + +1. Verify installation: + + ```bash copy + copilot --version + ``` + +1. Or specify the full path: + + ```typescript copy + const client = new CopilotClient({ + cliPath: "/usr/local/bin/copilot", + }); + ``` + + For examples in Python, Go, and .NET, see [Debugging Guide](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) in the `github/copilot-sdk` repository. + +### "Not authenticated" + +**Cause:** The CLI is not authenticated with {% data variables.product.github %}. + +**Solution:** + +1. Authenticate the CLI: + + ```bash copy + copilot auth login + ``` + +1. Or provide a token programmatically: + + ```typescript copy + const client = new CopilotClient({ + githubToken: process.env.GITHUB_TOKEN, + }); + ``` + + For examples in Python, Go, and .NET, see [Debugging Guide](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) in the `github/copilot-sdk` repository. + +### "Session not found" + +**Cause:** Attempting to use a session that was destroyed or doesn't exist. + +**Solution:** + +1. Ensure you're not calling methods after `disconnect()`: + + ```typescript copy + await session.disconnect(); + // Don't use session after this! + ``` + +1. For resuming sessions, verify the session ID exists: + + ```typescript copy + const sessions = await client.listSessions(); + console.log("Available sessions:", sessions); + ``` + +### "Connection refused" or "ECONNREFUSED" + +**Cause:** The CLI server process crashed or failed to start. + +**Solution:** + +1. Check if the CLI runs correctly standalone: + + ```bash copy + copilot --server --stdio + ``` + +1. Check for port conflicts if using TCP mode: + + ```typescript copy + const client = new CopilotClient({ + useStdio: false, + port: 0, // Use random available port + }); + ``` + +## MCP server debugging + +MCP (Model Context Protocol) servers can be tricky to debug. For comprehensive MCP debugging guidance, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/troubleshooting/debug-mcp-servers). + +### Quick MCP checklist + +* [ ] MCP server executable exists and runs independently +* [ ] Command path is correct (use absolute paths) +* [ ] Tools are enabled: `tools: ["*"]` +* [ ] Server responds to `initialize` request correctly +* [ ] Working directory (`cwd`) is set if needed + +### Test your MCP server + +Before integrating with the SDK, verify your MCP server works: + +```bash copy +echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server +``` + +For detailed troubleshooting, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/troubleshooting/debug-mcp-servers). + +## Connection issues + +### Stdio vs TCP mode + +The SDK supports two transport modes: + +| Mode | Description | Use case | +|------|-------------|----------| +| **Stdio** (default) | CLI runs as subprocess, communicates via pipes | Local development, single process | +| **TCP** | CLI runs separately, communicates via TCP socket | Multiple clients, remote CLI | + +**Stdio mode (default):** + +```typescript copy +const client = new CopilotClient({ + useStdio: true, // This is the default +}); +``` + +**TCP mode:** + +```typescript copy +const client = new CopilotClient({ + useStdio: false, + port: 8080, // Or 0 for random port +}); +``` + +**Connect to existing server:** + +```typescript copy +const client = new CopilotClient({ + cliUrl: "localhost:8080", // Connect to running server +}); +``` + +### Diagnosing connection failures + +1. Check client state: + + ```typescript copy + console.log("Connection state:", client.getState()); + // Should be "connected" after start() + ``` + +1. Listen for state changes: + + ```typescript copy + client.on("stateChange", (state) => { + console.log("State changed to:", state); + }); + ``` + +1. Verify the CLI process is running: + + ```bash copy + # Check for copilot processes + ps aux | grep copilot + ``` + +## Tool execution issues + +### Custom tool not being called + +1. Verify tool registration: + + ```typescript copy + const session = await client.createSession({ + tools: [myTool], + }); + + // Check registered tools + console.log("Registered tools:", session.getTools?.()); + ``` + +1. Check the tool schema is valid JSON Schema: + + ```typescript copy + const myTool = { + name: "get_weather", + description: "Get weather for a location", + parameters: { + type: "object", + properties: { + location: { type: "string", description: "City name" }, + }, + required: ["location"], + }, + handler: async (args) => { + return { temperature: 72 }; + }, + }; + ``` + +1. Ensure the handler returns a valid result: + + ```typescript copy + handler: async (args) => { + // Must return something JSON-serializable + return { success: true, data: "result" }; + + // Don't return undefined or non-serializable objects + } + ``` + +### Tool errors not surfacing + +Subscribe to error events: + +```typescript copy +session.on("tool.execution_error", (event) => { + console.error("Tool error:", event.data); +}); + +session.on("error", (event) => { + console.error("Session error:", event.data); +}); +``` + +## Platform-specific issues + +### Windows + +1. **Path separators:** Use raw strings or forward slashes. For .NET-specific examples, see [Debugging Guide](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) in the `github/copilot-sdk` repository. + +1. **Console encoding:** Ensure UTF-8 for proper JSON handling. For .NET-specific examples, see [Debugging Guide](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) in the `github/copilot-sdk` repository. + +### macOS + +1. **Gatekeeper issues:** If CLI is blocked: + + ```bash copy + xattr -d com.apple.quarantine /path/to/copilot + ``` + +1. **PATH issues in GUI apps:** GUI applications may not inherit shell PATH: + + ```typescript copy + const client = new CopilotClient({ + cliPath: "/opt/homebrew/bin/copilot", // Full path + }); + ``` + +### Linux + +1. **Permission issues:** + + ```bash copy + chmod +x /path/to/copilot + ``` + +1. **Missing libraries:** Check for required shared libraries: + + ```bash copy + ldd /path/to/copilot + ``` + +## Getting help + +If you're still stuck, collect the following debug information before opening an issue: + +* SDK version +* CLI version (`copilot --version`) +* Operating system +* Debug logs +* Minimal reproduction code + +Search for existing issues or open a new issue in the [github/copilot-sdk](https://github.com/github/copilot-sdk/issues) repository. diff --git a/content/copilot/how-tos/copilot-sdk/troubleshooting/debug-mcp-servers.md b/content/copilot/how-tos/copilot-sdk/troubleshooting/debug-mcp-servers.md new file mode 100644 index 000000000000..b9328972546b --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/troubleshooting/debug-mcp-servers.md @@ -0,0 +1,334 @@ +--- +title: Debugging MCP servers in Copilot SDK +shortTitle: Debug MCP servers +intro: Diagnose and fix issues with MCP servers integrated with {% data variables.copilot.copilot_sdk_short %}, including server startup failures, tool discovery problems, and protocol errors. +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +--- + +> [!NOTE] +> {% data reusables.copilot.copilot-sdk.technical-preview-note %} + +## Quick diagnostics + +### Checklist + +Before diving deep, verify these basics: + +* [ ] MCP server executable exists and is runnable +* [ ] Command path is correct (use absolute paths when in doubt) +* [ ] Tools are enabled (`tools: ["*"]` or specific tool names) +* [ ] Server implements MCP protocol correctly (responds to `initialize`) +* [ ] No firewall or antivirus is blocking the process (Windows) + +### Enable MCP debug logging + +Add environment variables to your MCP server config: + +```typescript copy +mcpServers: { + "my-server": { + type: "local", + command: "/path/to/server", + args: [], + env: { + MCP_DEBUG: "1", + DEBUG: "*", + NODE_DEBUG: "mcp", // For Node.js MCP servers + }, + }, +} +``` + +## Testing MCP servers independently + +Always test your MCP server outside the SDK first. + +### Manual protocol test + +Send an `initialize` request via stdin: + +```bash copy +# Unix/macOS +echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server +``` + +**Expected response:** + +```json +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}} +``` + +For a Windows PowerShell example, see [MCP Server Debugging Guide](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/mcp-debugging.md) in the `github/copilot-sdk` repository. + +### Test tool listing + +After initialization, request the tools list: + +```bash copy +echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server +``` + +**Expected response:** + +```json +{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"my_tool","description":"Does something","inputSchema":{...}}]}} +``` + +### Interactive testing script + +Create a test script to interactively debug your MCP server: + +```bash copy +#!/bin/bash +# test-mcp.sh + +SERVER="$1" + +# Initialize +echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' + +# Send initialized notification +echo '{"jsonrpc":"2.0","method":"notifications/initialized"}' + +# List tools +echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' + +# Keep stdin open +cat +``` + +Usage: + +```bash copy +./test-mcp.sh | /path/to/mcp-server +``` + +## Common issues + +### Server not starting + +**Symptoms:** No tools appear, no errors in logs. + +| Cause | Solution | +|-------|----------| +| Wrong command path | Use absolute path: `/usr/local/bin/server` | +| Missing executable permission | Run `chmod +x /path/to/server` | +| Missing dependencies | Check with `ldd` (Linux) or run manually | +| Working directory issues | Set `cwd` in config | + +Debug by running manually: + +```bash copy +# Run exactly what the SDK would run +cd /expected/working/dir +/path/to/command arg1 arg2 +``` + +### Server starts but tools don't appear + +**Symptoms:** Server process runs but no tools are available. + +1. **Tools not enabled in config:** + + ```typescript copy + mcpServers: { + "server": { + // ... + tools: ["*"], // Must be "*" or list of tool names + }, + } + ``` + +1. **Server doesn't expose tools:** Test with a `tools/list` request manually. Check that the server implements the `tools/list` method. + +1. **Initialization handshake fails:** The server must respond to `initialize` correctly and handle `notifications/initialized`. + +### Tools listed but never called + +**Symptoms:** Tools appear in debug logs but the model doesn't use them. + +1. **Prompt doesn't clearly need the tool:** + + ```typescript copy + // Too vague + await session.sendAndWait({ prompt: "What's the weather?" }); + + // Better—explicitly mentions capability + await session.sendAndWait({ + prompt: "Use the weather tool to get the current temperature in Seattle" + }); + ``` + +1. **Tool description unclear:** + + ```typescript copy + // Bad—model doesn't know when to use it + { name: "do_thing", description: "Does a thing" } + + // Good—clear purpose + { name: "get_weather", description: "Get current weather conditions for a city. Returns temperature, humidity, and conditions." } + ``` + +1. **Tool schema issues:** Ensure `inputSchema` is valid JSON Schema. Required fields must be listed in the `required` array. + +### Timeout errors + +**Symptoms:** `MCP tool call timed out` errors. + +1. Increase the timeout: + + ```typescript copy + mcpServers: { + "slow-server": { + // ... + timeout: 300000, // 5 minutes + }, + } + ``` + +1. Optimize server performance by adding progress logging to identify the bottleneck, considering async operations, and checking for blocking I/O. + +1. For long-running tools, consider streaming responses if supported. + +### JSON-RPC errors + +**Symptoms:** Parse errors, invalid request errors. + +Common causes: + +1. **Server writes to stdout incorrectly:** Debug output going to stdout instead of stderr, or extra newlines or whitespace: + + ```typescript copy + // Wrong—pollutes stdout + console.log("Debug info"); + + // Correct—use stderr for debug + console.error("Debug info"); + ``` + +1. **Encoding issues:** Ensure UTF-8 encoding with no BOM (Byte Order Mark). + +1. **Message framing:** Each message must be a complete JSON object, newline-delimited (one message per line). + +## Platform-specific issues + +### Windows + +On Windows, antivirus or firewall software may block new executables or processes communicating via stdin/stdout. Add exclusions for your MCP server executable if needed. + +For Windows-specific configuration examples for .NET console apps and NPX commands, see [MCP Server Debugging Guide](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/mcp-debugging.md) in the `github/copilot-sdk` repository. + +**Path issues:** + +* Use raw strings (`@"C:\path"`) or forward slashes (`"C:/path"`). +* Avoid spaces in paths when possible. +* If spaces are required, ensure proper quoting. + +### macOS + +1. **Gatekeeper blocking:** If the server is blocked: + + ```bash copy + xattr -d com.apple.quarantine /path/to/mcp-server + ``` + +1. **Homebrew paths:** GUI apps may not have `/opt/homebrew` in PATH. Use the full path: + + ```typescript copy + mcpServers: { + "my-server": { + command: "/opt/homebrew/bin/node", // Full path + args: ["/path/to/server.js"], + }, + } + ``` + +### Linux + +1. **Permission issues:** + + ```bash copy + chmod +x /path/to/mcp-server + ``` + +1. **Missing shared libraries:** + + ```bash copy + # Check dependencies + ldd /path/to/mcp-server + + # Install missing libraries + apt install libfoo # Debian/Ubuntu + yum install libfoo # RHEL/CentOS + ``` + +## Advanced debugging + +### Capture all MCP traffic + +Create a wrapper script to log all communication: + +```bash copy +#!/bin/bash +# mcp-debug-wrapper.sh + +LOG="/tmp/mcp-debug-$(date +%s).log" +ACTUAL_SERVER="$1" +shift + +echo "=== MCP Debug Session ===" >> "$LOG" +echo "Server: $ACTUAL_SERVER" >> "$LOG" +echo "Args: $@" >> "$LOG" +echo "=========================" >> "$LOG" + +# Tee stdin/stdout to log file +tee -a "$LOG" | "$ACTUAL_SERVER" "$@" 2>> "$LOG" | tee -a "$LOG" +``` + +Use it: + +```typescript copy +mcpServers: { + "debug-server": { + command: "/path/to/mcp-debug-wrapper.sh", + args: ["/actual/server/path", "arg1", "arg2"], + }, +} +``` + +### Inspect with MCP Inspector + +Use the official MCP Inspector tool: + +```bash copy +npx @modelcontextprotocol/inspector /path/to/your/mcp-server +``` + +This provides a web UI to send test requests, view responses, and inspect tool schemas. + +### Protocol version mismatches + +Check your server supports the protocol version the SDK uses: + +```json +// In initialize response, check protocolVersion +{"result":{"protocolVersion":"2024-11-05",...}} +``` + +If versions don't match, update your MCP server library. + +## Debugging checklist + +When opening an issue or asking for help on [GitHub Issues](https://github.com/github/copilot-sdk/issues), collect: + +* [ ] SDK language and version +* [ ] CLI version (`copilot --version`) +* [ ] MCP server type (Node.js, Python, .NET, Go, and so on) +* [ ] Full MCP server configuration (redact secrets) +* [ ] Result of manual `initialize` test +* [ ] Result of manual `tools/list` test +* [ ] Debug logs from SDK +* [ ] Any error messages diff --git a/content/copilot/how-tos/copilot-sdk/troubleshooting/index.md b/content/copilot/how-tos/copilot-sdk/troubleshooting/index.md new file mode 100644 index 000000000000..300ee9d750c8 --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/troubleshooting/index.md @@ -0,0 +1,12 @@ +--- +title: Troubleshooting Copilot SDK +shortTitle: Troubleshooting +intro: Find solutions to common issues and resolve problems when using {% data variables.copilot.copilot_sdk_short %}. +versions: + feature: copilot +children: + - /sdk-and-cli-compatibility + - /debug-copilot-sdk + - /debug-mcp-servers +contentType: how-tos +--- diff --git a/content/copilot/how-tos/copilot-sdk/troubleshooting/sdk-and-cli-compatibility.md b/content/copilot/how-tos/copilot-sdk/troubleshooting/sdk-and-cli-compatibility.md new file mode 100644 index 000000000000..d8298572c55e --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/troubleshooting/sdk-and-cli-compatibility.md @@ -0,0 +1,292 @@ +--- +title: SDK and CLI compatibility +shortTitle: SDK and CLI compatibility +intro: Compare which {% data variables.product.prodname_copilot_short %} CLI features are available through {% data variables.copilot.copilot_sdk_short %}, identify CLI-only features, and find programmatic workarounds. +product: '{% data reusables.gated-features.copilot-sdk %}' +versions: + feature: copilot +contentType: how-tos +--- + +> [!NOTE] +> {% data reusables.copilot.copilot-sdk.technical-preview-note %} + +{% data variables.copilot.copilot_sdk %} communicates with {% data variables.copilot.copilot_cli %} via JSON-RPC protocol. Features must be explicitly exposed through this protocol to be available in the SDK. Many interactive CLI features are terminal-specific and not available programmatically. + +## Feature comparison + +### Available in SDK + +| Feature | SDK method | Notes | +|---------|------------|-------| +| **Session Management** | | | +| Create session | `createSession()` | Full config support | +| Resume session | `resumeSession()` | With infinite session workspaces | +| Disconnect session | `disconnect()` | Release in-memory resources | +| Destroy session | `destroy()` | Use `disconnect()` instead | +| Delete session | `deleteSession()` | Remove from storage | +| List sessions | `listSessions()` | All stored sessions | +| Get last session | `getLastSessionId()` | For quick resume | +| Get foreground session | `getForegroundSessionId()` | Multi-session coordination | +| Set foreground session | `setForegroundSessionId()` | Multi-session coordination | +| **Messaging** | | | +| Send message | `send()` | With attachments | +| Send and wait | `sendAndWait()` | Blocks until complete | +| Steering (immediate mode) | `send({ mode: "immediate" })` | Inject mid-turn without aborting | +| Queueing (enqueue mode) | `send({ mode: "enqueue" })` | Buffer for sequential processing (default) | +| File attachments | `send({ attachments: [{ type: "file", path }] })` | Images auto-encoded and resized | +| Directory attachments | `send({ attachments: [{ type: "directory", path }] })` | Attach directory context | +| Get history | `getMessages()` | All session events | +| Abort | `abort()` | Cancel in-flight request | +| **Tools** | | | +| Register custom tools | `registerTools()` | Full JSON Schema support | +| Tool permission control | `onPreToolUse` hook | Allow/deny/ask | +| Tool result modification | `onPostToolUse` hook | Transform results | +| Available/excluded tools | `availableTools`, `excludedTools` config | Filter tools | +| **Models** | | | +| List models | `listModels()` | With capabilities, billing, policy | +| Set model (at creation) | `model` in session config | Per-session | +| Switch model (mid-session) | `session.setModel()` | Also via `session.rpc.model.switchTo()` | +| Get current model | `session.rpc.model.getCurrent()` | Query active model | +| Reasoning effort | `reasoningEffort` config | For supported models | +| **Agent Mode** | | | +| Get current mode | `session.rpc.mode.get()` | Returns current mode | +| Set mode | `session.rpc.mode.set()` | Switch between modes | +| **Plan Management** | | | +| Read plan | `session.rpc.plan.read()` | Get plan.md content and path | +| Update plan | `session.rpc.plan.update()` | Write plan.md content | +| Delete plan | `session.rpc.plan.delete()` | Remove plan.md | +| **Workspace Files** | | | +| List workspace files | `session.rpc.workspace.listFiles()` | Files in session workspace | +| Read workspace file | `session.rpc.workspace.readFile()` | Read file content | +| Create workspace file | `session.rpc.workspace.createFile()` | Create file in workspace | +| **Authentication** | | | +| Get auth status | `getAuthStatus()` | Check login state | +| Use token | `githubToken` option | Programmatic auth | +| **Connectivity** | | | +| Ping | `client.ping()` | Health check with server timestamp | +| Get server status | `client.getStatus()` | Protocol version and server info | +| **MCP Servers** | | | +| Local/stdio servers | `mcpServers` config | Spawn processes | +| Remote HTTP/SSE | `mcpServers` config | Connect to services | +| **Hooks** | | | +| Pre-tool use | `onPreToolUse` | Permission, modify args | +| Post-tool use | `onPostToolUse` | Modify results | +| User prompt | `onUserPromptSubmitted` | Modify prompts | +| Session start/end | `onSessionStart`, `onSessionEnd` | Lifecycle with source/reason | +| Error handling | `onErrorOccurred` | Custom handling | +| **Events** | | | +| All session events | `on()`, `once()` | 40+ event types | +| Streaming | `streaming: true` | Delta events | +| **Session Config** | | | +| Custom agents | `customAgents` config | Define specialized agents | +| System message | `systemMessage` config | Append or replace | +| Custom provider | `provider` config | BYOK support | +| Infinite sessions | `infiniteSessions` config | Auto-compaction | +| Permission handler | `onPermissionRequest` | Approve/deny requests | +| User input handler | `onUserInputRequest` | Handle ask_user | +| Skills | `skillDirectories` config | Custom skills | +| Disabled skills | `disabledSkills` config | Disable specific skills | +| Config directory | `configDir` config | Override default config location | +| Client name | `clientName` config | Identify app in User-Agent | +| Working directory | `workingDirectory` config | Set session cwd | +| **Experimental** | | | +| Agent management | `session.rpc.agent.*` | List, select, deselect, get current agent | +| Fleet mode | `session.rpc.fleet.start()` | Parallel sub-agent execution | +| Manual compaction | `session.rpc.compaction.compact()` | Trigger compaction on demand | + +### Not available in SDK (CLI-only) + +| Feature | CLI command/option | Reason | +|---------|-------------------|--------| +| **Session Export** | | | +| Export to file | `--share`, `/share` | Not in protocol | +| Export to gist | `--share-gist`, `/share gist` | Not in protocol | +| **Interactive UI** | | | +| Slash commands | `/help`, `/clear`, `/exit`, etc. | Terminal UI (TUI)-only | +| Agent picker dialog | `/agent` | Interactive UI | +| Diff mode dialog | `/diff` | Interactive UI | +| Feedback dialog | `/feedback` | Interactive UI | +| Theme picker | `/theme` | Terminal UI | +| Model picker | `/model` | Interactive UI (use SDK `setModel()` instead) | +| Copy to clipboard | `/copy` | Terminal-specific | +| Context management | `/context` | Interactive UI | +| **Research & History** | | | +| Deep research | `/research` | TUI workflow with web search | +| Session history tools | `/chronicle` | Standup, tips, improve, reindex | +| **Terminal Features** | | | +| Color output | `--no-color` | Terminal-specific | +| Screen reader mode | `--screen-reader` | Accessibility | +| Rich diff rendering | `--plain-diff` | Terminal rendering | +| Startup banner | `--banner` | Visual element | +| Streamer mode | `/streamer-mode` | TUI display mode | +| Alternate screen buffer | `--alt-screen`, `--no-alt-screen` | Terminal rendering | +| Mouse support | `--mouse`, `--no-mouse` | Terminal input | +| **Path/Permission Shortcuts** | | | +| Allow all paths | `--allow-all-paths` | Use permission handler | +| Allow all URLs | `--allow-all-urls` | Use permission handler | +| Allow all permissions | `--yolo`, `--allow-all`, `/allow-all` | Use permission handler | +| Granular tool permissions | `--allow-tool`, `--deny-tool` | Use `onPreToolUse` hook | +| URL access control | `--allow-url`, `--deny-url` | Use permission handler | +| Reset allowed tools | `/reset-allowed-tools` | TUI command | +| **Directory Management** | | | +| Add directory | `/add-dir`, `--add-dir` | Configure in session | +| List directories | `/list-dirs` | TUI command | +| Change directory | `/cwd` | TUI command | +| **Plugin/MCP Management** | | | +| Plugin commands | `/plugin` | Interactive management | +| MCP server management | `/mcp` | Interactive UI | +| **Account Management** | | | +| Login flow | `/login`, `copilot auth login` | OAuth device flow | +| Logout | `/logout`, `copilot auth logout` | Direct CLI | +| User info | `/user` | TUI command | +| **Session Operations** | | | +| Clear conversation | `/clear` | TUI-only | +| Plan view | `/plan` | TUI-only (use SDK `session.rpc.plan.*` instead) | +| Session management | `/session`, `/resume`, `/rename` | TUI workflow | +| Fleet mode (interactive) | `/fleet` | TUI-only (use SDK `session.rpc.fleet.start()` instead) | +| **Skills Management** | | | +| Manage skills | `/skills` | Interactive UI | +| **Task Management** | | | +| View background tasks | `/tasks` | TUI command | +| **Usage & Stats** | | | +| Token usage | `/usage` | Subscribe to usage events | +| **Code Review** | | | +| Review changes | `/review` | TUI command | +| **Delegation** | | | +| Delegate to PR | `/delegate` | TUI workflow | +| **Terminal Setup** | | | +| Shell integration | `/terminal-setup` | Shell-specific | +| **Development** | | | +| Toggle experimental | `/experimental`, `--experimental` | Runtime flag | +| Custom instructions control | `--no-custom-instructions` | CLI flag | +| Diagnose session | `/diagnose` | TUI command | +| View/manage instructions | `/instructions` | TUI command | +| Collect debug logs | `/collect-debug-logs` | Diagnostic tool | +| Reindex workspace | `/reindex` | TUI command | +| IDE integration | `/ide` | IDE-specific workflow | +| **Non-interactive Mode** | | | +| Prompt mode | `-p`, `--prompt` | Single-shot execution | +| Interactive prompt | `-i`, `--interactive` | Auto-execute then interactive | +| Silent output | `-s`, `--silent` | Script-friendly | +| Continue session | `--continue` | Resume most recent | +| Agent selection | `--agent ` | CLI flag | + +## Workarounds + +### Session export + +The `--share` option is not available via SDK. To work around this: + +* **Collect events manually:** Subscribe to session events and build your own export: + + ```typescript copy + const events: SessionEvent[] = []; + session.on((event) => events.push(event)); + // ... after conversation ... + const messages = await session.getMessages(); + // Format as markdown yourself + ``` + +* **Use the CLI directly** for one-off exports. + +### Permission control + +The SDK uses a deny-by-default permission model. All permission requests (file writes, shell commands, URL fetches, and others) are denied unless your app provides an `onPermissionRequest` handler. + +Instead of `--allow-all-paths` or `--yolo`, use the permission handler: + +```typescript copy +const session = await client.createSession({ + onPermissionRequest: approveAll, +}); +``` + +### Token usage tracking + +Instead of `/usage`, subscribe to usage events: + +```typescript copy +session.on("assistant.usage", (event) => { + console.log("Tokens used:", { + input: event.data.inputTokens, + output: event.data.outputTokens, + }); +}); +``` + +### Context compaction + +Instead of `/compact`, configure automatic compaction or trigger it manually: + +```typescript copy +// Automatic compaction via config +const session = await client.createSession({ + infiniteSessions: { + enabled: true, + backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization + bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization + }, +}); + +// Manual compaction (experimental) +const result = await session.rpc.compaction.compact(); +console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`); +``` + +> [!NOTE] +> Thresholds are context utilization ratios (0.0-1.0), not absolute token counts. + +### Plan management + +Read and write session plans programmatically: + +```typescript copy +// Read the current plan +const plan = await session.rpc.plan.read(); +if (plan.exists) { + console.log(plan.content); +} + +// Update the plan +await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" }); + +// Delete the plan +await session.rpc.plan.delete(); +``` + +### Message steering + +Inject a message into the current LLM turn without aborting: + +```typescript copy +// Steer the agent mid-turn +await session.send({ prompt: "Focus on error handling first", mode: "immediate" }); + +// Default: enqueue for next turn +await session.send({ prompt: "Next, add tests" }); +``` + +## Protocol limitations + +The SDK can only access features exposed through the CLI's JSON-RPC protocol. If you need a CLI feature that's not available: + +* **Check for alternatives:** Many features have SDK equivalents (see [Workarounds](#workarounds) above). +* **Use the CLI directly:** For one-off operations, invoke the CLI. +* **Request the feature:** Open an issue in the [github/copilot-sdk](https://github.com/github/copilot-sdk/issues) repository to request protocol support. + +## Version compatibility + +| SDK protocol range | CLI protocol version | Compatibility | +|--------------------|---------------------|---------------| +| v2-v3 | v3 | Full support | +| v2-v3 | v2 | Supported with automatic v2 adapters | + +The SDK negotiates protocol versions with the CLI at startup. The SDK supports protocol versions 2 through 3. When connecting to a v2 CLI server, the SDK automatically adapts `tool.call` and `permission.request` messages to the v3 event model—no code changes required. + +You can check versions at runtime: + +```typescript copy +const status = await client.getStatus(); +console.log("Protocol version:", status.protocolVersion); +``` diff --git a/content/copilot/reference/ai-models/model-hosting.md b/content/copilot/reference/ai-models/model-hosting.md index 9c203396cca7..9b82998524d9 100644 --- a/content/copilot/reference/ai-models/model-hosting.md +++ b/content/copilot/reference/ai-models/model-hosting.md @@ -21,9 +21,6 @@ Used for: * {% data variables.copilot.copilot_gpt_41 %} * {% data variables.copilot.copilot_gpt_5_mini %} * {% data variables.copilot.copilot_gpt_51 %} -* {% data variables.copilot.copilot_gpt_51_codex %} -* {% data variables.copilot.copilot_gpt_51_codex_mini %} -* {% data variables.copilot.copilot_gpt_51_codex_max %} * {% data variables.copilot.copilot_gpt_52 %} * {% data variables.copilot.copilot_gpt_52_codex %} * {% data variables.copilot.copilot_gpt_53_codex %} diff --git a/content/copilot/reference/ai-models/supported-models.md b/content/copilot/reference/ai-models/supported-models.md index beca331a0b98..9b4d1a656090 100644 --- a/content/copilot/reference/ai-models/supported-models.md +++ b/content/copilot/reference/ai-models/supported-models.md @@ -66,11 +66,6 @@ The following table shows which models are available in each client. > [!NOTE] > * {% data reusables.copilot.auto-model-selection %} > * {% data reusables.copilot.gpt-5-codex-vscode-support %} -> * {% data variables.copilot.copilot_gpt_51_codex %} and {% data variables.copilot.copilot_gpt_51_codex_mini %} are supported in: -> * Visual Studio Code versions 1.104.1 or higher -> * JetBrains, Copilot plugin versions 1.5.61 or higher -> * Xcode, Copilot plugin versions 0.45.0 or later -> * Eclipse, Copilot plugin versions 0.13.0 or later {% rowheaders %} diff --git a/content/index.md b/content/index.md index 987c9b192dc3..6b26dcf14c07 100644 --- a/content/index.md +++ b/content/index.md @@ -122,13 +122,15 @@ childGroups: - actions - packages - pages - - name: Security and quality + - name: Security and code quality octicon: ShieldLockIcon children: + - code-security - code-security/how-tos/secure-your-secrets + - code-security/how-tos/find-and-fix-code-vulnerabilities - code-security/how-tos/secure-your-supply-chain - - code-security/how-tos/scan-code-for-vulnerabilities - code-security/how-tos/maintain-quality-code + - code-security/how-tos/secure-at-scale - name: Client apps octicon: DeviceMobileIcon children: diff --git a/data/learning-tracks/code-security.yml b/data/learning-tracks/code-security.yml index e895090d861c..dfc7d982896b 100644 --- a/data/learning-tracks/code-security.yml +++ b/data/learning-tracks/code-security.yml @@ -186,16 +186,16 @@ code_security_actions: - >- /code-security/concepts/code-scanning/about-code-scanning - >- - /code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning + /code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning - >- /code-security/reference/code-scanning/workflow-configuration-options - >- - /code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/codeql-code-scanning-for-compiled-languages + /code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/codeql-code-scanning-for-compiled-languages - >- /code-security/tutorials/customize-code-scanning/running-codeql-code-scanning-in-a-container - /code-security/reference/code-scanning/troubleshoot-analysis-errors - >- - /code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning + /code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning code_security_integration: title: Integrate with code scanning description: Upload code analysis results from third-party systems to GitHub using SARIF. @@ -203,7 +203,7 @@ code_security_integration: - >- /code-security/concepts/code-scanning/about-integration-with-code-scanning - >- - /code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github + /code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github - >- /code-security/reference/code-scanning/sarif-files/sarif-support-for-code-scanning - /rest/code-scanning diff --git a/data/reusables/copilot/copilot-coding-agent-non-auto-models.md b/data/reusables/copilot/copilot-coding-agent-non-auto-models.md index 4c7a642532a9..ecccd4824da5 100644 --- a/data/reusables/copilot/copilot-coding-agent-non-auto-models.md +++ b/data/reusables/copilot/copilot-coding-agent-non-auto-models.md @@ -1,4 +1,3 @@ * {% data variables.copilot.copilot_claude_opus_45 %} * {% data variables.copilot.copilot_claude_opus_46 %} -* {% data variables.copilot.copilot_gpt_51_codex_max %} * {% data variables.copilot.copilot_gpt_52_codex %} diff --git a/data/reusables/copilot/copilot-sdk/release-state-note.md b/data/reusables/copilot/copilot-sdk/release-state-note.md new file mode 100644 index 000000000000..5b3f53275c1a --- /dev/null +++ b/data/reusables/copilot/copilot-sdk/release-state-note.md @@ -0,0 +1,2 @@ +> [!NOTE] +> {% data variables.copilot.copilot_sdk_short %} is currently in {% data variables.release-phases.technical_preview %}. Functionality and availability are subject to change. diff --git a/data/tables/copilot/model-deprecation-history.yml b/data/tables/copilot/model-deprecation-history.yml index 2cb89f2d9824..0df9f6666d42 100644 --- a/data/tables/copilot/model-deprecation-history.yml +++ b/data/tables/copilot/model-deprecation-history.yml @@ -12,7 +12,7 @@ # - suggested_alternative: The model recommended for migration. - name: 'GPT-5.1' - retirement_date: '2026-04-01' + retirement_date: '2026-04-15' suggested_alternative: 'GPT-5.3-Codex' - name: 'GPT-5.1-Codex' diff --git a/data/tables/copilot/model-release-status.yml b/data/tables/copilot/model-release-status.yml index e9d5a337e2dd..d87b2470a4da 100644 --- a/data/tables/copilot/model-release-status.yml +++ b/data/tables/copilot/model-release-status.yml @@ -34,28 +34,7 @@ - name: 'GPT-5.1' provider: 'OpenAI' - release_status: 'Closing down: 2026-04-01' - agent_mode: true - ask_mode: true - edit_mode: true - -- name: 'GPT-5.1-Codex' - provider: 'OpenAI' - release_status: 'Closing down: 2026-04-01' - agent_mode: true - ask_mode: true - edit_mode: true - -- name: 'GPT-5.1-Codex-Max' - provider: 'OpenAI' - release_status: 'Closing down: 2026-04-01' - agent_mode: true - ask_mode: true - edit_mode: true - -- name: 'GPT-5.1-Codex-Mini' - provider: 'OpenAI' - release_status: 'Closing down: 2026-04-01' + release_status: 'Closing down: 2026-04-15' agent_mode: true ask_mode: true edit_mode: true