From f716642e034f420ac98a5a4eace1e9e11502d5e3 Mon Sep 17 00:00:00 2001 From: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com> Date: Mon, 2 Feb 2026 13:57:24 +0000 Subject: [PATCH 1/8] [EDI] Creating CodeQL query suites (#59446) --- .../codeql/codeql-query-suites.md | 21 +++++++++++-------- .../creating-codeql-query-suites.md | 12 +---------- 2 files changed, 13 insertions(+), 20 deletions(-) diff --git a/content/code-security/concepts/code-scanning/codeql/codeql-query-suites.md b/content/code-security/concepts/code-scanning/codeql/codeql-query-suites.md index 1f7b6fef4094..8d15e99addbd 100644 --- a/content/code-security/concepts/code-scanning/codeql/codeql-query-suites.md +++ b/content/code-security/concepts/code-scanning/codeql/codeql-query-suites.md @@ -17,20 +17,19 @@ topics: contentType: concepts --- -## About {% data variables.product.prodname_codeql %} query suites +## What are query suites? -With {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %}, you can select a specific group of {% data variables.product.prodname_codeql %} queries, called a {% data variables.product.prodname_codeql %} query suite, to run against your code. The following built-in query suites are available through {% data variables.product.prodname_dotcom %}: +Query suites allow you to pass multiple queries to {% data variables.product.prodname_codeql %} without having to specify the path to each query file individually. They provide a way of selecting queries based on their filename, metadata properties, or location on disk or in a {% data variables.product.prodname_codeql %} pack. -* `default` query suite. -* `security-extended` query suite. This suite is referred to as the "Extended" query suite on {% data variables.product.prodname_dotcom %}. +You should use query suites for the queries that you want to frequently use in your {% data variables.product.prodname_codeql %} analyses. You can use a built-in query suite available through {% data variables.product.github %}, or you can create your own. -Currently, both the `default` query suite and the `security-extended` query suite are available for default setup for {% data variables.product.prodname_code_scanning %}. Additionally, organization owners and security managers can recommend a query suite for use with default setup throughout their organization. For more information on configuring default setup for individual repositories, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). For more information on configuring default setup at scale and recommending a query suite, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale). +## Built-in {% data variables.product.prodname_codeql %} query suites -To use a custom query suite, you must configure advanced setup for {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %}. For more information on advanced setups and creating a query suite, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql) and [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites). +The built-in {% data variables.product.prodname_codeql %} query suites, `default` and `security-extended`, are created and maintained by {% data variables.product.prodname_dotcom %}. Both of these query suites are available with default setup for every {% data variables.product.prodname_codeql %}-supported language. -## Built-in {% data variables.product.prodname_codeql %} query suites +Organization owners and security managers can recommend a query suite for use with default setup throughout their organization. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale). -The built-in {% data variables.product.prodname_codeql %} query suites, `default` and `security-extended`, are created and maintained by {% data variables.product.prodname_dotcom %}. Both of these query suites are available for every {% data variables.product.prodname_codeql %}-supported language. For more information on {% data variables.product.prodname_codeql %}-supported languages, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql#about-codeql). +For a complete list of queries included in each query suite for every language, see [AUTOTITLE](/code-security/code-scanning/reference/code-ql-built-in-queries). ### `default` query suite @@ -44,7 +43,11 @@ The built-in {% data variables.product.prodname_codeql %} query suites, `default * Relative to the `default` query suite, the `security-extended` suite may return a greater number of false positive {% data variables.product.prodname_code_scanning %} results. * This query suite is available for use with default setup for {% data variables.product.prodname_code_scanning %}, and is referred to as the "Extended" query suite on {% data variables.product.prodname_dotcom %}. -For a complete list of queries included in each query suite for every language, see [AUTOTITLE](/code-security/code-scanning/reference/code-ql-built-in-queries). +## Custom query suites + +To use a custom query suite, you must configure advanced setup for {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %}. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). + +Query suite definitions are stored in YAML files with the extension `.qls`. A suite definition is a sequence of instructions, where each instruction is a YAML mapping with (usually) a single key. The instructions are executed in the order they appear in the query suite definition. After all the instructions in the suite definition have been executed, the result is a set of selected queries. For more information, see [AUTOTITLE](/code-security/tutorials/customize-code-scanning/creating-codeql-query-suites). ## Further reading diff --git a/content/code-security/tutorials/customize-code-scanning/creating-codeql-query-suites.md b/content/code-security/tutorials/customize-code-scanning/creating-codeql-query-suites.md index e6fcd9cdf3e4..a0f1ac713d4c 100644 --- a/content/code-security/tutorials/customize-code-scanning/creating-codeql-query-suites.md +++ b/content/code-security/tutorials/customize-code-scanning/creating-codeql-query-suites.md @@ -17,19 +17,9 @@ redirect_from: contentType: tutorials --- -## About creating {% data variables.product.prodname_codeql %} query suites - {% data reusables.code-scanning.codeql-cli-version-ghes %} -{% data variables.product.prodname_codeql %} query suites provide a way of selecting queries, based on their -filename, location on disk or in a {% data variables.product.prodname_codeql %} pack, or metadata properties. -Create query suites for the queries that you want to frequently use in -your {% data variables.product.prodname_codeql %} analyses. - -Query suites allow you to pass multiple queries to {% data variables.product.prodname_codeql %} without having to specify the path to each query file individually. Query suite definitions are stored in YAML files with the extension `.qls`. A suite definition is a sequence of instructions, where each instruction is a YAML -mapping with (usually) a single key. The instructions are executed in the order -they appear in the query suite definition. After all the instructions in the -suite definition have been executed, the result is a set of selected queries. +You can create query suites for the queries that you want to frequently use in your {% data variables.product.prodname_codeql %} analyses. For more information, see [AUTOTITLE](/code-security/concepts/code-scanning/codeql/codeql-query-suites). > [!NOTE] > Any custom queries that you want to add to a query suite must be in a [{% data variables.product.prodname_codeql %} pack](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs) and contain the correct query metadata. For more information, see [Using custom queries with the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli). From 6e24d92bc03ff62b0253d50bb5f7043d220376c6 Mon Sep 17 00:00:00 2001 From: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com> Date: Mon, 2 Feb 2026 13:57:35 +0000 Subject: [PATCH 2/8] [EDI] Exporting data from security overview (#59445) --- .../exporting-data-from-security-overview.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/exporting-data-from-security-overview.md b/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/exporting-data-from-security-overview.md index 637a3ea53481..f3e32b84a416 100644 --- a/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/exporting-data-from-security-overview.md +++ b/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/exporting-data-from-security-overview.md @@ -19,12 +19,8 @@ redirect_from: - /code-security/security-overview/exporting-data-from-security-overview --- -## About exporting your security overview data - {% data reusables.security-overview.download-csv-files %} -The overview page contains data about security alerts across your organization or enterprise, while the risk and coverage pages contain data about repositories and how they are affected by security alerts or covered by security features. The {% data variables.product.prodname_codeql %} pull request alerts page contains data about {% data variables.product.prodname_codeql %} alerts that were caught in pull requests merged to the default branch. - The CSV file you download will contain data corresponding to the filters you have applied to security overview. For example, if you add the filter `dependabot-alerts:enabled`, your file will only contain data for repositories that have enabled {% data variables.product.prodname_dependabot_alerts %}. > [!NOTE] From f1971c0afc51d68265ac0e29acdf65378cd285eb Mon Sep 17 00:00:00 2001 From: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com> Date: Mon, 2 Feb 2026 14:20:00 +0000 Subject: [PATCH 3/8] [EDI] Editing your configuration of default setup (#59443) Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com> --- .../concepts/code-scanning/setup-types.md | 18 ++++++++++++++++-- ...ting-your-configuration-of-default-setup.md | 9 +-------- 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/content/code-security/concepts/code-scanning/setup-types.md b/content/code-security/concepts/code-scanning/setup-types.md index e7eb4d88966b..531f1335dc14 100644 --- a/content/code-security/concepts/code-scanning/setup-types.md +++ b/content/code-security/concepts/code-scanning/setup-types.md @@ -20,14 +20,28 @@ Default setup for {% data variables.product.prodname_code_scanning %} is the qui * When creating or committing to a pull request based against the repository's default branch, or any protected branch, excluding pull requests from forks. * On a weekly schedule. -If you need more granular control over your {% data variables.product.prodname_code_scanning %} configuration, you should instead configure advanced setup. - ### Supported languages {% data reusables.code-scanning.default-setup-pre-enablement-explanation %} If the code in a repository changes to include any {% data variables.product.prodname_codeql %}-supported languages, {% data variables.product.prodname_dotcom %} will automatically update the {% data variables.product.prodname_code_scanning %} configuration to include the new language. If {% data variables.product.prodname_code_scanning %} fails with the new configuration, {% data variables.product.prodname_dotcom %} will resume the previous configuration automatically so the repository does not lose {% data variables.product.prodname_code_scanning %} coverage. +## Customization of default setup + +After running an initial analysis of your code with default setup, you can make changes to your configuration to better meet your needs. + +If you need more granular control over your {% data variables.product.prodname_code_scanning %} configuration, you should instead configure advanced setup. + +### Configuration options + +For existing configurations of default setup, you can edit: + +* Which languages default setup will analyze. +* The query suite run during analysis. For more information on the available query suites, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites). +* The threat models ({% data variables.release-phases.public_preview %}) to use for analysis. Your choice of threat model determines which sources of tainted data are treated as a risk to your application. During the {% data variables.release-phases.public_preview %}, threat models are supported only for analysis of {% data variables.code-scanning.code_scanning_threat_model_support %}. For more information about threat models, see [Including local sources of tainted data in default setup](/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup#including-local-sources-of-tainted-data-in-default-setup). + +If your codebase depends on a library or framework that is not recognized by the standard libraries included with {% data variables.product.prodname_codeql %}, you can also extend the {% data variables.product.prodname_codeql %} coverage in default setup using {% data variables.product.prodname_codeql %} model packs. For more information, see [Extending CodeQL coverage with CodeQL model packs in default setup](/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup). + ### Available runners You can use default setup for all {% data variables.product.prodname_codeql %}-supported languages on self-hosted runners or {% data variables.product.prodname_dotcom %}-hosted runners. 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/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md index 8392399ef89f..3ddcc0cf4ec6 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/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md @@ -15,14 +15,7 @@ redirect_from: contentType: how-tos --- -## About editing your configuration of default setup - -After running an initial analysis of your code with default setup, you may need to make changes to your configuration to better meet your needs. For existing configurations of default setup, you can edit: -* Which languages default setup will analyze. -* The query suite run during analysis. For more information on the available query suites, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites). -* The threat models ({% data variables.release-phases.public_preview %}) to use for analysis. Your choice of threat model determines which sources of tainted data are treated as a risk to your application. During the {% data variables.release-phases.public_preview %}, threat models are supported only for analysis of {% data variables.code-scanning.code_scanning_threat_model_support %}. For more information about threat models, see [Including local sources of tainted data in default setup](#including-local-sources-of-tainted-data-in-default-setup). - -If your codebase depends on a library or framework that is not recognized by the standard libraries included with {% data variables.product.prodname_codeql %}, you can also extend the {% data variables.product.prodname_codeql %} coverage in default setup using {% data variables.product.prodname_codeql %} model packs. For more information, see [Extending CodeQL coverage with CodeQL model packs in default setup](#extending-codeql-coverage-with-codeql-model-packs-in-default-setup). +After running an initial analysis of your code with default setup, you can make changes to your configuration to better meet your needs. For more information on setup types and customization options, see [AUTOTITLE](/code-security/concepts/code-scanning/setup-types). If you need to change any other aspects of your {% data variables.product.prodname_code_scanning %} configuration, consider configuring advanced setup. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). From 3425e6be31ce5346a98e22db7fcd2d830b0a7728 Mon Sep 17 00:00:00 2001 From: Siara <108543037+SiaraMist@users.noreply.github.com> Date: Mon, 2 Feb 2026 06:48:07 -0800 Subject: [PATCH 4/8] Create a CLI map topic for rapid publishing (#59413) Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: hubwriter --- .../add-repository-instructions.md | 52 ---------- .../add-repository-instructions.md | 54 +++++++++++ content/copilot/how-tos/copilot-cli/index.md | 14 +++ .../install-copilot-cli.md | 3 +- .../use-copilot-cli.md | 1 + .../copilot/how-tos/copilot-cli/use-hooks.md | 29 ++++++ content/copilot/how-tos/index.md | 1 + content/copilot/how-tos/set-up/index.md | 4 +- .../coding-agent/use-hooks.md | 94 +------------------ .../how-tos/use-copilot-agents/index.md | 4 +- .../coding-agent/create-hooks-instructions.md | 53 +++++++++++ .../copilot/coding-agent/hooks-intro.md | 1 + .../coding-agent/troubleshoot-hooks.md | 35 +++++++ 13 files changed, 198 insertions(+), 147 deletions(-) create mode 100644 content/copilot/how-tos/copilot-cli/add-repository-instructions.md create mode 100644 content/copilot/how-tos/copilot-cli/index.md rename content/copilot/how-tos/{set-up => copilot-cli}/install-copilot-cli.md (95%) rename content/copilot/how-tos/{use-copilot-agents => copilot-cli}/use-copilot-cli.md (99%) create mode 100644 content/copilot/how-tos/copilot-cli/use-hooks.md create mode 100644 data/reusables/copilot/coding-agent/create-hooks-instructions.md create mode 100644 data/reusables/copilot/coding-agent/hooks-intro.md create mode 100644 data/reusables/copilot/coding-agent/troubleshoot-hooks.md diff --git a/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md b/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md index d0c46bee7663..0a11328bb952 100644 --- a/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md +++ b/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md @@ -531,58 +531,6 @@ Whitespace between instructions is ignored, so the instructions can be written a - - -{% copilotcli %} - -This version of this article is for using repository custom instructions with the {% data variables.product.prodname_copilot %} CLI. Click the tabs above for instructions on using custom instructions in other environments. - -## Creating custom instructions - -{% data variables.product.prodname_copilot %} supports three types of repository custom instructions. - -* **Repository-wide custom instructions**, which apply to all requests made in the context of a repository. - - These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions). - -* **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path. - - These are specified in one or more `NAME.instructions.md` files within or below the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions). - - If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. You should avoid potential conflicts between instructions as {% data variables.product.prodname_copilot_short %}'s choice between conflicting instructions is non-deterministic. - -* **Agent instructions** are used by AI agents. - - {% data reusables.copilot.custom-instructions-agents %} - - Alternatively, you can use a single `CLAUDE.md` or `GEMINI.md` file stored in the root of the repository. - -## Creating repository-wide custom instructions - -1. In the root of your repository, create a file named `.github/copilot-instructions.md`. - - Create the `.github` directory if it does not already exist. - -1. Add natural language instructions to the file, in Markdown format. - - Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. - -## Creating path-specific custom instructions - -{% data reusables.copilot.custom-instructions-path %} - -{% data reusables.copilot.custom-instructions-note %} - -## Further reading - -* [AUTOTITLE](/copilot/reference/custom-instructions-support) -* [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions)—a curated collection of examples -* [AUTOTITLE](/copilot/tutorials/use-custom-instructions) - -{% endcopilotcli %} - - - {% eclipse %} diff --git a/content/copilot/how-tos/copilot-cli/add-repository-instructions.md b/content/copilot/how-tos/copilot-cli/add-repository-instructions.md new file mode 100644 index 000000000000..66dde3eaefe0 --- /dev/null +++ b/content/copilot/how-tos/copilot-cli/add-repository-instructions.md @@ -0,0 +1,54 @@ +--- +title: Adding repository custom instructions +shortTitle: Add repository instructions +intro: 'Create repository custom instructions files that give {% data variables.product.prodname_copilot_short %} additional context on how to understand your project and how to build, test and validate its changes.' +versions: + feature: copilot +topics: + - Copilot +contentType: how-tos +--- + +This version of this article is for using repository custom instructions with the {% data variables.product.prodname_copilot %} CLI. Click the tabs above for instructions on using custom instructions in other environments. + +## Creating custom instructions + +{% data variables.product.prodname_copilot %} supports three types of repository custom instructions. + +* **Repository-wide custom instructions**, which apply to all requests made in the context of a repository. + + These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions). + +* **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path. + + These are specified in one or more `NAME.instructions.md` files within or below the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions). + + If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. You should avoid potential conflicts between instructions as {% data variables.product.prodname_copilot_short %}'s choice between conflicting instructions is non-deterministic. + +* **Agent instructions** are used by AI agents. + + {% data reusables.copilot.custom-instructions-agents %} + + Alternatively, you can use a single `CLAUDE.md` or `GEMINI.md` file stored in the root of the repository. + +## Creating repository-wide custom instructions + +1. In the root of your repository, create a file named `.github/copilot-instructions.md`. + + Create the `.github` directory if it does not already exist. + +1. Add natural language instructions to the file, in Markdown format. + + Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. + +## Creating path-specific custom instructions + +{% data reusables.copilot.custom-instructions-path %} + +{% data reusables.copilot.custom-instructions-note %} + +## Further reading + +* [AUTOTITLE](/copilot/reference/custom-instructions-support) +* [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions)—a curated collection of examples +* [AUTOTITLE](/copilot/tutorials/use-custom-instructions) diff --git a/content/copilot/how-tos/copilot-cli/index.md b/content/copilot/how-tos/copilot-cli/index.md new file mode 100644 index 000000000000..88abbde343fc --- /dev/null +++ b/content/copilot/how-tos/copilot-cli/index.md @@ -0,0 +1,14 @@ +--- +title: GitHub Copilot CLI +shortTitle: Copilot CLI +intro: Learn how to use {% data variables.product.prodname_copilot %} in your terminal. +versions: + feature: copilot +children: + - /install-copilot-cli + - /add-repository-instructions + - /use-hooks + - /use-copilot-cli +contentType: how-tos +--- + diff --git a/content/copilot/how-tos/set-up/install-copilot-cli.md b/content/copilot/how-tos/copilot-cli/install-copilot-cli.md similarity index 95% rename from content/copilot/how-tos/set-up/install-copilot-cli.md rename to content/copilot/how-tos/copilot-cli/install-copilot-cli.md index f0078becdc58..a012a3f03b1d 100644 --- a/content/copilot/how-tos/set-up/install-copilot-cli.md +++ b/content/copilot/how-tos/copilot-cli/install-copilot-cli.md @@ -1,7 +1,7 @@ --- title: Installing GitHub Copilot CLI shortTitle: Install Copilot CLI -intro: 'Learn how to install {% data variables.copilot.copilot_cli_short %} so that you can use {% data variables.product.prodname_copilot_short %} directly from the command line.' +intro: Learn how to install {% data variables.copilot.copilot_cli_short %} so that you can use {% data variables.product.prodname_copilot_short %} directly from the command line. versions: feature: copilot topics: @@ -15,6 +15,7 @@ redirect_from: - /copilot/managing-copilot/configure-personal-settings/installing-github-copilot-in-the-cli - /copilot/how-tos/personal-settings/installing-github-copilot-in-the-cli - /copilot/how-tos/set-up/installing-github-copilot-in-the-cli + - /copilot/how-tos/set-up/install-copilot-cli contentType: how-tos category: - Configure Copilot diff --git a/content/copilot/how-tos/use-copilot-agents/use-copilot-cli.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli.md similarity index 99% rename from content/copilot/how-tos/use-copilot-agents/use-copilot-cli.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli.md index 5a81beb417f5..c60d027ae47f 100644 --- a/content/copilot/how-tos/use-copilot-agents/use-copilot-cli.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli.md @@ -5,6 +5,7 @@ intro: Learn how to use {% data variables.product.prodname_copilot %} from the c product: '{% data reusables.gated-features.copilot-cli %}' redirect_from: - /copilot/how-tos/use-copilot-cli + - /copilot/how-tos/use-copilot-agents/use-copilot-cli versions: feature: copilot topics: diff --git a/content/copilot/how-tos/copilot-cli/use-hooks.md b/content/copilot/how-tos/copilot-cli/use-hooks.md new file mode 100644 index 000000000000..b4dd5ba03022 --- /dev/null +++ b/content/copilot/how-tos/copilot-cli/use-hooks.md @@ -0,0 +1,29 @@ +--- +title: Using hooks with GitHub Copilot CLI +shortTitle: Use hooks +intro: "Extend {% data variables.product.prodname_copilot %} agent behavior with custom shell commands at key points during agent execution." +versions: + feature: copilot +topics: + - Copilot +contentType: how-tos +category: + - Configure Copilot +--- + +{% data reusables.copilot.coding-agent.hooks-intro %} + +## Creating a hook in a repository on {% data variables.product.github %} + +{% data reusables.copilot.coding-agent.create-hooks-instructions %} + +## Troubleshooting + +{% data reusables.copilot.coding-agent.troubleshoot-hooks %} + +## Further reading + +* [AUTOTITLE](/copilot/reference/hooks-configuration) +* [AUTOTITLE](/copilot/concepts/agents/coding-agent/about-coding-agent) +* [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli) +* [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment) \ No newline at end of file diff --git a/content/copilot/how-tos/index.md b/content/copilot/how-tos/index.md index 33f4ee2caa27..2c889032bf0d 100644 --- a/content/copilot/how-tos/index.md +++ b/content/copilot/how-tos/index.md @@ -10,6 +10,7 @@ children: - /set-up - /get-code-suggestions - /chat-with-copilot + - /copilot-cli - /use-copilot-agents - /use-ai-models - /provide-context diff --git a/content/copilot/how-tos/set-up/index.md b/content/copilot/how-tos/set-up/index.md index fb4044ff53a5..b3b76877d768 100644 --- a/content/copilot/how-tos/set-up/index.md +++ b/content/copilot/how-tos/set-up/index.md @@ -1,7 +1,7 @@ --- title: Setting up GitHub Copilot shortTitle: Set up -intro: 'Learn how to set up {% data variables.product.prodname_copilot %}.' +intro: Learn how to set up {% data variables.product.prodname_copilot %}. topics: - Copilot versions: @@ -12,9 +12,9 @@ children: - /set-up-for-enterprise - /set-up-a-dedicated-enterprise-for-copilot-business - /install-copilot-extension - - /install-copilot-cli redirect_from: - /copilot/setting-up-github-copilot - /copilot/get-started/setting-up-github-copilot contentType: how-tos --- + diff --git a/content/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks.md b/content/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks.md index a9e549792da4..4f678282e67a 100644 --- a/content/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks.md +++ b/content/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks.md @@ -1,7 +1,7 @@ --- title: Using hooks with GitHub Copilot agents shortTitle: Use hooks -intro: 'Learn how to extend and customize {% data variables.product.prodname_copilot %} agent behavior by executing custom shell commands at key points during agent execution.' +intro: 'Extend and customize {% data variables.product.prodname_copilot %} agent behavior by executing custom shell commands at key points during agent execution.' versions: feature: copilot topics: @@ -11,101 +11,15 @@ category: - Configure Copilot --- -Hooks allow you to extend and customize the behavior of {% data variables.product.prodname_copilot %} agents by executing custom shell commands at key points during agent execution. For a conceptual overview of hooks, see [AUTOTITLE](/copilot/concepts/agents/coding-agent/about-hooks). +{% data reusables.copilot.coding-agent.hooks-intro %} ## Creating a hook in a repository on {% data variables.product.github %} -1. Create a new `hooks.json` file with the name of your choice in the `.github/hooks/` folder of your repository. The hooks configuration file **must be present** on your repository's default branch to be used by {% data variables.copilot.copilot_coding_agent %}. For {% data variables.copilot.copilot_cli %}, hooks are loaded from your current working directory. - -1. In your text editor, copy and paste the following hook template. Remove any hooks you don't plan on using from the `hooks` array. - - ```json copy - { - "version": 1, - "hooks": { - "sessionStart": [...], - "sessionEnd": [...], - "userPromptSubmitted": [...], - "preToolUse": [...], - "postToolUse": [...], - "errorOccurred": [...] - } - } - ``` - -1. Configure your hook syntax under the `bash` or `powershell` keys, or directly reference script files you have created. - - * This example runs a script that outputs the start date of the session to a log file using the `sessionStart` hook: - - ```json copy - "sessionStart": [ - { - "type": "command", - "bash": "echo \"Session started: $(date)\" >> logs/session.log", - "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"", - "cwd": ".", - "timeoutSec": 10 - } - ], - ``` - - * This example calls out to an external `log-prompt` script: - - ```json copy - "userPromptSubmitted": [ - { - "type": "command", - "bash": "./scripts/log-prompt.sh", - "powershell": "./scripts/log-prompt.ps1", - "cwd": "scripts", - "env": { - "LOG_LEVEL": "INFO" - } - } - ], - ``` - - For a full reference on the input JSON from agent sessions along with sample scripts, see [AUTOTITLE](/copilot/reference/hooks-configuration). - -1. Commit the file to the repository and merge it into the default branch. Your hooks will now run during agent sessions. +{% data reusables.copilot.coding-agent.create-hooks-instructions %} ## Troubleshooting -If you run into problems using hooks, use the following table to troubleshoot. - -| Issue | Action | -| --- | --- | -| Hooks are not executing | | -| Hooks are timing out |