From 1804c197a91b8691704b04f1268d1dbbc686420b Mon Sep 17 00:00:00 2001 From: Sophie <29382425+sophietheking@users.noreply.github.com> Date: Thu, 5 Dec 2024 15:27:40 +0100 Subject: [PATCH] [Copilot] Context Passing (Public Preview) (#53356) Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com> --- .../about-building-copilot-extensions.md | 15 ++++++++++++ ...r-github-app-for-your-copilot-extension.md | 4 ++-- ...egrate-external-tools-with-copilot-chat.md | 24 ++++++++++++++++++- .../copilot-extensions/account-permissions.md | 3 +++ .../context-passing-public-preview-note.md | 1 + 5 files changed, 44 insertions(+), 3 deletions(-) create mode 100644 data/reusables/copilot/copilot-extensions/account-permissions.md create mode 100644 data/reusables/copilot/copilot-extensions/context-passing-public-preview-note.md diff --git a/content/copilot/building-copilot-extensions/about-building-copilot-extensions.md b/content/copilot/building-copilot-extensions/about-building-copilot-extensions.md index eca5460c8121..e5ebdd253ed1 100644 --- a/content/copilot/building-copilot-extensions/about-building-copilot-extensions.md +++ b/content/copilot/building-copilot-extensions/about-building-copilot-extensions.md @@ -51,6 +51,21 @@ type: overview For more information about skillsets, see "[AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/about-copilot-skillsets)." {% data reusables.copilot.copilot-extensions.differences-between-agents-and-skillsets-2 %} +### About context passing + +{% data reusables.copilot.copilot-extensions.context-passing-public-preview-note %} + +You can allow your {% data variables.product.prodname_copilot_extension_short %} to receive context from the editor, such as the currently opened file, by enabling the **Read-only** access level for the "{% data variables.product.prodname_copilot_short %} Editor Context" permission in your {% data variables.product.prodname_github_app %} settings. See "[AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension#creating-a-github-app)." + +The {% data variables.product.prodname_copilot_extensibility_platform %} automatically handles messaging when implicit and explicit context is unavailable or unauthorized. To enable context passing, you are required to request permissions from users. When requesting permissions, follow these best practices: + +* Clearly communicate what context you need and what you need it for. +* Implement appropriate error handling for unavailable context that your own application logic and API calls. +* In the event context is unavailable, provide value where possible without this data. +* Request only the minimum required permissions for your extension. + +Context passing respects content exclusions, `.env` files, and files listed in the content exclusion settings. + ### Resources for building {% data variables.product.prodname_copilot_extensions %} {% data variables.product.company_short %} provides a comprehensive toolkit for extension builders, with code samples, a CLI debugging tool, quickstart SDKs, and a user feedback repository. For more information, see the [copilot-extensions](https://github.com/orgs/copilot-extensions/) organization on {% data variables.product.company_short %}. diff --git a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-extension.md b/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-extension.md index a5d12ec40c3b..d13798bb6302 100644 --- a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-extension.md +++ b/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-extension.md @@ -36,7 +36,7 @@ Once you have configured your server and created your {% data variables.product. 1. In the left sidebar, click **Permissions & events**. 1. To expand the "Account permissions" section, click anywhere in the section. -1. In the "{% data variables.product.prodname_copilot_chat %}" row, select the **Access:** dropdown menu, then click **Read-only**. Click **Save changes**. +{% data reusables.copilot.copilot-extensions.account-permissions %} 1. In the left sidebar, click **{% data variables.product.prodname_copilot_short %}**. 1. Read the {% data variables.product.prodname_marketplace %} Developer Agreement and the {% data variables.product.github %} Pre-release License Terms, then accept the terms for creating a {% data variables.product.prodname_copilot_extension_short %}. @@ -68,7 +68,7 @@ Once you have configured your server and created your {% data variables.product. 1. In the left sidebar, click **Permissions & events**. 1. To expand the "Account permissions" section, click anywhere in the section. -1. In the "{% data variables.product.prodname_copilot_chat %}" row, select the **Access:** dropdown menu, then click **Read-only**. Click **Save changes**. +{% data reusables.copilot.copilot-extensions.account-permissions %} 1. In the left sidebar, click **{% data variables.product.prodname_copilot_short %}**. 1. Read the {% data variables.product.prodname_marketplace %} Developer Agreement and the {% data variables.product.github %} Pre-release License Terms, then accept the terms for creating a {% data variables.product.prodname_copilot_extension_short %}. diff --git a/content/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat.md b/content/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat.md index b30c687ee732..299f60b2091d 100644 --- a/content/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat.md +++ b/content/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat.md @@ -40,6 +40,28 @@ You can interact with your custom-built or installed extension in a {% data vari {% data reusables.copilot.copilot-extensions.supported-clients-and-ides-table %} +## About context passing in {% data variables.product.prodname_copilot_extensions %} + +{% data reusables.copilot.copilot-extensions.context-passing-public-preview-note %} + +{% data variables.product.prodname_copilot_extensions %} can access certain contextual information depending on where you're using them. This context passing happens automatically when you interact with an extension, but requires your explicit authorization through {% data variables.product.prodname_github_app %} permissions for use in any organization-owned repositories. + +Context passing helps extensions understand your current work environment to provide more relevant assistance, while maintaining security through permission controls. Context passing also respects content exclusions, `.env` files, and files listed in your content exclusion settings. + +The following table shows the contexts that are passed to {% data variables.product.prodname_copilot_extensions %} based on the client or IDE you are using. + +{% rowheaders %} + +| Client or IDE | client.file | client.selection | github.repository | github.current-url | Additional contexts | +| ------------------ | ----------- | ---------------- | ----------------- | ------------------ | ------------------------------------------------- | +| {% data variables.product.prodname_vscode %} | Yes | Yes | Yes | No | Repository owner and branch | +| {% data variables.product.prodname_vs %} | Yes | Yes | Yes | No | Repository owner and branch | +| {% data variables.product.prodname_dotcom_the_website %} | No | No | Yes | Yes | Repository information and other {% data variables.product.github %} resources | +| {% data variables.product.prodname_mobile %} | No | No | No | Yes | Not applicable | +| JetBrains IDEs | No | No | No | Yes | Not applicable | + +{% endrowheaders %} + ## Prerequisites **If you have a {% data variables.product.prodname_copilot_individuals_short %} subscription**, you need to install a {% data variables.product.prodname_copilot_extension_short %} before you can use the extension in {% data variables.product.prodname_copilot_chat_short %}. See "[AUTOTITLE](/copilot/github-copilot-chat/github-copilot-extensions/installing-github-copilot-extensions-for-your-personal-account)." @@ -82,7 +104,7 @@ For questions and issues related to {% data variables.product.prodname_copilot_e * **{% data variables.product.github %} Technology Partners:** Email the partnerships team directly for assistance. * **{% data variables.product.prodname_copilot_extensions_vsc %}:** For more information on this type of {% data variables.product.prodname_copilot_extension_short %}, see [Chat extensions](https://code.visualstudio.com/api/extension-guides/chat) in the {% data variables.product.prodname_vscode %} documentation. -> [!NOTE] {% data variables.product.github %} Support is not able to answer questions regarding {% data variables.product.prodname_copilot_extensions_vsc %}, as this implementation path is owned and maintained by the {% data variables.product.prodname_vscode_shortname %} team. +> [!NOTE] {% data variables.contact.github_support %} is not able to answer questions regarding {% data variables.product.prodname_copilot_extensions_vsc %}, as this implementation path is owned and maintained by the {% data variables.product.prodname_vscode_shortname %} team. ## Further reading diff --git a/data/reusables/copilot/copilot-extensions/account-permissions.md b/data/reusables/copilot/copilot-extensions/account-permissions.md new file mode 100644 index 000000000000..b7f3a98de740 --- /dev/null +++ b/data/reusables/copilot/copilot-extensions/account-permissions.md @@ -0,0 +1,3 @@ +1. In the "{% data variables.product.prodname_copilot_chat %}" row, select the **Access:** dropdown menu, then click **Read-only**. +1. To enable the application to receive editor content (for example the currently opened file), in the "{% data variables.product.prodname_copilot_short %} Editor Context" row, select the **Access:** dropdown menu, then click **Read-only**. +1. Click **Save changes**. diff --git a/data/reusables/copilot/copilot-extensions/context-passing-public-preview-note.md b/data/reusables/copilot/copilot-extensions/context-passing-public-preview-note.md new file mode 100644 index 000000000000..e297f16324cc --- /dev/null +++ b/data/reusables/copilot/copilot-extensions/context-passing-public-preview-note.md @@ -0,0 +1 @@ +> [!NOTE] Context passing is in {% data variables.release-phases.public_preview %} and subject to change.