diff --git a/assets/images/enterprise/management-console/monitor-dash-link-old.png b/assets/images/enterprise/management-console/monitor-dash-link-old.png deleted file mode 100644 index df9682bc0c69..000000000000 Binary files a/assets/images/enterprise/management-console/monitor-dash-link-old.png and /dev/null differ diff --git a/assets/images/help/enterprises/activity-dashboard.png b/assets/images/help/enterprises/activity-dashboard.png deleted file mode 100644 index 331565a94e15..000000000000 Binary files a/assets/images/help/enterprises/activity-dashboard.png and /dev/null differ diff --git a/content/account-and-profile/concepts/contributions-on-your-profile.md b/content/account-and-profile/concepts/contributions-on-your-profile.md index 1baafffa63be..f00fbb55af3f 100644 --- a/content/account-and-profile/concepts/contributions-on-your-profile.md +++ b/content/account-and-profile/concepts/contributions-on-your-profile.md @@ -57,6 +57,6 @@ If you can't see certain events in your timeline, check to make sure you still h ## Next steps -To learn the different ways to view your contributions, see [AUTOTITLE](/account-and-profile/how-tos/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile). +To learn the different ways to view your contributions, see [AUTOTITLE](/account-and-profile/how-tos/contribution-settings/viewing-contributions-on-your-profile). To learn what counts as a contribution, see [AUTOTITLE](/account-and-profile/reference/why-are-my-contributions-not-showing-up-on-my-profile#what-counts-as-a-contribution) diff --git a/content/account-and-profile/concepts/email-addresses.md b/content/account-and-profile/concepts/email-addresses.md index 04f12356db96..cb06a1b50b14 100644 --- a/content/account-and-profile/concepts/email-addresses.md +++ b/content/account-and-profile/concepts/email-addresses.md @@ -13,13 +13,13 @@ category: ## Adding an email address to your {% data variables.product.github %} account -{% data variables.product.github %} allows you to add as many email addresses to your account as you like. For more information, see [AUTOTITLE](/account-and-profile/how-tos/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). +{% data variables.product.github %} allows you to add as many email addresses to your account as you like. For more information, see [AUTOTITLE](/account-and-profile/how-tos/email-preferences/adding-an-email-address-to-your-github-account). If you set an email address in your local Git configuration, you will need to add it to your account settings in order to connect your commits to your account. For more information about your email address and commits, see [Commit email addresses](#commit-email-addresses) below. ## Changing your primary email address -You can change the email address associated with your personal account at any time. You cannot change your primary email address to an email that is already set to be your backup email address. For more information, see [AUTOTITLE](/account-and-profile/how-tos/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address). +You can change the email address associated with your personal account at any time. You cannot change your primary email address to an email that is already set to be your backup email address. For more information, see [AUTOTITLE](/account-and-profile/how-tos/email-preferences/changing-your-primary-email-address). ## Email verification for personal accounts @@ -59,5 +59,5 @@ For more information, see [AUTOTITLE](/account-and-profile/how-tos/setting-up-an ## Next steps -* For how-to procedures on managing your email preferences, see [AUTOTITLE](/account-and-profile/how-tos/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences). +* For how-to procedures on managing your email preferences, see [AUTOTITLE](/account-and-profile/how-tos/email-preferences). * For email address reference information, see [AUTOTITLE](/account-and-profile/reference/email-addresses-reference). diff --git a/content/account-and-profile/get-started/account.md b/content/account-and-profile/get-started/account.md index 50c8f9077ebe..3e244e8f3d8a 100644 --- a/content/account-and-profile/get-started/account.md +++ b/content/account-and-profile/get-started/account.md @@ -26,7 +26,7 @@ If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %} ## Next steps * For conceptual information about accounts, see [AUTOTITLE](/account-and-profile/concepts/account-management). -* For information about managing your account, see [AUTOTITLE](/account-and-profile/how-tos/setting-up-and-managing-your-personal-account-on-github). +* For information about managing your account, see [AUTOTITLE](/account-and-profile/how-tos). * For reference information, see [AUTOTITLE](/account-and-profile/reference/personal-account-reference). {%- ifversion ghec %} * For information about {% data variables.enterprise.prodname_managed_users %}, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). diff --git a/content/account-and-profile/get-started/profile.md b/content/account-and-profile/get-started/profile.md index a0a8b96961f8..cd9cafa32d7b 100644 --- a/content/account-and-profile/get-started/profile.md +++ b/content/account-and-profile/get-started/profile.md @@ -16,5 +16,5 @@ category: Your profile is how other people discover and learn about you on {% data variables.product.github %}. You can customize your profile to highlight your best work and share more about yourself. * For a general tutorial on personalizing your profile, see [AUTOTITLE](/account-and-profile/tutorials/personalize-your-profile). -* For more specific profile customization, see [AUTOTITLE](/account-and-profile/how-tos/setting-up-and-managing-your-github-profile). +* For more specific profile customization, see [AUTOTITLE](/account-and-profile/how-tos). * For reference information, see [AUTOTITLE](/account-and-profile/reference/profile-reference). diff --git a/content/account-and-profile/how-tos/contribution-settings/troubleshooting-missing-contributions.md b/content/account-and-profile/how-tos/contribution-settings/troubleshooting-missing-contributions.md index a77981e3b830..8597ea6da54d 100644 --- a/content/account-and-profile/how-tos/contribution-settings/troubleshooting-missing-contributions.md +++ b/content/account-and-profile/how-tos/contribution-settings/troubleshooting-missing-contributions.md @@ -21,7 +21,7 @@ category: ## Commit was made less than 24 hours ago -After making a commit that meets the requirements to count as a contribution, you may need to wait for up to 24 hours to see the contribution appear on your contributions graph. For more information, see [AUTOTITLE](/account-and-profile/how-tos/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/troubleshooting-commits-on-your-timeline). +After making a commit that meets the requirements to count as a contribution, you may need to wait for up to 24 hours to see the contribution appear on your contributions graph. For more information, see [AUTOTITLE](/account-and-profile/how-tos/contribution-settings/viewing-commit-details-from-your-timeline). ## Your local Git commit email isn't connected to your account diff --git a/content/account-and-profile/tutorials/personalize-your-profile.md b/content/account-and-profile/tutorials/personalize-your-profile.md index 5deb2bb3938f..f7e4a9e7b2e0 100644 --- a/content/account-and-profile/tutorials/personalize-your-profile.md +++ b/content/account-and-profile/tutorials/personalize-your-profile.md @@ -124,7 +124,7 @@ You can set a status to display information about your current availability. ## Next steps -* To learn more about GitHub profiles, see [AUTOTITLE](/account-and-profile/concepts/about-your-profile). +* To learn more about GitHub profiles, see [AUTOTITLE](/account-and-profile/concepts/personal-profile). * For reference information, see [AUTOTITLE](/account-and-profile/reference/profile-reference). diff --git a/content/billing/how-tos/set-up-payment/manage-payment-info.md b/content/billing/how-tos/set-up-payment/manage-payment-info.md index 6129ea66cdc3..2db5d355894a 100644 --- a/content/billing/how-tos/set-up-payment/manage-payment-info.md +++ b/content/billing/how-tos/set-up-payment/manage-payment-info.md @@ -24,7 +24,7 @@ category: - Set up payment --- -The payment methods available depend on your account type. Enterprise and organization accounts have more payment options than personal accounts. Invoiced enterprise accounts make their payments using other methods. For more information, see [AUTOTITLE](/billing/reference/payment-methods). +The payment methods available depend on your account type. Enterprise and organization accounts have more payment options than personal accounts. Invoiced enterprise accounts make their payments using other methods. For more information, see [AUTOTITLE](/billing/reference/supported-payment-methods). ## Managing payment information diff --git a/content/billing/reference/index.md b/content/billing/reference/index.md index 9b1228245a4b..d6a0bbf9bac3 100644 --- a/content/billing/reference/index.md +++ b/content/billing/reference/index.md @@ -20,6 +20,6 @@ children: - /product-and-sku-names - /product-usage-included - /roles-for-visual-studio - - /payment-methods + - /supported-payment-methods contentType: reference --- diff --git a/content/billing/reference/payment-methods.md b/content/billing/reference/payment-methods.md deleted file mode 100644 index 6b3ae47fda09..000000000000 --- a/content/billing/reference/payment-methods.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Payment methods -shortTitle: Payment methods -intro: 'Reference information for supported payment methods for {% data variables.product.github %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -contentType: reference -category: - - Set up payment -redirect_from: - - /billing/reference/supported-payment-methods ---- - -The payment methods available to you depend on your account type and the products you use. - -## Self-serve accounts - -Self-serve accounts can use the following payment methods: - -* Credit card -* PayPal -* Azure Subscription ID (not personal accounts) - -## Invoiced accounts - -Invoiced accounts can use different payment methods for volume-licensed products (such as {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_GH_advanced_security %}) and metered products (such as {% data variables.product.prodname_github_codespaces %}). You can combine payment methods for different product types. For example, you can use invoice for volume products and Azure Subscription ID for metered products. - -| Payment method | Volume products | Metered products | -|---|---|---| -| Credit card | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | -| PayPal | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | -| Azure Subscription ID | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | -| Invoice | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -| Prepaid credits | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | -| Purchase order | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -| ACH | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | - -> [!NOTE] -> For purchase orders, contact [{% data variables.product.github %}'s Sales team](https://github.com/enterprise/contact?scid=&utm_campaign=2023q3-site-ww-PremiumSupport&utm_content=Premium+Support&utm_medium=referral&utm_source=github). diff --git a/content/billing/reference/supported-payment-methods.md b/content/billing/reference/supported-payment-methods.md new file mode 100644 index 000000000000..2989e0f12d3c --- /dev/null +++ b/content/billing/reference/supported-payment-methods.md @@ -0,0 +1,71 @@ +--- +title: Supported payment methods for GitHub +intro: 'Reference information detailing the supported payment methods for {% data variables.product.github %}.' +versions: + fpt: '*' + ghec: '*' + ghes: '*' +shortTitle: Supported payment methods +contentType: reference +category: + - Set up payment +redirect_from: + - /billing/reference/payment-methods +--- + +## Metered or usage-based billing options + +> [!NOTE] +> Prepaid credit/debit cards are not accepted as a valid form of payment. + +The supported payment methods for metered billing: + +* Invoice – Managed accounts only +* Credit card – Unmanaged accounts, or as a nonrecurring method for managed accounts +* PayPal – Unmanaged accounts, or as a nonrecurring method for managed accounts +* Azure Subscription ID – Not available for personal accounts +* Automated Clearing House (ACH) – Managed accounts only + +Accounts with volume licenses and metered billing can use multiple payment methods. + +* For unmanaged accounts, you might pay for volume licenses with a credit card or PayPal, and metered usage with an Azure Subscription ID. +* For managed accounts, you might pay for volume licenses via invoice, and metered usage via Azure Subscription ID. + +{% data variables.product.prodname_copilot_short %} standalone accounts, which traditionally used Azure Subscription IDs, can now also pay by credit card. Contact your {% data variables.product.github %} representative for details. + +## Unsupported Azure subscription types + +The following Azure subscription types cannot be used as a payment method for {% data variables.product.github %}: + +| Quota ID | Offer number(s) | +|---|---| +| `FreeTrial_2014-09-01` | MS-AZR-0044P | +| `AzureForStudents_2018-01-01` | MS-AZR-0170P | +| `DreamSpark_2015-02-01` | MS-AZR-0144P | +| `AzurePass_2014-09-01` | MS-AZR-0120P, MS-AZR-0122P–MS-AZR-0125P, MS-AZR-0128P–MS-AZR-0130P | +| `PayAsYouGo_2014-09-01` | MS-AZR-0017G | +| `Sponsored_2016-01-01` | MS-AZR-0036P | + +{% ifversion fpt or ghec %} + +## Usage-based billing availability + +{% data variables.product.github %} provides usage-based billing for the following products. + +* {% data variables.product.prodname_actions %}, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions) +* {% data variables.product.prodname_github_codespaces %}, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces) +* {% data variables.product.prodname_registry %}, see [AUTOTITLE](/billing/managing-billing-for-github-packages/about-billing-for-github-packages) +* {% data variables.large_files.product_name_long %}, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/about-billing-for-git-large-file-storage) + +In addition, usage-based billing is available for the following licenses: + +* {% data variables.product.prodname_enterprise %}, see [AUTOTITLE](/billing/managing-your-billing/about-billing-for-your-enterprise) +* {% data variables.product.prodname_copilot %}, see [AUTOTITLE](/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot) +* {% data variables.product.prodname_GHAS %}, see [AUTOTITLE](/billing/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security) + +For information about controlling spending, see [AUTOTITLE](/billing/managing-your-billing/using-budgets-control-spending). + +> [!NOTE] +> Prepaid usage is not currently available for usage-based billing through Azure. + +{% endif %} diff --git a/content/copilot/concepts/agents/cloud-agent/about-cloud-agent.md b/content/copilot/concepts/agents/cloud-agent/about-cloud-agent.md index 00211cc19994..7b6b2392b265 100644 --- a/content/copilot/concepts/agents/cloud-agent/about-cloud-agent.md +++ b/content/copilot/concepts/agents/cloud-agent/about-cloud-agent.md @@ -20,10 +20,9 @@ contentType: concepts category: - Learn about Copilot --- - - -## Overview of {% data variables.copilot.copilot_cloud_agent_tmp %} - + +## Overview of {% data variables.copilot.copilot_cloud_agent %} + With {% data variables.copilot.copilot_cloud_agent %}, {% data variables.product.prodname_copilot %} can work independently in the background to complete tasks, just like a human developer. {% data variables.copilot.copilot_cloud_agent %} can: @@ -137,7 +136,7 @@ You can customize {% data variables.copilot.copilot_cloud_agent %} in a number o * **Custom instructions**: Custom instructions allow you to give {% data variables.product.prodname_copilot_short %} additional context on your project and how to build, test and validate its changes. For more information, see [AUTOTITLE](/copilot/how-tos/configure-custom-instructions/add-repository-instructions). * **Model Context Protocol (MCP) servers**: MCP servers allow you to give {% data variables.product.prodname_copilot_short %} access to different data sources and tools. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/extend-cloud-agent-with-mcp). * **{% data variables.copilot.custom_agents_caps_short %}**: {% data variables.copilot.custom_agents_caps_short %} allow you to create different specialized versions of {% data variables.product.prodname_copilot_short %} for different tasks. For example, you could customize {% data variables.product.prodname_copilot_short %} to be an expert frontend engineer following your team's guidelines. For more information, see [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-custom-agents). -* **Hooks**: Hooks allow you to execute custom shell commands at key points during agent execution, enabling you to add validation, logging, security scanning, or workflow automation. For more information, see [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-hooks). +* **Hooks**: Hooks allow you to execute custom shell commands at key points during agent execution, enabling you to add validation, logging, security scanning, or workflow automation. For more information, see [AUTOTITLE](/copilot/concepts/agents/hooks). * **Skills**: Skills allow you to enhance the ability of {% data variables.product.prodname_copilot_short %} to perform specialized tasks with instructions, scripts, and resources. For more information, see [AUTOTITLE](/copilot/concepts/agents/about-agent-skills). ## Limitations of {% data variables.copilot.copilot_cloud_agent %} diff --git a/content/copilot/concepts/agents/cloud-agent/index.md b/content/copilot/concepts/agents/cloud-agent/index.md index db4f3f1ddbd2..6ff721642a8b 100644 --- a/content/copilot/concepts/agents/cloud-agent/index.md +++ b/content/copilot/concepts/agents/cloud-agent/index.md @@ -9,7 +9,6 @@ children: - /about-cloud-agent - /agent-management - /about-custom-agents - - /about-hooks - /access-management - /mcp-and-cloud-agent - /risks-and-mitigations diff --git a/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md b/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md index 90b1964a61b7..c195b6af9178 100644 --- a/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md +++ b/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md @@ -174,7 +174,7 @@ You can customize {% data variables.copilot.copilot_cli %} in a number of ways: * **Custom instructions**: Custom instructions allow you to give {% data variables.product.prodname_copilot_short %} additional context on your project and how to build, test and validate its changes. All custom instruction files now combine instead of using priority-based fallbacks. For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions). * **Model Context Protocol (MCP) servers**: MCP servers allow you to give {% data variables.product.prodname_copilot_short %} access to different data sources and tools. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/use-copilot-cli#add-an-mcp-server). * **{% data variables.copilot.custom_agents_caps_short %}**: {% data variables.copilot.custom_agents_caps_short %} allow you to create different specialized versions of {% data variables.product.prodname_copilot_short %} for different tasks. For example, you could customize {% data variables.product.prodname_copilot_short %} to be an expert frontend engineer following your team's guidelines. {% data variables.copilot.copilot_cli %} includes specialized {% data variables.copilot.custom_agents_short %} that it automatically delegates common tasks to. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/use-copilot-cli#use-custom-agents). -* **Hooks**: Hooks allow you to execute custom shell commands at key points during agent execution, enabling you to add validation, logging, security scanning, or workflow automation. See [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-hooks). +* **Hooks**: Hooks allow you to execute custom shell commands at key points during agent execution, enabling you to add validation, logging, security scanning, or workflow automation. See [AUTOTITLE](/copilot/concepts/agents/hooks). * **Skills**: Skills allow you to enhance the ability of {% data variables.product.prodname_copilot_short %} to perform specialized tasks with instructions, scripts, and resources. For more information, see [AUTOTITLE](/copilot/concepts/agents/about-agent-skills). * **{% data variables.copilot.copilot_memory %}**: {% data variables.copilot.copilot_memory %} allows {% data variables.product.prodname_copilot_short %} to build a persistent understanding of your repository by storing "memories", which are pieces of information about coding conventions, patterns, and preferences that {% data variables.product.prodname_copilot_short %} deduces as it works. This reduces the need to repeatedly explain context in your prompts and makes future sessions more productive. For more information, see [AUTOTITLE](/copilot/concepts/agents/copilot-memory). diff --git a/content/copilot/concepts/agents/copilot-cli/comparing-cli-features.md b/content/copilot/concepts/agents/copilot-cli/comparing-cli-features.md index 6f9f7ba7c228..c3bcc0f5df07 100644 --- a/content/copilot/concepts/agents/copilot-cli/comparing-cli-features.md +++ b/content/copilot/concepts/agents/copilot-cli/comparing-cli-features.md @@ -271,8 +271,7 @@ Avoid hooks when: See: * [AUTOTITLE](/copilot/how-tos/copilot-cli/use-hooks) -* [AUTOTITLE](/copilot/reference/hooks-configuration) -* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-hooks-reference) +* [AUTOTITLE](/copilot/reference/hooks-reference) ## Subagents diff --git a/content/copilot/concepts/agents/cloud-agent/about-hooks.md b/content/copilot/concepts/agents/hooks.md similarity index 82% rename from content/copilot/concepts/agents/cloud-agent/about-hooks.md rename to content/copilot/concepts/agents/hooks.md index 3fb93d93bcdf..b993ec38ac93 100644 --- a/content/copilot/concepts/agents/cloud-agent/about-hooks.md +++ b/content/copilot/concepts/agents/hooks.md @@ -1,8 +1,7 @@ --- -title: About hooks +title: About hooks for {% data variables.product.prodname_copilot %} shortTitle: Hooks intro: 'Extend and customize {% data variables.product.prodname_copilot %} agent behavior by executing custom shell commands at key points during agent execution.' -product: '{% data reusables.gated-features.copilot-cloud-agent %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' versions: feature: copilot contentType: concepts @@ -10,24 +9,26 @@ category: - Configure Copilot redirect_from: - /copilot/concepts/agents/coding-agent/about-hooks + - /copilot/concepts/agents/cloud-agent/about-hooks + - /copilot/concepts/agents/about-hooks --- -## About hooks +## What are hooks? -Hooks enable you to execute custom shell commands at strategic points in an agent's workflow, such as when an agent session starts or ends, or before and after a prompt is entered or a tool is called. +Hooks are a way of executing custom shell commands at strategic points in an agent's workflow, such as when an agent session starts or ends, when you enter a prompt, or when a tool is called. Hooks receive detailed information about agent actions via JSON input, enabling context-aware automation. For example, you can use hooks to: * Programmatically approve or deny tool executions. -* Utilize built-in security features like secret scanning to prevent credential leaks. +* Use built-in security features like secret scanning to prevent credential leaks. * Implement custom validation rules and audit logging for compliance. -{% data variables.product.prodname_copilot_short %} agents support hooks stored in JSON files in your repository at `.github/hooks/*.json`. - Hooks are available for use with: -* {% data variables.copilot.copilot_cloud_agent %} on {% data variables.product.github %} -* {% data variables.copilot.copilot_cli %} in the terminal +* **{% data variables.copilot.copilot_cloud_agent %}** on {% data variables.product.github %}. +* **{% data variables.copilot.copilot_cli %}** in your terminal. + +You define hooks in JSON files, stored in your repository at `.github/hooks/*.json`. These apply whenever {% data variables.product.prodname_copilot_short %} agents are used in the repository. {% data variables.copilot.copilot_cli_short %} also supports personal hooks that you store in your home directory at `~/.copilot/hooks/*.json`. These apply whenever you use {% data variables.copilot.copilot_cli_short %}. ## Types of hooks @@ -42,7 +43,7 @@ The following types of hooks are available: * **subagentStop**: Executed when a subagent completes, before returning results to the parent agent. * **errorOccurred**: Executed when an error occurs during agent execution. Can be used to log errors for debugging, send notifications, track error patterns, and generate reports. -To see a complete reference of hook types with example use cases, best practices, and advanced patterns, see [AUTOTITLE](/copilot/reference/hooks-configuration). +To see a complete reference of hook types with example use cases, best practices, and advanced patterns, see [AUTOTITLE](/copilot/reference/hooks-reference). ## Hook configuration format @@ -162,4 +163,6 @@ To ensure security is maintained when using hooks, keep the following considerat ## Next steps -To start creating hooks, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/use-hooks). +To start creating hooks, see: +* [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/use-hooks) for {% data variables.copilot.copilot_cloud_agent %} +* [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/use-hooks) for {% data variables.copilot.copilot_cli %} diff --git a/content/copilot/concepts/agents/index.md b/content/copilot/concepts/agents/index.md index 5676dbda0475..2e6b1bb06b5e 100644 --- a/content/copilot/concepts/agents/index.md +++ b/content/copilot/concepts/agents/index.md @@ -10,6 +10,7 @@ children: - /copilot-cli - /code-review - /copilot-memory + - /hooks - /about-third-party-agents - /openai-codex - /anthropic-claude diff --git a/content/copilot/get-started/features.md b/content/copilot/get-started/features.md index 98b638ae6661..c8b130979952 100644 --- a/content/copilot/get-started/features.md +++ b/content/copilot/get-started/features.md @@ -45,7 +45,7 @@ These features can work autonomously without direct human supervision. However, A command line interface that lets you use {% data variables.product.prodname_copilot_short %} in your terminal. Use the CLI to add features or fix bugs, then create a pull request. Start {% data variables.product.prodname_copilot_short %} working on a task in your terminal, then continue working in the same session on {% data variables.product.prodname_dotcom_the_website %}, or on your mobile. See [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli). -### {% data variables.copilot.copilot_cloud_agent_tmp %} +### {% data variables.copilot.copilot_cloud_agent %} An autonomous AI agent that can research a repository, create an implementation plan, and make code changes on a branch. You can review the diff, iterate, and create a pull request when you're ready. You can also assign a {% data variables.product.github %} issue to {% data variables.product.prodname_copilot_short %} or ask it to open a pull request directly to complete a task. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent). diff --git a/content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies.md b/content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies.md index 6cfcaef15fb5..92009e2dd881 100644 --- a/content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies.md +++ b/content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies.md @@ -19,6 +19,8 @@ category: When an organization owner assigns a {% data variables.product.prodname_copilot_short %} license to a member of their organization, the availability of features and models is controlled by policies. +If you're setting up {% data variables.product.prodname_copilot_short %} for the first time, see [AUTOTITLE](/copilot/tutorials/roll-out-at-scale/govern-for-adoption) for guidance on setting a governance posture that balances compliance with developer productivity. + ## Defining policies for your enterprise Enterprise owners can define a policy for the whole enterprise, or delegate the decision to individual organization owners. See [AUTOTITLE](/copilot/concepts/policies). diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/use-hooks.md b/content/copilot/how-tos/copilot-cli/customize-copilot/use-hooks.md index b3e883d7b3f9..75ec1a7dcefe 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/use-hooks.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/use-hooks.md @@ -16,18 +16,95 @@ docsTeamMetrics: {% data reusables.copilot.cloud-agent.hooks-intro %} -## Creating a hook in a repository on {% data variables.product.github %} +## Prerequisite + +**For Windows only:** The examples in this article use PowerShell. If you're using Windows, you must have PowerShell 7.0 or later installed and in your PATH. You can check your PowerShell version by running `pwsh --version` in a terminal. To install PowerShell, run `winget install Microsoft.PowerShell` then restart your terminal. + +## Creating a repository-level hook + +1. Create a new `NAME.json` file (where `NAME` describes the purpose of the file) in the `.github/hooks/` folder of your repository. {% data reusables.copilot.cloud-agent.create-hooks-instructions %} +## Creating a user-level hook + +User-level hooks are configured just like repository-level hooks, but the hook files are stored locally, below your home directory. + +The following examples for macOS and Windows show how to configure hooks that will play a sound and display a message box when the CLI finishes responding to a prompt, and when you quit {% data variables.copilot.copilot_cli_short %}. Hooks for Linux would be similar to the macOS example, but would use Linux tools for playing sounds and displaying messages. + +### User-level example for macOS + +1. Create a file called `notification-hooks.json` in `~/.copilot/hooks/`. + + > [!NOTE] + > If `COPILOT_HOME` is set, create the file in `$COPILOT_HOME/hooks/`. + +1. Copy and paste the following JSON into the file: + + ```json copy + { + "version": 1, + "hooks": { + "agentStop": [ + { + "type": "command", + "bash": "osascript -e 'do shell script \"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\"' -e 'display dialog \"Agent stopped.\" with title \"Hook-generated message\" buttons {\"OK\"} default button \"OK\"'", + "timeoutSec": 5 + } + ], + "sessionEnd": [ + { + "type": "command", + "bash": "osascript -e 'do shell script \"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\"' -e 'display dialog \"Session ended.\" with title \"Hook-generated message\" buttons {\"OK\"} default button \"OK\"'", + "timeoutSec": 5 + } + ] + } + } + ``` + +{% data reusables.copilot.cloud-agent.hooks-example-steps %} + +### User-level example for Windows + +1. Create a file called `notification-hooks.json` in `%USERPROFILE%\.copilot\hooks\`. + + > [!NOTE] + > If `COPILOT_HOME` is set, create the file in `%COPILOT_HOME%\hooks\`. + +1. Copy and paste the following JSON into the file: + + ```json copy + { + "version": 1, + "hooks": { + "agentStop": [ + { + "type": "command", + "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Agent stopped.', 'Hook-generated message') | Out-Null", + "timeoutSec": 5 + } + ], + "sessionEnd": [ + { + "type": "command", + "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Session ended.', 'Hook-generated message') | Out-Null", + "timeoutSec": 5 + } + ] + } + } + ``` + +{% data reusables.copilot.cloud-agent.hooks-example-steps %} + ## Troubleshooting {% data reusables.copilot.cloud-agent.troubleshoot-hooks %} ## Further reading -* [AUTOTITLE](/copilot/reference/hooks-configuration) +* [AUTOTITLE](/copilot/reference/hooks-reference) * [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-cloud-agent) * [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli) * [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment) -* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-hooks-reference) diff --git a/content/copilot/how-tos/copilot-cli/index.md b/content/copilot/how-tos/copilot-cli/index.md index 76ef7c09f1a4..25e6f72c3b09 100644 --- a/content/copilot/how-tos/copilot-cli/index.md +++ b/content/copilot/how-tos/copilot-cli/index.md @@ -42,7 +42,7 @@ children: - /content/copilot/reference/copilot-cli-reference/cli-command-reference - /content/copilot/reference/copilot-cli-reference/cli-plugin-reference - /content/copilot/reference/copilot-cli-reference/cli-programmatic-reference - - /content/copilot/reference/hooks-configuration + - /content/copilot/reference/hooks-reference - /content/copilot/responsible-use/copilot-cli - /content/copilot/tutorials/copilot-cli-hooks - /customize-copilot/add-custom-instructions diff --git a/content/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks.md b/content/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks.md index bbbf6e24174a..5f016053b058 100644 --- a/content/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks.md +++ b/content/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks.md @@ -5,7 +5,7 @@ intro: 'Run automated checks—like linting, formatting, or security scans—at versions: feature: copilot contentType: how-tos -category: +category: - Configure Copilot redirect_from: - /copilot/how-tos/use-copilot-agents/coding-agent/use-hooks @@ -16,6 +16,11 @@ redirect_from: ## Creating a hook in a repository on {% data variables.product.github %} +1. Create a new `NAME.json` file (where `NAME` describes the purpose of the file) in the `.github/hooks/` folder of your repository. + + > [!IMPORTANT] + > The hooks configuration file **must be present** on your repository's default branch to be used by {% data variables.copilot.copilot_cloud_agent %}. + {% data reusables.copilot.cloud-agent.create-hooks-instructions %} ## Troubleshooting @@ -24,7 +29,7 @@ redirect_from: ## Further reading -* [AUTOTITLE](/copilot/reference/hooks-configuration) +* [AUTOTITLE](/copilot/reference/hooks-reference) * [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-cloud-agent) * [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli) * [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment) diff --git a/content/copilot/how-tos/copilot-on-github/use-copilot-agents/research-plan-iterate.md b/content/copilot/how-tos/copilot-on-github/use-copilot-agents/research-plan-iterate.md index 90d163bafecd..2429cb16b921 100644 --- a/content/copilot/how-tos/copilot-on-github/use-copilot-agents/research-plan-iterate.md +++ b/content/copilot/how-tos/copilot-on-github/use-copilot-agents/research-plan-iterate.md @@ -15,7 +15,7 @@ redirect_from: - /copilot/how-tos/use-copilot-agents/cloud-agent/provide-visual-inputs --- -{% data variables.copilot.copilot_cloud_agent_tmp %} lets you: +{% data variables.copilot.copilot_cloud_agent %} lets you: * **Research** a repository by asking {% data variables.product.prodname_copilot_short %} questions. * **Plan** and refine an approach before {% data variables.product.prodname_copilot_short %} makes changes. @@ -43,7 +43,7 @@ Ask {% data variables.copilot.copilot_cloud_agent %} questions about a repositor Ask {% data variables.copilot.copilot_cloud_agent %} to propose a plan before making changes. 1. Describe the plan you want. - + For example: `Create a plan to implement the most impactful performance improvements for this app.` 1. Review the plan and iterate with {% data variables.product.prodname_copilot_short %} until it matches your intent. diff --git a/content/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions.md b/content/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions.md index 1ce6c73b724f..7ae47acc9687 100644 --- a/content/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions.md +++ b/content/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions.md @@ -44,6 +44,7 @@ You can start {% data variables.copilot.copilot_cloud_agent %} from: * Your preferred IDE or agentic coding tool with [Model Context Protocol (MCP)](#asking-copilot-to-create-a-pull-request-from-the-github-mcp-server) support * The [Raycast](#asking-copilot-to-create-a-pull-request-from-raycast) launcher * The ["New repository" form](#asking-copilot-to-create-a-pull-request-from-the-new-repository-page) on {% data variables.product.github %} +* A failing [{% data variables.product.prodname_actions %} workflow run](#asking-copilot-to-fix-a-failing-github-actions-workflow-run) on {% data variables.product.github %} * [Jira](/copilot/how-tos/use-copilot-agents/cloud-agent/integrate-cloud-agent-with-jira) * [Slack](/copilot/how-tos/use-copilot-agents/cloud-agent/integrate-cloud-agent-with-slack) * [Microsoft Teams](/copilot/how-tos/use-copilot-agents/cloud-agent/integrate-cloud-agent-with-teams) @@ -651,6 +652,18 @@ When creating a new repository, you can ask {% data variables.product.prodname_c {% data reusables.copilot.cloud-agent.monitoring-progress-heading %} +## Asking {% data variables.product.prodname_copilot_short %} to fix a failing {% data variables.product.prodname_actions %} workflow run + +> [!NOTE] +> This feature is only available to {% data variables.copilot.copilot_business_short %} and {% data variables.copilot.copilot_enterprise_short %} users. + +When an {% data variables.product.prodname_actions %} workflow run fails on a pull request branch, you can ask {% data variables.product.prodname_copilot_short %} to investigate and fix the failure. + +1. On {% data variables.product.github %}, navigate to the failing workflow run job page. +1. Click the **{% octicon "agent" aria-label="The Agents icon" %} Fix with {% data variables.product.prodname_copilot_short %}** button. + + {% data variables.product.prodname_copilot_short %} will start a new session, investigate the cause of the failure, and push a fix to your branch. + ## Further reading * [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-cloud-agent) diff --git a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md index 59eeb3b06f51..3533ab8b993f 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md @@ -419,7 +419,7 @@ For more information, see [AUTOTITLE](/copilot/how-tos/configure-custom-instruct ## Hooks reference -For detailed information about hooks—including hook configuration formats, hook events, input payloads, and decision control—see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-hooks-reference). +For detailed information about hooks—including hook configuration formats, hook events, input payloads, and decision control—see [AUTOTITLE](/copilot/reference/hooks-reference). ## MCP server configuration @@ -711,7 +711,7 @@ Use `/permissions reset` to clear in-memory approvals for the current session. ## OpenTelemetry monitoring -{% data variables.copilot.copilot_cli_short %} can export traces and metrics via [OpenTelemetry](https://opentelemetry.io/) (OTel), giving you visibility into agent interactions, LLM calls, tool executions, and token usage. All signal names and attributes follow the [OTel GenAI Semantic Conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/). +{% data variables.copilot.copilot_cli_short %} can export traces and metrics via [OpenTelemetry](https://opentelemetry.io/) (OTel), giving you visibility into agent interactions, LLM calls, tool executions, and token usage. All signal names and attributes follow the [OTel GenAI Semantic Conventions](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai/). OTel is off by default with zero overhead. It activates when any of the following conditions are met: @@ -886,7 +886,7 @@ When content capture is enabled, the following attributes are populated. ## Further reading * [AUTOTITLE](/copilot/how-tos/copilot-cli) -* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-hooks-reference) +* [AUTOTITLE](/copilot/reference/hooks-reference) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-programmatic-reference) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference) diff --git a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md index c6344db831de..efbad98dc645 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md @@ -36,6 +36,7 @@ The `~/.copilot` directory contains the following top-level items. | `permissions-config.json` | File | Saved tool and directory permissions per project | | `plugin-data/` | Directory | Persistent data for installed plugins | | `session-state/` | Directory | Session history and workspace data | +| `command-history-state/` | Directory | Command history data | | `session-store.db` | File | SQLite database for cross-session data | | `settings.json` | File | Your personal configuration settings | | `skills/` | Directory | Personal custom skill definitions | @@ -121,6 +122,10 @@ Stores your saved tool and directory permission decisions, organized by project Contains session history data, organized by session ID in subdirectories. Each session directory stores an event log (`events.jsonl`) and workspace artifacts (plans, checkpoints, tracked files). This data enables session resume (`--resume` or `--continue`). +### `command-history-state/` + +Contains command history data used for reverse search (Ctrl+R) and history navigation in the interactive interface. This directory is managed automatically and should not be edited. + ### `session-store.db` A SQLite database used by the CLI for cross-session data such as checkpoint indexing and search. This file is automatically managed and should not be edited. @@ -179,6 +184,7 @@ To override the default `~/.copilot` location, set the `COPILOT_HOME` environmen | `permissions-config.json` | With caution | Resets all saved permissions. The CLI will prompt you again for tool and directory approvals. | | `plugin-data/` | Yes | Plugin persistent data is re-created as needed. | | `session-state/` | With caution | Deleting removes session history. You will no longer be able to resume past sessions. | +| `command-history-state/` | With caution | Deleting removes command history. You will no longer be able to search previous commands with Ctrl+R. | | `session-store.db` | With caution | Deleting removes cross-session data. The file is re-created automatically. | | `settings.json` | With caution | Resets all user preferences to defaults. You will need to reconfigure your settings. | @@ -230,7 +236,7 @@ These settings apply across all your sessions and repositories. You can edit thi | `mergeStrategy` | `"rebase"` \| `"merge"` | — | Conflict resolution strategy for `/pr fix conflicts`. When set to `"rebase"`, conflicts are resolved by rebasing onto the base branch. When set to `"merge"`, the base branch is merged into the feature branch. If not configured, a picker dialog is shown. | | `model` | `string` | varies | AI model to use. Set to `"auto"` to let {% data variables.product.prodname_copilot_short %} pick the best available model automatically. Managed by the `/model` slash command. | | `mouse` | `boolean` | `true` | Enable mouse support in alt screen mode. Can also be set with `--mouse` or `--no-mouse`. | -| `powershellFlags` | `string[]` | `["-NoProfile", "-NoLogo"]` | Flags passed to PowerShell (`pwsh`) on startup. Windows only. | +| `powershellFlags` | `string[]` | `["-NoProfile", "-NoLogo"]` | Flags passed to PowerShell on startup. On Windows, the CLI prefers PowerShell 7+ (`pwsh`) and falls back to Windows PowerShell (`powershell.exe`) when `pwsh` is unavailable. Windows only. | | `renderMarkdown` | `boolean` | `true` | Render Markdown in terminal output. | | `respectGitignore` | `boolean` | `true` | Exclude gitignored files from the `@` file mention picker. When `false`, the picker includes files normally excluded by `.gitignore`. | | `screenReader` | `boolean` | `false` | Enable screen reader optimizations. | @@ -269,4 +275,4 @@ The local configuration file uses the same schema as the repository configuratio * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-programmatic-reference) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference) -* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-hooks-reference) +* [AUTOTITLE](/copilot/reference/hooks-reference) diff --git a/content/copilot/reference/copilot-cli-reference/index.md b/content/copilot/reference/copilot-cli-reference/index.md index f8fdffce2470..a763d0c872ff 100644 --- a/content/copilot/reference/copilot-cli-reference/index.md +++ b/content/copilot/reference/copilot-cli-reference/index.md @@ -6,7 +6,6 @@ versions: feature: copilot children: - /cli-command-reference - - /cli-hooks-reference - /cli-plugin-reference - /cli-programmatic-reference - /acp-server diff --git a/content/copilot/reference/customization-cheat-sheet.md b/content/copilot/reference/customization-cheat-sheet.md index e378d1811041..908cdb5baeab 100644 --- a/content/copilot/reference/customization-cheat-sheet.md +++ b/content/copilot/reference/customization-cheat-sheet.md @@ -22,7 +22,7 @@ This table shows what each customization feature is and where it lives. | [{% data variables.copilot.custom_agents_caps_short %}](/copilot/concepts/agents/cloud-agent/about-custom-agents) | Specialist persona with its own instructions, tool restrictions, and context | `.github/agents/AGENT-NAME.md` (repo), `agents/AGENT-NAME.md` in `.github-private` repo (org/enterprise), or user profile | | [{% data variables.copilot.subagents_caps_short %}](/copilot/how-tos/chat-with-copilot/chat-in-ide#using-subagents) | Separate agent spawned by the main agent to handle delegated work in an isolated context | N/A (runtime process, not a user-configured file) | | [Agent skills](/copilot/concepts/agents/about-agent-skills) | Folder of instructions, scripts, and resources that {% data variables.product.prodname_copilot_short %} loads when relevant to a task | `.github/skills//SKILL.md`, `.claude/skills//SKILL.md`, or `.agents/skills//SKILL.md` (project); `~/.copilot/skills//SKILL.md` or `~/.agents/skills//SKILL.md` (personal) | -| [Hooks](/copilot/concepts/agents/cloud-agent/about-hooks) | Custom shell commands that execute deterministically at specific points in an agent's workflow | `.github/hooks/*.json` | +| [Hooks](/copilot/concepts/agents/hooks) | Custom shell commands that execute deterministically at specific points in an agent's workflow | `.github/hooks/*.json` | | [MCP servers](/copilot/concepts/context/mcp) | Connection to external systems, APIs, and databases | `mcp.json` (path varies by IDE), repo settings on {% data variables.product.github %} ({% data variables.copilot.copilot_cloud_agent_short %}), or `mcp-servers` property in {% data variables.copilot.copilot_custom_agent_short %} configurations | ## Usage comparison @@ -36,7 +36,7 @@ This table helps you decide which customization feature to use. | [{% data variables.copilot.custom_agents_caps_short %}](/copilot/concepts/agents/cloud-agent/about-custom-agents) | Manual: select from the agent dropdown in your IDE, on {% data variables.product.github %}, or in {% data variables.copilot.copilot_cli_short %} | Projects or processes with distinct stages that need specialized capabilities or strict handoffs | React reviewer agent, read-only auditing agent | | [{% data variables.copilot.subagents_caps_short %}](/copilot/how-tos/chat-with-copilot/chat-in-ide#using-subagents) | Automatic, or reference a {% data variables.copilot.subagent_short %} directly in your prompt | Complex subtasks that should run in isolation from the main agent | Codebase research, running test suites | | [Agent skills](/copilot/concepts/agents/about-agent-skills) | Automatic: chosen by {% data variables.product.prodname_copilot_short %} when relevant to your prompt | Multi-step workflows with bundled assets that should be loaded as needed | {% data variables.product.prodname_actions %} failure debugging, deployment procedures, release note drafting | -| [Hooks](/copilot/concepts/agents/cloud-agent/about-hooks) | Automatic: at configured lifecycle events | Tasks that need to run at a specific point in the agent lifecycle, with guaranteed execution | Run a formatter after every file edit, approve or deny tool executions, prevent credential leaks with {% data variables.product.prodname_secret_scanning %} | +| [Hooks](/copilot/concepts/agents/hooks) | Automatic: at configured lifecycle events | Tasks that need to run at a specific point in the agent lifecycle, with guaranteed execution | Run a formatter after every file edit, approve or deny tool executions, prevent credential leaks with {% data variables.product.prodname_secret_scanning %} | | [MCP servers](/copilot/concepts/context/mcp) | Automatic, or ask for a specific tool by name | Tasks that require access to external tools or real-time data | Manage issues and PRs ({% data variables.product.github %} MCP server), automate browser testing (Playwright MCP server) | ## IDE and surface support diff --git a/content/copilot/reference/hooks-configuration.md b/content/copilot/reference/hooks-configuration.md deleted file mode 100644 index 01f92494d5ef..000000000000 --- a/content/copilot/reference/hooks-configuration.md +++ /dev/null @@ -1,557 +0,0 @@ ---- -title: Hooks configuration -shortTitle: Hooks configuration -intro: 'Find information about configuring hooks for use with {% data variables.copilot.copilot_cli %} and {% data variables.copilot.copilot_cloud_agent %}.' -versions: - feature: copilot -contentType: reference -category: - - Configure Copilot - - Configure Copilot CLI ---- - -This reference article describes the available hook types with examples, including their input and output formats, script best practices, and advanced patterns for logging, security enforcement, and external integrations. For general information about creating hooks, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/use-hooks). For a tutorial on creating hooks for the CLI, see [AUTOTITLE](/copilot/tutorials/copilot-cli-hooks). - -## Hook types - -### Session start hook - -Executed when a new agent session begins or when resuming an existing session. - -**Input JSON:** - -```json copy -{ - "timestamp": 1704614400000, - "cwd": "/path/to/project", - "source": "new", - "initialPrompt": "Create a new feature" -} -``` - -**Fields:** - -* `timestamp`: Unix timestamp in milliseconds -* `cwd`: Current working directory -* `source`: Either `"new"` (new session), `"resume"` (resumed session), or `"startup"` -* `initialPrompt`: The user's initial prompt (if provided) - -**Output:** Ignored (no return value processed) - -**Example hook:** - -```json copy -{ - "type": "command", - "bash": "./scripts/session-start.sh", - "powershell": "./scripts/session-start.ps1", - "cwd": "scripts", - "timeoutSec": 30 -} -``` - -**Example script (Bash):** - -```shell copy -#!/bin/bash -INPUT=$(cat) -SOURCE=$(echo "$INPUT" | jq -r '.source') -TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp') - -echo "Session started from $SOURCE at $TIMESTAMP" >> session.log -``` - -### Session end hook - -Executed when the agent session completes or is terminated. - -**Input JSON:** - -```json copy -{ - "timestamp": 1704618000000, - "cwd": "/path/to/project", - "reason": "complete" -} -``` - -**Fields:** - -* `timestamp`: Unix timestamp in milliseconds -* `cwd`: Current working directory -* `reason`: One of `"complete"`, `"error"`, `"abort"`, `"timeout"`, or `"user_exit"` - -**Output:** Ignored - -**Example script:** - -```shell copy -#!/bin/bash -INPUT=$(cat) -REASON=$(echo "$INPUT" | jq -r '.reason') - -echo "Session ended: $REASON" >> session.log -# Cleanup temporary files -rm -rf /tmp/session-* -``` - -### User prompt submitted hook - -Executed when the user submits a prompt to the agent. - -**Input JSON:** - -```json copy -{ - "timestamp": 1704614500000, - "cwd": "/path/to/project", - "prompt": "Fix the authentication bug" -} -``` - -**Fields:** - -* `timestamp`: Unix timestamp in milliseconds -* `cwd`: Current working directory -* `prompt`: The exact text the user submitted - -**Output:** Ignored (prompt modification not currently supported in customer hooks) - -**Example script:** - -```shell copy -#!/bin/bash -INPUT=$(cat) -PROMPT=$(echo "$INPUT" | jq -r '.prompt') -TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp') - -# Log to a structured file -echo "$(date -d @$((TIMESTAMP/1000))): $PROMPT" >> prompts.log -``` - -### Pre-tool use hook - -Executed before the agent uses any tool (such as `bash`, `edit`, `view`). This is the most powerful hook as it can **approve or deny tool executions**. - -**Input JSON:** - -```json copy -{ - "timestamp": 1704614600000, - "cwd": "/path/to/project", - "toolName": "bash", - "toolArgs": "{\"command\":\"rm -rf dist\",\"description\":\"Clean build directory\"}" -} -``` - -**Fields:** - -* `timestamp`: Unix timestamp in milliseconds -* `cwd`: Current working directory -* `toolName`: Name of the tool being invoked (such as "bash", "edit", "view", "create") -* `toolArgs`: JSON string containing the tool's arguments - -**Output JSON (optional):** - -```json copy -{ - "permissionDecision": "deny", - "permissionDecisionReason": "Destructive operations require approval" -} -``` - -**Output fields:** - -* `permissionDecision`: Either `"allow"`, `"deny"`, or `"ask"` (only `"deny"` is currently processed) -* `permissionDecisionReason`: Human-readable explanation for the decision - -**Example hook to block dangerous commands:** - -```shell copy -#!/bin/bash -INPUT=$(cat) -TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName') -TOOL_ARGS=$(echo "$INPUT" | jq -r '.toolArgs') - -# Log the tool use -echo "$(date): Tool=$TOOL_NAME Args=$TOOL_ARGS" >> tool-usage.log - -# Check for dangerous patterns -if echo "$TOOL_ARGS" | grep -qE "rm -rf /|format|DROP TABLE"; then - echo '{"permissionDecision":"deny","permissionDecisionReason":"Dangerous command detected"}' - exit 0 -fi - -# Allow by default (or omit output to allow) -echo '{"permissionDecision":"allow"}' -``` - -**Example hook to enforce file permissions:** - -```shell copy -#!/bin/bash -INPUT=$(cat) -TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName') - -# Only allow editing specific directories -if [ "$TOOL_NAME" = "edit" ]; then - PATH_ARG=$(echo "$INPUT" | jq -r '.toolArgs' | jq -r '.path') - - if [[ ! "$PATH_ARG" =~ ^(src/|test/) ]]; then - echo '{"permissionDecision":"deny","permissionDecisionReason":"Can only edit files in src/ or test/ directories"}' - exit 0 - fi -fi - -# Allow all other tools -``` - -### Post-tool use hook - -Executed after a tool completes execution (whether successful or failed). - -**Example input JSON:** - -```json copy -{ - "timestamp": 1704614700000, - "cwd": "/path/to/project", - "toolName": "bash", - "toolArgs": "{\"command\":\"npm test\"}", - "toolResult": { - "resultType": "success", - "textResultForLlm": "All tests passed (15/15)" - } -} -``` - -**Fields:** - -* `timestamp`: Unix timestamp in milliseconds -* `cwd`: Current working directory -* `toolName`: Name of the tool that was executed -* `toolArgs`: JSON string containing the tool's arguments -* `toolResult`: Result object containing: - * `resultType`: Either `"success"`, `"failure"`, or `"denied"` - * `textResultForLlm`: The result text shown to the agent - -**Output:** Ignored (result modification is not currently supported) - -**Example script that logs tool execution statistics to a CSV file:** - -This script logs tool execution statistics to a CSV file and sends an email alert when a tool fails. - -```shell copy -#!/bin/bash -INPUT=$(cat) -TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName') -RESULT_TYPE=$(echo "$INPUT" | jq -r '.toolResult.resultType') - -# Track statistics -echo "$(date),${TOOL_NAME},${RESULT_TYPE}" >> tool-stats.csv - -# Alert on failures -if [ "$RESULT_TYPE" = "failure" ]; then - RESULT_TEXT=$(echo "$INPUT" | jq -r '.toolResult.textResultForLlm') - echo "FAILURE: $TOOL_NAME - $RESULT_TEXT" | mail -s "Agent Tool Failed" admin@example.com -fi -``` - -### Error occurred hook - -Executed when an error occurs during agent execution. - -**Example input JSON:** - -```json copy -{ - "timestamp": 1704614800000, - "cwd": "/path/to/project", - "error": { - "message": "Network timeout", - "name": "TimeoutError", - "stack": "TimeoutError: Network timeout\n at ..." - } -} -``` - -**Fields:** - -* `timestamp`: Unix timestamp in milliseconds -* `cwd`: Current working directory -* `error`: Error object containing: - * `message`: Error message - * `name`: Error type/name - * `stack`: Stack trace (if available) - -**Output:** Ignored (error handling modification is not currently supported) - -**Example script that extracts error details to a log file:** - -```shell copy -#!/bin/bash -INPUT=$(cat) -ERROR_MSG=$(echo "$INPUT" | jq -r '.error.message') -ERROR_NAME=$(echo "$INPUT" | jq -r '.error.name') - -echo "$(date): [$ERROR_NAME] $ERROR_MSG" >> errors.log -``` - -## Script best practices - -### Reading input - -This example script reads JSON input from stdin into a variable, then uses `jq` to extract the `timestamp` and `cwd` fields. - -**Bash:** - -```shell copy -#!/bin/bash -# Read JSON from stdin -INPUT=$(cat) - -# Parse with jq -TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp') -CWD=$(echo "$INPUT" | jq -r '.cwd') -``` - -**PowerShell:** - -```powershell copy -# Read JSON from stdin -$input = [Console]::In.ReadToEnd() | ConvertFrom-Json - -# Access properties -$timestamp = $input.timestamp -$cwd = $input.cwd -``` - -### Outputting JSON - -This example script shows how to output valid JSON from your hook script. Use `jq -c` in Bash for compact single-line output, or `ConvertTo-Json -Compress` in PowerShell. - -**Bash:** - -```shell copy -#!/bin/bash -# Use jq to compact the JSON output to a single line -echo '{"permissionDecision":"deny","permissionDecisionReason":"Security policy violation"}' | jq -c - -# Or construct with variables -REASON="Too dangerous" -jq -n --arg reason "$REASON" '{permissionDecision: "deny", permissionDecisionReason: $reason}' -``` - -**PowerShell:** - -```powershell copy -# Use ConvertTo-Json to compact the JSON output to a single line -$output = @{ - permissionDecision = "deny" - permissionDecisionReason = "Security policy violation" -} -$output | ConvertTo-Json -Compress -``` - -### Error handling - -This script example demonstrates how to handle errors in hook scripts. - -**Bash:** - -```shell copy -#!/bin/bash -set -e # Exit on error - -INPUT=$(cat) -# ... process input ... - -# Exit with 0 for success -exit 0 -``` - -**PowerShell:** - -```powershell copy -$ErrorActionPreference = "Stop" - -try { - $input = [Console]::In.ReadToEnd() | ConvertFrom-Json - # ... process input ... - exit 0 -} catch { - Write-Error $_.Exception.Message - exit 1 -} -``` - -### Handling timeouts - -Hooks have a default timeout of 30 seconds. For longer operations, increase `timeoutSec`: - -```json copy -{ - "type": "command", - "bash": "./scripts/slow-validation.sh", - "timeoutSec": 120 -} -``` - -## Advanced patterns - -### Multiple hooks of the same type - -You can define multiple hooks for the same event. They execute in order: - -```json copy -{ - "version": 1, - "hooks": { - "preToolUse": [ - { - "type": "command", - "bash": "./scripts/security-check.sh", - "comment": "Security validation - runs first" - }, - { - "type": "command", - "bash": "./scripts/audit-log.sh", - "comment": "Audit logging - runs second" - }, - { - "type": "command", - "bash": "./scripts/metrics.sh", - "comment": "Metrics collection - runs third" - } - ] - } -} -``` - -### Conditional logic in scripts - -**Example: Only block specific tools** - -```shell copy -#!/bin/bash -INPUT=$(cat) -TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName') - -# Only validate bash commands -if [ "$TOOL_NAME" != "bash" ]; then - exit 0 # Allow all non-bash tools -fi - -# Check bash command for dangerous patterns -COMMAND=$(echo "$INPUT" | jq -r '.toolArgs' | jq -r '.command') -if echo "$COMMAND" | grep -qE "rm -rf|sudo|mkfs"; then - echo '{"permissionDecision":"deny","permissionDecisionReason":"Dangerous system command"}' -fi -``` - -### Structured logging - -**Example: JSON Lines format** - -```shell copy -#!/bin/bash -INPUT=$(cat) -TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp') -TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName') -RESULT_TYPE=$(echo "$INPUT" | jq -r '.toolResult.resultType') - -# Output structured log entry -jq -n \ - --arg ts "$TIMESTAMP" \ - --arg tool "$TOOL_NAME" \ - --arg result "$RESULT_TYPE" \ - '{timestamp: $ts, tool: $tool, result: $result}' >> logs/audit.jsonl -``` - -### Integration with external systems - -**Example: Send alerts to Slack** - -```shell copy -#!/bin/bash -INPUT=$(cat) -ERROR_MSG=$(echo "$INPUT" | jq -r '.error.message') - -WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL" - -curl -X POST "$WEBHOOK_URL" \ - -H 'Content-Type: application/json' \ - -d "{\"text\":\"Agent Error: $ERROR_MSG\"}" -``` - -## Example use cases - -### Compliance audit trail - -Log all agent actions for compliance requirements by utilizing log scripts: - -```json copy -{ - "version": 1, - "hooks": { - "sessionStart": [{"type": "command", "bash": "./audit/log-session-start.sh"}], - "userPromptSubmitted": [{"type": "command", "bash": "./audit/log-prompt.sh"}], - "preToolUse": [{"type": "command", "bash": "./audit/log-tool-use.sh"}], - "postToolUse": [{"type": "command", "bash": "./audit/log-tool-result.sh"}], - "sessionEnd": [{"type": "command", "bash": "./audit/log-session-end.sh"}] - } -} -``` - -### Cost tracking - -Track tool usage for cost allocation: - -```shell copy -#!/bin/bash -INPUT=$(cat) -TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName') -TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp') -USER=${USER:-unknown} - -echo "$TIMESTAMP,$USER,$TOOL_NAME" >> /var/log/copilot/usage.csv -``` - -### Code quality enforcement - -Prevent commits that violate code standards: - -```shell copy -#!/bin/bash -INPUT=$(cat) -TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName') - -if [ "$TOOL_NAME" = "edit" ] || [ "$TOOL_NAME" = "create" ]; then - # Run linter before allowing edits - npm run lint-staged - if [ $? -ne 0 ]; then - echo '{"permissionDecision":"deny","permissionDecisionReason":"Code does not pass linting"}' - fi -fi -``` - -### Notification system - -Send notifications on important events: - -```shell copy -#!/bin/bash -INPUT=$(cat) -PROMPT=$(echo "$INPUT" | jq -r '.prompt') - -# Notify on production-related prompts -if echo "$PROMPT" | grep -iq "production"; then - echo "ALERT: Production-related prompt: $PROMPT" | mail -s "Agent Alert" team@example.com -fi -``` - -## Further reading - -* [AUTOTITLE](/copilot/concepts/agents/cloud-agent) -* [AUTOTITLE](/copilot/how-tos/copilot-cli) -* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference) diff --git a/content/copilot/reference/copilot-cli-reference/cli-hooks-reference.md b/content/copilot/reference/hooks-reference.md similarity index 52% rename from content/copilot/reference/copilot-cli-reference/cli-hooks-reference.md rename to content/copilot/reference/hooks-reference.md index cb91ccc0b4ea..df3b54bb3da0 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-hooks-reference.md +++ b/content/copilot/reference/hooks-reference.md @@ -1,18 +1,60 @@ --- -title: GitHub Copilot CLI hooks reference -shortTitle: CLI hooks reference -intro: 'Find hook events, configuration formats, and input payloads for {% data variables.copilot.copilot_cli_short %}.' +title: GitHub Copilot hooks reference +shortTitle: Hooks reference +intro: 'Find hook events, configuration formats, and input payloads for hooks in {% data variables.copilot.copilot_cli_short %} and {% data variables.copilot.copilot_cloud_agent %}.' versions: feature: copilot +redirect_from: + - /copilot/reference/hooks-configuration + - /copilot/reference/copilot-cli-reference/cli-hooks-reference category: - Author and optimize with Copilot # Copilot discovery page - Configure Copilot CLI # Copilot CLI bespoke page + - Configure Copilot cloud agent # Cloud agent bespoke page contentType: reference docsTeamMetrics: - copilot-cli --- -Hooks are external commands that execute at specific lifecycle points during a session, enabling custom automation, security controls, and integrations. Hook configuration files are loaded automatically from `.github/hooks/*.json` in your repository. +## Introduction + +Hooks are external commands that execute at specific lifecycle points during a session, enabling custom automation, security controls, and integrations. + +Hooks are supported in two {% data variables.product.prodname_copilot_short %} surfaces: {% data variables.copilot.copilot_cli_short %} and {% data variables.copilot.copilot_cloud_agent %}. Most of the configuration format and event payloads are identical, but the execution environment and the set of events that can fire differ. + +Throughout this article, behavior that differs between the two surfaces is called out in "CLI only" and "Cloud agent only" notes. Anything not marked applies to both. + +## Hooks locations + +The locations where hooks run, and where you can store hook configuration files, depend on the surface: + +* **{% data variables.copilot.copilot_cli_short %}** — hooks run on the developer's local machine in the same shell as the CLI. All hook events described in this article are supported by the CLI. + + Hooks are loaded from the following sources in order (user, then project, then plugins) and combined. When the same event appears in multiple sources, all hook entries from all sources are run. + + * **Repository-level hook files** — `.github/hooks/*.json` in the repository root. + * **User-level hook files** — `*.json` files in the user-level hooks directory. By default this is `~/.copilot/hooks/` on macOS and Linux, or `%USERPROFILE%\.copilot\hooks\` on Windows. If `COPILOT_HOME` is set, it is `$COPILOT_HOME/hooks/`. + * **Inline `hooks` block in repository settings** — the `hooks` field at the top level of `.github/copilot/settings.json` (Git committed) or `.github/copilot/settings.local.json` (typically gitignored and user specific) in the repository. Cross-tool `.claude/settings.json` and `.claude/settings.local.json` files in the repository are also read. + * **Inline `hooks` block in user-level config** — the `hooks` field at the top level of `~/.copilot/settings.json`. + * **Hooks contributed by installed plugins** — declared by each plugin in its own `hooks.json` (or under `hooks/hooks.json`) inside the plugin's installation directory. + +* **{% data variables.copilot.copilot_cloud_agent %}** — hooks run inside the ephemeral Linux sandbox that cloud agent provisions for each job. The sandbox is non-interactive, has a constrained network, and is destroyed when the job ends. A subset of events fires, and only `bash` (or `command`) entries are honored. + + Hook configuration is loaded from `.github/hooks/*.json` files in the cloned repository. + +## Cloud agent execution environment + +This section applies to **{% data variables.copilot.copilot_cloud_agent %} only**. It describes constraints that affect how you write hook scripts and configure hook entries for cloud agent jobs. + +| Property | Value | +|----------|-------| +| Operating system | Linux. Only the `bash` field on command hooks is honored; `powershell` entries are ignored. The cross-platform `command` field is honored as a fallback. | +| Working directory | `/workspace` when a repository is cloned, otherwise `/root`. Use this path when setting `cwd` on a hook entry or when referencing files from a script. | +| Filesystem | Ephemeral. Files written by hooks (logs, CSVs, transcripts) are discarded when the job ends. To retain hook output, send it via an `http` hook entry. | +| Outbound network | Restricted by the cloud agent firewall. By default only GitHub and {% data variables.product.prodname_copilot_short %} hostnames are reachable; reaching any other host (for example `https://hooks.example.com`) requires an admin-configured firewall allow rule. | +| Available environment variables | `GITHUB_COPILOT_API_TOKEN` and `GITHUB_COPILOT_GIT_TOKEN` are set in the sandbox. `COPILOT_AGENT_PROMPT` holds the prompt the job was invoked with. `HOME` is set to `/root`, so any hook script that resolves `~/...` paths writes into the ephemeral sandbox. `GITHUB_TOKEN` is not set. | +| Interactivity | Fully non-interactive. The agent runs with all tool permissions pre-granted, so no permission dialogs are shown and no notifications are surfaced to a user. | +| Configuration discovery | In a cloud agent job, the only hook configuration that exists by default is `.github/hooks/*.json` inside the cloned repository. The sandbox does not ship with user-level hook files, `settings.json`, `config.json`, or installed plugins. | ## Hook configuration format @@ -22,6 +64,9 @@ Hook configuration files use JSON format with version `1`. Command hooks run shell scripts and are supported on all hook types. +> [!NOTE] +> **Cloud agent only.** Cloud agent runs hooks in a Linux sandbox. Only the `bash` field is honored; `powershell` entries are ignored. The cross-platform `command` field is honored as a fallback. + ```json { "version": 1, @@ -42,16 +87,55 @@ Command hooks run shell scripts and are supported on all hook types. | Field | Type | Required | Description | |-------|------|----------|-------------| -| `bash` | string | One of `bash`/`powershell` | Shell command for Unix. | +| `bash` | string | One of `bash`, `powershell`, or `command` | Shell command for Unix. | +| `command` | string | One of `bash`, `powershell`, or `command` | Cross-platform fallback used when neither `bash` nor `powershell` is set for the current platform. | | `cwd` | string | No | Working directory for the command (relative to repository root or absolute). | | `env` | object | No | Environment variables to set (supports variable expansion). | -| `powershell` | string | One of `bash`/`powershell` | Shell command for Windows. | +| `powershell` | string | One of `bash`, `powershell`, or `command` | Shell command for Windows. | | `timeoutSec` | number | No | Timeout in seconds. Default: `30`. | | `type` | `"command"` | Yes | Must be `"command"`. | +### HTTP hooks + +HTTP hooks send the input payload as a JSON `POST` to a URL. + +> [!NOTE] +> **Cloud agent only.** Outbound network from the sandbox is restricted by the cloud agent firewall, so `url` must target an allow-listed host. + +```json +{ + "version": 1, + "hooks": { + "postToolUse": [ + { + "type": "http", + "url": "https://hooks.example.com/copilot", + "headers": { "X-Source": "copilot-cli" }, + "allowedEnvVars": ["GITHUB_TOKEN"], + "timeoutSec": 30 + } + ] + } +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `allowedEnvVars` | string[] | No | Environment variable names that may be expanded inside `headers` values. When set, `url` must use `https://`. | +| `headers` | object | No | Request headers to include. | +| `timeoutSec` | number | No | Timeout in seconds. Default: `30`. | +| `type` | `"http"` | Yes | Must be `"http"`. | +| `url` | string | Yes | Target URL. Must use `http:` or `https:`. For `preToolUse` and `permissionRequest`, must use `https://` because the response can grant tool permissions. | + ### Prompt hooks -Prompt hooks auto-submit text as if the user typed it. They are only supported on `sessionStart` and only fire for **new interactive sessions**. They do not fire on resume, and they do not fire in non-interactive prompt mode (`-p`). The text can be a natural language prompt or a slash command. +Prompt hooks auto-submit text as if the user typed it. They are only supported on `sessionStart`. The text can be a natural language prompt or a slash command. + +> [!NOTE] +> **{% data variables.copilot.copilot_cli_short %} only.** Prompt hooks fire only for **new interactive sessions**. They do not fire on resume, and they do not fire in non-interactive prompt mode (`-p`). + +> [!NOTE] +> **Cloud agent.** Cloud agent jobs run non-interactively (similar to `-p`), so `prompt` hook entries may not fire. Confirm the behavior in your environment before relying on them. ```json { @@ -74,21 +158,23 @@ Prompt hooks auto-submit text as if the user typed it. They are only supported o ## Hook events -| Event | Fires when | Output processed | -|-------|-----------|-----------------| -| `agentStop` | The main agent finishes a turn. | Yes — can block and force continuation. | -| `errorOccurred` | An error occurs during execution. | No | -| `notification` | Fires asynchronously when the CLI emits a system notification (shell completion, agent completion or idle, permission prompts, elicitation dialogs). Fire-and-forget: never blocks the session. Supports `matcher` regex on `notification_type`. | Optional — can inject `additionalContext` into the session. | -| `permissionRequest` | Fires before the permission service runs (rules engine, session approvals, auto-allow/auto-deny, and user prompting). If the merged hook output returns `behavior: "allow"` or `"deny"`, that decision short-circuits the normal permission flow. Supports `matcher` regex on `toolName`. | Yes — can allow or deny programmatically. | -| `postToolUse` | After each tool completes successfully. | Yes — can replace the successful result (SDK programmatic hooks only). | -| `postToolUseFailure` | After a tool completes with a failure. | Yes — can provide recovery guidance via `additionalContext` (exit code `2` for command hooks). | -| `preCompact` | Context compaction is about to begin (manual or automatic). Supports `matcher` to filter by trigger (`"manual"` or `"auto"`). | No — notification only. | -| `preToolUse` | Before each tool executes. | Yes — can allow, deny, or modify. | -| `sessionEnd` | The session terminates. | No | -| `sessionStart` | A new or resumed session begins. | No | -| `subagentStart` | A subagent is spawned (before it runs). Returns `additionalContext` prepended to the subagent's prompt. Supports `matcher` to filter by agent name. | No — cannot block creation. | -| `subagentStop` | A subagent completes. | Yes — can block and force continuation. | -| `userPromptSubmitted` | The user submits a prompt. | No | +The table below lists every supported event. The **Cloud agent** column shows whether the event fires under cloud agent and notes any behavior differences. + +| Event | Fires when | Output processed | Cloud agent | +|-------|-----------|------------------|-------------| +| `agentStop` | The main agent finishes a turn. | Yes — can block and force continuation. | Fires. `decision: "block"` forces another turn, which still counts against the job's timeout. | +| `errorOccurred` | An error occurs during execution. | No | Fires. | +| `notification` | Fires asynchronously when the CLI emits a system notification (shell completion, agent completion or idle, permission prompts, elicitation dialogs). Fire-and-forget: never blocks the session. Supports `matcher` regex on `notification_type`. | Optional — can inject `additionalContext` into the session. | **Does not fire.** Cloud agent does not surface notifications to a user (see the **Interactivity** row in the Cloud agent execution environment table above). | +| `permissionRequest` | Fires before the permission service runs (rules engine, session approvals, auto-allow/auto-deny, and user prompting). If the merged hook output returns `behavior: "allow"` or `"deny"`, that decision short-circuits the normal permission flow. Supports `matcher` regex on `toolName`. | Yes — can allow or deny programmatically. | Tool calls are pre-approved, so this hook either does not fire or has no effect. Use `preToolUse` to make permission decisions instead. | +| `postToolUse` | After each tool completes successfully. | No | Fires. | +| `postToolUseFailure` | After a tool completes with a failure. | Yes — can provide recovery guidance via `additionalContext` (exit code `2` for command hooks). | Fires. | +| `preCompact` | Context compaction is about to begin (manual or automatic). Supports `matcher` to filter by trigger (`"manual"` or `"auto"`). | No — notification only. | Fires only with `trigger: "auto"`. There is no user to request manual compaction. | +| `preToolUse` | Before each tool executes. | Yes — can allow, deny, or modify. | Fires. A decision of `"ask"` is treated as `"deny"` because no user is available to answer. | +| `sessionEnd` | The session terminates. | No | Fires once per job. `reason` is typically `"complete"`, `"error"`, or `"timeout"`; `"abort"` and `"user_exit"` are not expected because there is no user. | +| `sessionStart` | A new or resumed session begins. | Optional — can inject `additionalContext` into the session. | Fires once per job, as a new session (not a resume). See the Prompt hooks note above for the behavior of `prompt` entries under cloud agent. | +| `subagentStart` | A subagent is spawned (before it runs). Supports `matcher` to filter by agent name. | Optional — cannot block creation, but `additionalContext` is prepended to the subagent's prompt. | Fires. | +| `subagentStop` | A subagent completes. | Yes — can block and force continuation. | Fires. | +| `userPromptSubmitted` | The user submits a prompt. | No | Fires at most once, for the prompt supplied to the job. There is no follow-up user input. | ## Hook event input payloads @@ -232,7 +318,7 @@ When configured with the PascalCase event name `PreToolUse`, the payload uses sn tool_name: string; tool_input: unknown; tool_result: { - result_type: "success" | "failure" | "denied" | "error"; + result_type: "success"; text_result_for_llm: string; } } @@ -413,7 +499,7 @@ The `preToolUse` hook can control tool execution by writing a JSON object to std | Field | Values | Description | |-------|--------|-------------| -| `permissionDecision` | `"allow"`, `"deny"`, `"ask"` | Whether the tool executes. Empty output uses default behavior. | +| `permissionDecision` | `"allow"`, `"deny"`, `"ask"` | Whether the tool executes. Empty output uses default behavior. Under cloud agent, `"ask"` is treated as `"deny"` because no user is available to answer. | | `permissionDecisionReason` | string | Reason shown to the agent. Required when decision is `"deny"`. | | `modifiedArgs` | object | Substitute tool arguments to use instead of the originals. | @@ -426,7 +512,10 @@ The `preToolUse` hook can control tool execution by writing a JSON object to std ## `permissionRequest` decision control -The `permissionRequest` hook fires before the permission service runs—before rule checks, session approvals, auto-allow/auto-deny, and user prompting. If hooks return `behavior: "allow"` or `"deny"`, that decision short-circuits the normal permission flow. Returning nothing falls through to normal permission handling. Use it to approve or deny tool calls programmatically—especially useful in pipe mode (`-p`) and CI environments where no interactive prompt is available. +> [!NOTE] +> **{% data variables.copilot.copilot_cli_short %} only.** The `permissionRequest` hook does not apply under {% data variables.copilot.copilot_cloud_agent %}—tool calls there are pre-approved (see the **Interactivity** row in the Cloud agent execution environment table). Use `preToolUse` to make permission decisions in cloud agent. + +The `permissionRequest` hook fires before the permission service runs—before rule checks, session approvals, auto-allow/auto-deny, and user prompting. If hooks return `behavior: "allow"` or `"deny"`, that decision short-circuits the normal permission flow. Returning nothing falls through to normal permission handling. Use it to approve or deny tool calls programmatically—especially useful in CLI pipe mode (`-p`) and other CLI CI usages where no interactive prompt is available. It does not apply to cloud agent. All configured `permissionRequest` hooks run for each request (except `read` and `hook` permission kinds, which short-circuit before hooks). Hook outputs are merged with later hook outputs overriding earlier ones. @@ -444,6 +533,9 @@ Return empty output or `{}` to fall through to the normal permission flow. For c ## `notification` hook +> [!NOTE] +> **{% data variables.copilot.copilot_cli_short %} only.** The `notification` hook does not fire under {% data variables.copilot.copilot_cloud_agent %}. + The `notification` hook fires asynchronously when the CLI emits a system notification. These hooks are fire-and-forget: they never block the session, and any errors are logged and skipped. **Input:** @@ -483,25 +575,72 @@ If `additionalContext` is returned, the text is injected into the session as a p **Matcher:** Optional regex on `notification_type`. The pattern is anchored as `^(?:pattern)$`. Omit `matcher` to receive all notification types. +## Matcher filtering + +Several events accept an optional `matcher` regex on each hook entry that filters which invocations the hook fires for. The pattern is anchored as `^(?:matcher)$` and must match the full value. Invalid regexes cause the hook entry to be skipped. + +| Event | `matcher` is matched against | +|-------|------------------------------| +| `notification` | `notification_type` | +| `permissionRequest` | `toolName` | +| `preCompact` | `trigger` (`"manual"` or `"auto"`) | +| `preToolUse` | `toolName` | +| `subagentStart` | `agentName` | + ## Tool names for hook matching | Tool name | Description | |-----------|-------------| -| `ask_user` | Ask the user a clarifying question. | +| `ask_user` | Ask the user a clarifying question. Under cloud agent there is no user, so `ask_user` does not produce a useful result. | | `bash` | Execute shell commands (Unix). | | `create` | Create new files. | | `edit` | Modify file contents. | | `glob` | Find files by pattern. | | `grep` | Search file contents. | -| `powershell` | Execute shell commands (Windows). | +| `powershell` | Execute shell commands (Windows). Does not appear under cloud agent (Linux sandbox). | | `task` | Run subagent tasks. | | `view` | Read file contents. | | `web_fetch` | Fetch web pages. | -If multiple hooks of the same type are configured, they execute in order. For `preToolUse`, if any hook returns `"deny"`, the tool is blocked. For `postToolUseFailure` command hooks, exiting with code `2` causes stderr to be returned as recovery guidance for the assistant. Hook failures (non-zero exit codes or timeouts) are logged and skipped—they never block agent execution. +If multiple hooks of the same type are configured, they execute in order. For `preToolUse`, if any hook returns `"deny"`, the tool is blocked. Hook failures (non-zero exit codes other than `2`, or timeouts) are logged and skipped—they never block agent execution. + +## Exit codes for command hooks + +| Exit code | Meaning | +|-----------|---------| +| `0` | Success. `stdout` is parsed as the hook output JSON if present. | +| `2` | Treated as a warning by default. `stderr` is surfaced to the user but the run continues. For `permissionRequest`, exit `2` is treated as `{"behavior":"deny"}` and any `stdout` JSON is merged in. For `postToolUseFailure`, exit `2` is treated as `additionalContext` and `stdout` is appended to the failure shown to the agent. | +| Other non-zero | Logged as a hook failure. The run continues (fail-open). | + +## Disable all hooks + +Use `disableAllHooks` when you want to keep your hook configuration on disk but stop it from running—for example: + +* Debugging an issue and you want to confirm a hook is the cause without deleting your config. +* Pausing automation during a sensitive task (a code review, a release branch, working with secrets) without losing the setup. (**{% data variables.copilot.copilot_cli_short %} only.**) +* Shipping a hooks file in source control that contributors can opt out of locally by setting the option in their repository `settings.json`. (**{% data variables.copilot.copilot_cli_short %} only.**) +* Temporarily silencing slow or noisy hooks during an interactive session. (**{% data variables.copilot.copilot_cli_short %} only.**) + +Set `disableAllHooks` to `true` at the top level to skip every hook in the file without deleting it. + +```json +{ + "version": 1, + "disableAllHooks": false, + "hooks": { + "preToolUse": [ /* hook entries */ ] + } +} +``` + +Behavior depends on where you set the flag: + +* **Inside a single `.github/hooks/*.json` file** — only the hooks declared in that file are skipped. Honored by both {% data variables.copilot.copilot_cli_short %} and {% data variables.copilot.copilot_cloud_agent %}. +* **At the top level of repository `settings.json`** — **{% data variables.copilot.copilot_cli_short %} only.** Every hook from every source (repository files, user files, plugins, and inline hook blocks) is skipped for sessions in that repository. Cloud agent does not load `settings.json`. ## Further reading * [AUTOTITLE](/copilot/how-tos/copilot-cli/use-hooks) * [AUTOTITLE](/copilot/reference/hooks-configuration) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference) +* [AUTOTITLE](/copilot/concepts/agents/cloud-agent) diff --git a/content/copilot/reference/index.md b/content/copilot/reference/index.md index 23c0dd821150..a20944303db4 100644 --- a/content/copilot/reference/index.md +++ b/content/copilot/reference/index.md @@ -13,7 +13,7 @@ children: - /copilot-cli-reference - /custom-agents-configuration - /custom-instructions-support - - /hooks-configuration + - /hooks-reference - /policy-conflicts - /copilot-allowlist-reference - /mcp-allowlist-enforcement diff --git a/content/copilot/responsible-use/copilot-cloud-agent.md b/content/copilot/responsible-use/copilot-cloud-agent.md index a9efdb87e0b1..703bb20804e8 100644 --- a/content/copilot/responsible-use/copilot-cloud-agent.md +++ b/content/copilot/responsible-use/copilot-cloud-agent.md @@ -15,7 +15,7 @@ category: - Responsible use --- -## About {% data variables.copilot.copilot_cloud_agent_tmp %} on {% data variables.product.prodname_dotcom_the_website %} +## About {% data variables.copilot.copilot_cloud_agent %} on {% data variables.product.prodname_dotcom_the_website %} {% data variables.copilot.copilot_cloud_agent %} is an autonomous and asynchronous software development agent integrated into {% data variables.product.github %}. The agent can pick up a task from an issue or from {% data variables.copilot.copilot_chat_short %}, research a repository, create an implementation plan, and make code changes on a branch. You can review the diff, iterate with the agent, and create a pull request when you're ready. diff --git a/content/copilot/tutorials/copilot-cli-hooks.md b/content/copilot/tutorials/copilot-cli-hooks.md index 27d24abdbb56..0fbcd732ed50 100644 --- a/content/copilot/tutorials/copilot-cli-hooks.md +++ b/content/copilot/tutorials/copilot-cli-hooks.md @@ -26,10 +26,11 @@ You’ll configure repository-scoped hooks that: ## Prerequisites -* Familiarity with shell scripting (Bash or PowerShell) -* Basic understanding of JSON configuration files -* Access to a repository where {% data variables.copilot.copilot_cli_short %} is used -* `jq` installed (for the Bash examples) +* Familiarity with shell scripting (Bash or PowerShell). +* Basic understanding of JSON configuration files. +* Access to a repository where {% data variables.copilot.copilot_cli_short %} is used. +* For the Bash examples: `jq` must be installed. +* For the PowerShell examples: PowerShell 7.0 or later must be installed. ## 1. Define an organizational policy @@ -79,7 +80,7 @@ Clear expectations make policy enforcement easier to adopt and maintain. Throughout this tutorial, you’ll use **repository-scoped hooks** stored in the repository under `.github/hooks/`. These hooks apply whenever {% data variables.copilot.copilot_cli_short %} runs from within this repository. > [!NOTE] -> {% data variables.product.prodname_copilot_short %} agents load hook configuration files from `.github/hooks/*.json` in the repository. Hooks run synchronously and can block execution. +> {% data variables.product.prodname_copilot_short %} agents load hook configurations from `.github/hooks/*.json` files in the repository. Hooks run synchronously and can block execution. ### Create the directory structure @@ -113,6 +114,9 @@ This tutorial uses the following structure: └── pre-tool-policy.ps1 ``` +> [!NOTE] +> This tutorial seeks to create portable hook configurations and scripts that can be used on Windows, Linux, and macOS. The `scripts` directory will therefore contain both Bash and PowerShell scripts, and the hook configuration files will include `bash` and `powershell` entries. The CLI will use the appropriate entry based on your operating system. + ### Create a hook configuration file Create a hook configuration file at `.github/hooks/copilot-cli-policy.json`. diff --git a/content/copilot/tutorials/roll-out-at-scale/govern-for-adoption.md b/content/copilot/tutorials/roll-out-at-scale/govern-for-adoption.md new file mode 100644 index 000000000000..1d3869666951 --- /dev/null +++ b/content/copilot/tutorials/roll-out-at-scale/govern-for-adoption.md @@ -0,0 +1,54 @@ +--- +title: Governing Copilot to support developer productivity +shortTitle: Govern for adoption +intro: 'Set a governance posture that balances compliance requirements with developer productivity, so your rollout succeeds from day one.' +permissions: Enterprise owners +versions: + feature: copilot +category: + - Roll Copilot out at scale +contentType: tutorials +allowTitleToDifferFromFilename: true +--- + +Getting the most from {% data variables.product.prodname_copilot %} means finding the right balance between governance and developer access. Too restrictive, and developers can't use the features that make them productive. Too permissive, and you may not meet your compliance requirements. + +This guide covers the governance decisions that help your developers get value from {% data variables.product.prodname_copilot_short %} quickly, while keeping your enterprise within its compliance boundaries. You should make these decisions during initial setup, and revisit them as your usage matures. + +## Delegate {% data variables.product.prodname_copilot_short %} administration to people with AI context + +Policy decisions work best when they're informed by practical experience with AI tools. Custom enterprise roles let you delegate AI administration to subject matter experts. + +This approach reduces bottlenecks and helps ensure that the people setting policies understand how developers actually work with {% data variables.product.prodname_copilot_short %}. + +For step-by-step instructions on creating an AI manager role, see [AUTOTITLE](/copilot/tutorials/roll-out-at-scale/establish-ai-managers). + +## Review and enable features promptly + +Developers get the most value from {% data variables.product.prodname_copilot_short %} when they can access new features and models as they become available. When there are significant feature gaps, due to features remaining disabled, developers may turn to third-party tools that sit outside your compliance controls. + +Consider enabling vetted capabilities promptly, rather than disabling features by default and enabling them only after review: + +* **Enable new features and models as they become available**, unless you have a specific compliance reason not to. {% data variables.product.github %} vets all features and models before release. +* **Only set enterprise-level defaults to disabled for non-negotiables**, such as compliance-critical controls or features that conflict with regulatory requirements. +* **Scope restrictions to sensitive organizations**. Rather than blocking features enterprise-wide, disable them only in organizations with stricter compliance requirements. This lets other organizations move faster. + +### Spend management and policy posture + +Spend controls interact with your policies. If you enable advanced models and agentic features but set tight budget limits, developers may not be able to use those features consistently. + +When configuring policies and budgets, consider whether your limits align with how you want developers to use {% data variables.product.prodname_copilot_short %}. + +## Use pre-vetted LLM models + +If your organization already has a vetted LLM provider for compliance, cost management, or existing contracts, you can use those API keys with {% data variables.product.prodname_copilot_short %} instead of going through a separate approval process for {% data variables.product.github %}-hosted models. + +If you don't have an existing LLM provider relationship, this approach is optional. {% data variables.product.github %}-hosted models are ready to use immediately. + +This approach offers several advantages: + +* **Governance and compliance**: Use LLM providers that already meet your organization's policies and regulatory requirements. +* **Cost management**: Align with existing payment methods, contracts, credits, or negotiated rates. +* **Visibility and control**: Monitor usage through your provider's existing dashboards and billing. + +For setup instructions, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/use-your-own-api-keys). diff --git a/content/copilot/tutorials/roll-out-at-scale/index.md b/content/copilot/tutorials/roll-out-at-scale/index.md index 9445c192d71e..f8e4e2b5588a 100644 --- a/content/copilot/tutorials/roll-out-at-scale/index.md +++ b/content/copilot/tutorials/roll-out-at-scale/index.md @@ -7,6 +7,7 @@ versions: children: - /assign-licenses - /establish-ai-managers + - /govern-for-adoption - /enable-developers - /drive-downstream-impact - /measure-success diff --git a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization.md index caa4a48c1c9e..52902c3700bf 100644 --- a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization.md +++ b/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization.md @@ -36,7 +36,7 @@ category: You can also require two-factor authentication for organizations in an enterprise. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise). > [!NOTE] -> Some of the users in your organization may have been selected for mandatory two-factor authentication enrollment by {% data variables.product.prodname_dotcom %}, but it has no impact on how you enable the 2FA requirement for your organization. If you enable the 2FA requirement in your organization, all users without 2FA currently enabled will be removed from your organization, including those that are required to enable it by {% data variables.product.prodname_dotcom %}. +> Some of the users in your organization may have been selected for mandatory two-factor authentication enrollment by {% data variables.product.prodname_dotcom %}, but it has no impact on how you enable the 2FA requirement for your organization. > [!WARNING] > * When you require use of two-factor authentication for your organization, members {% ifversion fpt or ghec %}and billing managers {% endif %}who do not use 2FA will not be able to access your organization's resources until they enable 2FA on their account. They will retain membership even without 2FA{% ifversion not ghes %}, including consuming {% ifversion enterprise-licensing-language %}licenses{% else %}seats{% endif %} in your organization{% endif %}. diff --git a/content/repositories/creating-and-managing-repositories/access-to-repositories.md b/content/repositories/creating-and-managing-repositories/access-to-repositories.md index 9acc9cb573f5..187357a204a3 100644 --- a/content/repositories/creating-and-managing-repositories/access-to-repositories.md +++ b/content/repositories/creating-and-managing-repositories/access-to-repositories.md @@ -24,7 +24,7 @@ If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %} {% endif %} -To add a collaborator, see [AUTOTITLE](/account-and-profile/how-tos/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository). +To add a collaborator, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration/inviting-collaborators-to-a-personal-repository). {% ifversion fpt or ghec %} @@ -44,6 +44,6 @@ An appointed successor can manage your public repositories after presenting a de To request access to manage repositories as a successor, please contact us through the {% data variables.contact.contact_support_portal %}. -For more information, see [AUTOTITLE](/account-and-profile/how-tos/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/maintaining-ownership-continuity-of-your-personal-accounts-repositories). +For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration/maintaining-ownership-continuity-of-your-personal-accounts-repositories). {% endif %} diff --git a/data/features/codeql-dependency-caching.yml b/data/features/codeql-dependency-caching.yml deleted file mode 100644 index ed0034394585..000000000000 --- a/data/features/codeql-dependency-caching.yml +++ /dev/null @@ -1,5 +0,0 @@ -# Reference #16278 -versions: - fpt: '*' - ghec: '*' - ghes: '>3.15' diff --git a/data/features/codeql-no-build-csharp.yml b/data/features/codeql-no-build-csharp.yml deleted file mode 100644 index 979f528738f9..000000000000 --- a/data/features/codeql-no-build-csharp.yml +++ /dev/null @@ -1,7 +0,0 @@ -# Reference: #14183 (C# beta) -# Reference: #15544 (C# GA) - -versions: - fpt: '*' - ghec: '*' - ghes: '>=3.15' diff --git a/data/features/cvss-4.yml b/data/features/cvss-4.yml deleted file mode 100644 index 4ed881f4b59c..000000000000 --- a/data/features/cvss-4.yml +++ /dev/null @@ -1,6 +0,0 @@ -# Reference: #3949 - -versions: - fpt: '*' - ghec: '*' - ghes: '> 3.15' diff --git a/data/features/dependabot-updates-composerv1-closing-down.yml b/data/features/dependabot-updates-composerv1-closing-down.yml deleted file mode 100644 index bf8af2c8da8c..000000000000 --- a/data/features/dependabot-updates-composerv1-closing-down.yml +++ /dev/null @@ -1,5 +0,0 @@ -# Reference: Issue #15951 - Deprecation notice - Dependabot updates ceases supporting Composer v1 [Deprecation] -versions: - fpt: '*' - ghec: '*' - ghes: '>= 3.15' diff --git a/data/features/dependabot-updates-pnpmv9-support.yml b/data/features/dependabot-updates-pnpmv9-support.yml deleted file mode 100644 index 474a72aa2c92..000000000000 --- a/data/features/dependabot-updates-pnpmv9-support.yml +++ /dev/null @@ -1,5 +0,0 @@ -# Reference: Issue #3970 from dependabot-core repo - DG-API supports PNPM v9 lockfile format -versions: - fpt: '*' - ghec: '*' - ghes: '>3.14' diff --git a/data/features/dependabot-updates-supported-versioning-tags.yml b/data/features/dependabot-updates-supported-versioning-tags.yml deleted file mode 100644 index fb4f7cccbd1b..000000000000 --- a/data/features/dependabot-updates-supported-versioning-tags.yml +++ /dev/null @@ -1,6 +0,0 @@ -# Reference: #16090 -# Add versioning tag details to Dependabot docs -versions: - fpt: '*' - ghec: '*' - ghes: '> 3.14' diff --git a/data/features/ghecom-license-sync.yml b/data/features/ghecom-license-sync.yml deleted file mode 100644 index 92dad18b5665..000000000000 --- a/data/features/ghecom-license-sync.yml +++ /dev/null @@ -1,3 +0,0 @@ -# GHES version required to enable GitHub Connect license sync between GHES and GHE.com -versions: - ghes: '>=3.15' diff --git a/data/features/kotlin-supported-language.yml b/data/features/kotlin-supported-language.yml deleted file mode 100644 index 0c679d536475..000000000000 --- a/data/features/kotlin-supported-language.yml +++ /dev/null @@ -1,4 +0,0 @@ -versions: - fpt: '*' - ghec: '*' - ghes: '>3.15' diff --git a/data/features/org-npp-enablement-security-configurations.yml b/data/features/org-npp-enablement-security-configurations.yml deleted file mode 100644 index 4c3136860973..000000000000 --- a/data/features/org-npp-enablement-security-configurations.yml +++ /dev/null @@ -1,6 +0,0 @@ -# Reference: #15650 -# Secret scanning - non-provider pattern enablement is included in security configurations [Public Beta] -versions: - fpt: '*' - ghec: '*' - ghes: '> 3.14' diff --git a/data/features/push-protection-bypass-reviewer-comment.yml b/data/features/push-protection-bypass-reviewer-comment.yml deleted file mode 100644 index db2a3edf12aa..000000000000 --- a/data/features/push-protection-bypass-reviewer-comment.yml +++ /dev/null @@ -1,7 +0,0 @@ -# Reference: #16452 -# Documentation for reviewers can add a comment on push protection bypass requests for secret scanning [GA] -# Ref 17108 Advanced Security available to Team plans -versions: - fpt: '*' - ghec: '*' - ghes: '>=3.16' diff --git a/data/reusables/advanced-security/note-org-enable-uses-seats.md b/data/reusables/advanced-security/note-org-enable-uses-seats.md deleted file mode 100644 index d60392ac6b84..000000000000 --- a/data/reusables/advanced-security/note-org-enable-uses-seats.md +++ /dev/null @@ -1,6 +0,0 @@ -{% ifversion ghes or ghec %} - -> [!NOTE] -> If you enable {% data variables.product.prodname_GHAS %} features, active committers to these repositories will use {% data variables.product.prodname_GHAS_cs_or_sp %} licenses. This option is deactivated if you have exceeded your license capacity. {% ifversion fpt or ghec %}See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security).{% endif %} - -{% endif %} diff --git a/data/reusables/cli/public-preview-remote-access.md b/data/reusables/cli/public-preview-remote-access.md deleted file mode 100644 index bd590c6c8371..000000000000 --- a/data/reusables/cli/public-preview-remote-access.md +++ /dev/null @@ -1,3 +0,0 @@ -> [!NOTE] -> * Remote access to {% data variables.copilot.copilot_cli_short %} sessions is in {% data variables.release-phases.public_preview %} and subject to change. -> * Mobile access is currently only available in the latest beta release of {% data variables.product.prodname_mobile %}. You can join the test program for {% data variables.product.prodname_mobile %} via [Apple TestFlight for iOS](https://testflight.apple.com/join/NLskzwi5) and [Google Play for Android](https://play.google.com/apps/testing/com.github.android). diff --git a/data/reusables/code-scanning/limitation-org-enable-all.md b/data/reusables/code-scanning/limitation-org-enable-all.md deleted file mode 100644 index 7e4f9fe12d61..000000000000 --- a/data/reusables/code-scanning/limitation-org-enable-all.md +++ /dev/null @@ -1 +0,0 @@ -If you disable {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} for all repositories this change is not reflected in the coverage information shown in security overview for the organization. The repositories will still appear to have {% data variables.product.prodname_code_scanning %} enabled in the "Security Coverage" view. diff --git a/data/reusables/copilot-business-for-non-ghe/enable-copilot.md b/data/reusables/copilot-business-for-non-ghe/enable-copilot.md deleted file mode 100644 index 8cfb509306fe..000000000000 --- a/data/reusables/copilot-business-for-non-ghe/enable-copilot.md +++ /dev/null @@ -1,6 +0,0 @@ -Before you can assign licenses, an **enterprise owner** must enable {% data variables.product.prodname_copilot_short %} for the enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.billing.enterprise-billing-menu %} -1. In the left sidebar, click {% octicon "law" aria-hidden="true" aria-label="law" %} **Licensing**. -1. Next to "{% data variables.product.prodname_copilot_short %}", click **Enable**. diff --git a/data/reusables/copilot/cloud-agent/create-hooks-instructions.md b/data/reusables/copilot/cloud-agent/create-hooks-instructions.md index adc4994ffb59..4d066b60761a 100644 --- a/data/reusables/copilot/cloud-agent/create-hooks-instructions.md +++ b/data/reusables/copilot/cloud-agent/create-hooks-instructions.md @@ -1,53 +1,54 @@ -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_cloud_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. \ No newline at end of file + ```json copy + { + "version": 1, + "hooks": { + "sessionStart": [...], + "sessionEnd": [...], + "userPromptSubmitted": [...], + "preToolUse": [...], + "postToolUse": [...], + "errorOccurred": [...] + } + } + ``` + +1. Configure your hook syntax under the `bash` and `powershell` keys, or directly reference script files you have created. + + > [!NOTE] + > Include both a `bash` key (with a script for Linux and macOS) and a `powershell` key (for a script for Windows) to allow the hooks to run on all three operating systems. {% data variables.product.prodname_copilot_short %} uses the appropriate key based on the user's operating system. + + * 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-reference). + +1. Commit the file to the repository and merge it into the default branch. Your hooks will now run during agent sessions. diff --git a/data/reusables/copilot/cloud-agent/hooks-example-steps.md b/data/reusables/copilot/cloud-agent/hooks-example-steps.md new file mode 100644 index 000000000000..2e3a23463d9a --- /dev/null +++ b/data/reusables/copilot/cloud-agent/hooks-example-steps.md @@ -0,0 +1,7 @@ +1. Start, or restart, {% data variables.copilot.copilot_cli_short %}. + + > [!NOTE] + > Changes to hook configurations are loaded when the CLI starts. + +1. Enter a prompt and check that you hear a sound and see a message box when the agent finishes responding, and when you quit the CLI. +1. Delete the `notification-hooks.json` file to remove these hooks. diff --git a/data/reusables/copilot/cloud-agent/hooks-intro.md b/data/reusables/copilot/cloud-agent/hooks-intro.md index 6d91fd40fcfd..117cfb9feb10 100644 --- a/data/reusables/copilot/cloud-agent/hooks-intro.md +++ b/data/reusables/copilot/cloud-agent/hooks-intro.md @@ -1 +1 @@ -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—including details of the available hook triggers—see [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-hooks). +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—including details of the available hook triggers—see [AUTOTITLE](/copilot/concepts/agents/hooks). diff --git a/data/reusables/copilot/gpt-5-codex-vscode-support.md b/data/reusables/copilot/gpt-5-codex-vscode-support.md deleted file mode 100644 index c09e75405d4d..000000000000 --- a/data/reusables/copilot/gpt-5-codex-vscode-support.md +++ /dev/null @@ -1 +0,0 @@ -{% data variables.copilot.copilot_gpt_5_codex %} is supported in {% data variables.product.prodname_vscode %} v1.104.1 or higher. diff --git a/data/reusables/copilot/setup-next-steps.md b/data/reusables/copilot/setup-next-steps.md index 9a4a493a63bd..a04d19300947 100644 --- a/data/reusables/copilot/setup-next-steps.md +++ b/data/reusables/copilot/setup-next-steps.md @@ -1,3 +1,4 @@ +* **Set a governance posture that supports adoption**. Avoid over-restricting {% data variables.product.prodname_copilot_short %} by delegating administration, enabling vetted features promptly, and aligning spend controls with your goals. See [AUTOTITLE](/copilot/tutorials/roll-out-at-scale/govern-for-adoption). * **Explore self-service license management options**. Many successful rollouts use a self-service model where developers can claim a license without approval. See [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/setting-up-a-self-serve-process-for-github-copilot-licenses). * **Learn how to plan and implement an effective enablement process to drive {% data variables.product.prodname_copilot_short %} adoption**. See [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/driving-copilot-adoption-in-your-company). * **Enhance the development experience by enabling and training developers on the latest features**. For example, share context with {% data variables.copilot.copilot_spaces %}, enable {% data variables.copilot.copilot_code-review_short %} on pull requests, and allow developers to experiment with prompts using {% data variables.product.prodname_github_models %}. For an example showing how these features fit together, see [AUTOTITLE](/copilot/tutorials/rolling-out-github-copilot-at-scale/enabling-developers/integrating-agentic-ai). diff --git a/data/reusables/dependabot/navigate-to-org-level-dependabot-alert-rules.md b/data/reusables/dependabot/navigate-to-org-level-dependabot-alert-rules.md deleted file mode 100644 index e1d853fd6d5e..000000000000 --- a/data/reusables/dependabot/navigate-to-org-level-dependabot-alert-rules.md +++ /dev/null @@ -1 +0,0 @@ -1. Under "{% data variables.product.prodname_dependabot %}", then under "{% data variables.product.prodname_dependabot_alerts %}", click {% octicon "gear" aria-label="The Gear icon" %} close to "{% data variables.product.prodname_dependabot %} rules". diff --git a/data/reusables/organizations/security-and-analysis.md b/data/reusables/organizations/security-and-analysis.md deleted file mode 100644 index 4be8a126a23e..000000000000 --- a/data/reusables/organizations/security-and-analysis.md +++ /dev/null @@ -1 +0,0 @@ -1. In the "Security" section of the sidebar, click **{% octicon "codescan" aria-hidden="true" aria-label="codescan" %} Code security and analysis**. diff --git a/data/reusables/release-notes/2024-08-resolvconf-wont-start.md b/data/reusables/release-notes/2024-08-resolvconf-wont-start.md deleted file mode 100644 index 5b8a6540e1d0..000000000000 --- a/data/reusables/release-notes/2024-08-resolvconf-wont-start.md +++ /dev/null @@ -1,16 +0,0 @@ -On boot, the `resolvconf` service may fail to start because the `/run/resolvconf` directory does not exist when the service attempts to `touch` a file there, with the error: - -```shell -/bin/touch: cannot touch '/run/resolvconf/postponed-update': No such file or directory -``` - -If this occurs, workaround this issue with the following commands — this change will persist on reboots, but not upgrades: - -```shell -sudo sed -i.bak \ -'/\[Service\]/a ExecStartPre\=\/bin\/mkdir \-p \/run\/resolvconf' \ -/etc/systemd/system/resolvconf.service.d/local.conf - -sudo systemctl daemon-reload -sudo systemctl start resolvconf -``` diff --git a/data/reusables/release-notes/2024-11-ghe-repl-promote-primary-down.md b/data/reusables/release-notes/2024-11-ghe-repl-promote-primary-down.md deleted file mode 100644 index 14b809d72e4c..000000000000 --- a/data/reusables/release-notes/2024-11-ghe-repl-promote-primary-down.md +++ /dev/null @@ -1,15 +0,0 @@ -When operating in a high availability configuration, running `ghe-repl-promote` on a replica node will fail if the original primary cannot be reached by the replica node. This is because the `ghe-repl-promote` script attempts to decommission all Elasticsearch nodes other than the promoted node, however these requests are made to the original primary node which is no longer reachable. The error message written to the terminal will be similar to: - -```shell -Maintenance mode has been enabled for active replica -{"message": "No server is currently available to service your request. Sorry about that. Please try resubmitting your request and contact your local GitHub Enterprise site administrator if the problem persists."} -jq: error (at :3): Cannot index string with string "node" -``` - -If this occurs, workaround this issue by running the following command — this changes the `ghe-repl-promote` script in place: - -```shell -sudo sed -i.bak -e '/for node_hostname in/i if ! $forced; then' -e '/^ done/a fi' /usr/local/bin/ghe-repl-promote -``` - -Then re-run the updated `ghe-repl-promote` script. diff --git a/data/reusables/release-notes/2025-02-gcp-hotpatch-bug.md b/data/reusables/release-notes/2025-02-gcp-hotpatch-bug.md deleted file mode 100644 index d13c8ac5ec43..000000000000 --- a/data/reusables/release-notes/2025-02-gcp-hotpatch-bug.md +++ /dev/null @@ -1 +0,0 @@ -Instances installed on Google Cloud Platform (GCP) could experience errors when the latest hotpatch was applied. We recommend waiting for the next patch release to hotpatch. diff --git a/data/reusables/repositories/navigate-to-tags.md b/data/reusables/repositories/navigate-to-tags.md deleted file mode 100644 index 963eb0ececb1..000000000000 --- a/data/reusables/repositories/navigate-to-tags.md +++ /dev/null @@ -1 +0,0 @@ -1. In the "Code and automation" section of the sidebar, click **{% octicon "tag" aria-hidden="true" aria-label="tag" %} Tags**. diff --git a/data/reusables/security-overview/security-overview-coverage-view.md b/data/reusables/security-overview/security-overview-coverage-view.md deleted file mode 100644 index 9bee2c6e2123..000000000000 --- a/data/reusables/security-overview/security-overview-coverage-view.md +++ /dev/null @@ -1,3 +0,0 @@ -1. In the sidebar, click **{% octicon "meter" aria-hidden="true" aria-label="meter" %} Coverage** to display the "Security coverage" view. - - ![Screenshot of the "Security coverage" view.](/assets/images/help/security-overview/security-coverage-view-multi-repo.png) diff --git a/data/reusables/security-overview/settings-limitations.md b/data/reusables/security-overview/settings-limitations.md deleted file mode 100644 index e9fd549d1888..000000000000 --- a/data/reusables/security-overview/settings-limitations.md +++ /dev/null @@ -1,3 +0,0 @@ -> [!NOTE] -> * Enabling {% data variables.product.prodname_code_scanning %} default setup _will not_ override any existing configurations of advanced setup for the selected repositories, but it _will_ override any existing configurations of default setup. -> * Enabling "Alerts" for {% data variables.product.prodname_secret_scanning %} enables default alerts. If you want to enable non-provider alerts, you need to edit the repository, organization, or enterprise settings. For more information about alert types, see [Supported secrets](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secrets). diff --git a/data/reusables/security/note-securing-your-org.md b/data/reusables/security/note-securing-your-org.md deleted file mode 100644 index 2f66f633d012..000000000000 --- a/data/reusables/security/note-securing-your-org.md +++ /dev/null @@ -1 +0,0 @@ -For more information about enabling security features across an organization, see [AUTOTITLE](/code-security/securing-your-organization). diff --git a/src/content-pipelines/config.yml b/src/content-pipelines/config.yml index 2136f5288e90..66de5b4446a3 100644 --- a/src/content-pipelines/config.yml +++ b/src/content-pipelines/config.yml @@ -22,18 +22,18 @@ copilot-cli: target-articles: - content/copilot/reference/copilot-cli-reference/cli-command-reference.md - content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md - - content/copilot/reference/copilot-cli-reference/cli-hooks-reference.md - content/copilot/reference/copilot-cli-reference/acp-server.md - content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md + - content/copilot/reference/hooks-reference.md exclusions: - All mentions of, or information directly relating to, feature flags - enabledFeatureFlags configuration setting - COPILOT_CLI_ENABLED_FEATURE_FLAGS environment variable content-mapping: | - cli-plugin-reference.md covers only plugin-specific content. - All information relating to files in the ~/.copilot configuration directory, and settings in those files, should go in cli-config-dir-reference.md. - All reference details relating to hooks should go in cli-hooks-reference.md. - All other CLI topics (MCP, skills, agents, permissions, etc.) belong in cli-command-reference.md even when they mention plugins. + content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md covers only plugin-specific content. + All information relating to files in the ~/.copilot configuration directory, and settings in those files, should go in content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md. + All reference details relating to hooks should go in content/copilot/reference/hooks-reference.md. + All other CLI topics (MCP, skills, agents, permissions, etc.) belong in content/copilot/reference/copilot-cli-reference/cli-command-reference.md even when they mention plugins. # TODO # mcp-server: diff --git a/src/content-pipelines/state/copilot-cli.sha b/src/content-pipelines/state/copilot-cli.sha index 35c06a62d26c..660d0de0321c 100644 --- a/src/content-pipelines/state/copilot-cli.sha +++ b/src/content-pipelines/state/copilot-cli.sha @@ -1 +1 @@ -391259f70310fc987767077c68d29b5e38b28263 +d37d2243a99b9136587359a66e824ca93f0b7d90 diff --git a/src/graphql/data/fpt/schema.docs.graphql b/src/graphql/data/fpt/schema.docs.graphql index a9edf4e33961..66088291b55d 100644 --- a/src/graphql/data/fpt/schema.docs.graphql +++ b/src/graphql/data/fpt/schema.docs.graphql @@ -23,6 +23,16 @@ directive @possibleTypes( concreteTypes: [String!]! ) on INPUT_FIELD_DEFINITION +""" +Assigns a documentation category for docs.github.com, aligned with REST API reference sections. +""" +directive @docsCategory( + """ + The category slug (e.g. "issues", "pulls", "repos"). + """ + name: String! +) on ENUM | INPUT_OBJECT | INTERFACE | OBJECT | UNION + """ Autogenerated input type of AbortQueuedMigrations """ diff --git a/src/graphql/data/ghec/schema.docs.graphql b/src/graphql/data/ghec/schema.docs.graphql index adb881a77d3f..4ab4373f7b64 100644 --- a/src/graphql/data/ghec/schema.docs.graphql +++ b/src/graphql/data/ghec/schema.docs.graphql @@ -23,6 +23,16 @@ directive @possibleTypes( concreteTypes: [String!]! ) on INPUT_FIELD_DEFINITION +""" +Assigns a documentation category for docs.github.com, aligned with REST API reference sections. +""" +directive @docsCategory( + """ + The category slug (e.g. "issues", "pulls", "repos"). + """ + name: String! +) on ENUM | INPUT_OBJECT | INTERFACE | OBJECT | UNION + """ Autogenerated input type of AbortQueuedMigrations """