diff --git a/CHANGELOG.md b/CHANGELOG.md index eb4bf8f8b096..ae7dafe8c72e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # Docs changelog +**24 October 2025** + +To support the enterprise roles and teams public preview, we: + +* Created a new concepts category in the [enterprise admin](https://docs.github.com/en/enterprise-cloud@latest/admin) docs aimed at onboarding administrators, including new articles on roles and teams in an enterprise. +* Built a user journey for setting up roles, teams, and apps to simplify administration, starting with [Identifying the roles required by your enterprise](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/identify-role-requirements). +* Published how-to content on [creating custom roles](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/create-custom-roles), [creating enterprise teams](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/create-enterprise-teams), and [assigning roles](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/assign-roles). +* Communicated new conceptual frameworks and best practices for enterprise accounts, including [Best practices for organizing work in your enterprise](https://docs.github.com/en/enterprise-cloud@latest/admin/concepts/best-practices) and [Enterprise accounts](https://docs.github.com/en/enterprise-cloud@latest/admin/concepts/enterprise-fundamentals/enterprise-accounts). + +
+ **17 October 2025** We have updated the [Account and profile](https://docs.github.com/en/account-and-profile) and [Subscriptions and notifications](https://docs.github.com/en/subscriptions-and-notifications) docs for improved usability, scannability, and information architecture. diff --git a/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/abilities-of-roles.md b/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/abilities-of-roles.md index 4f0ef513b6b5..eb1f8fc8247e 100644 --- a/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/abilities-of-roles.md +++ b/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/abilities-of-roles.md @@ -11,6 +11,7 @@ redirect_from: - /admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/abilities-of-roles + - /early-access/enterprise/enterprise-roles/enterprise-security-manager versions: ghec: '*' ghes: '*' @@ -93,7 +94,7 @@ App managers can also be assigned to individual apps. See [AUTOTITLE](/admin/man ## Security managers > [!NOTE] -> The enterprise security manager role is in {% data variables.release-phases.public_preview %} and subject to change. The [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-pre-release-license-terms) apply to your use of this role. +> The enterprise security manager role is in {% data variables.release-phases.public_preview %} and subject to change. Security managers have the permissions required to effectively manage use of security features and alerts for the enterprise. They can view, manage, and assign: diff --git a/content/copilot/concepts/prompting/response-customization.md b/content/copilot/concepts/prompting/response-customization.md index aeb9a9b2b047..66053e4eec12 100644 --- a/content/copilot/concepts/prompting/response-customization.md +++ b/content/copilot/concepts/prompting/response-customization.md @@ -14,117 +14,69 @@ redirect_from: contentType: concepts --- + + {% webui %} > [!NOTE] This version of this article is about custom instructions on the {% data variables.product.github %} website. Click the tabs above for other environments. -{% endwebui %} - -{% vscode %} - -> [!NOTE] This version of this article is about custom instructions and prompt files in {% data variables.product.prodname_vscode_shortname %}. Click the tabs above for other environments. - -{% endvscode %} - -{% visualstudio %} - -> [!NOTE] This version of this article is about custom instructions in {% data variables.product.prodname_vs %}. Click the tabs above for other environments. - -{% endvisualstudio %} - -{% jetbrains %} - -> [!NOTE] This version of this article is about custom instructions and prompt files in JetBrains IDEs. Click the tabs above for other environments. -{% endjetbrains %} - -{% xcode %} - -> [!NOTE] This version of this article is about custom instructions in Xcode. Click the tabs above for other environments. -{% endxcode %} - -{% eclipse %} - -> [!NOTE] This version of this article is about custom instructions in Eclipse. Click the tabs above for other environments. -{% endeclipse %} - ## About customizing {% data variables.product.prodname_copilot_short %} responses -{% webui %} - {% data variables.product.prodname_copilot %} can provide responses that are tailored to your personal preferences, the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create custom instructions that automatically add this information for you. The additional information is not displayed, but is available to {% data variables.product.prodname_copilot_short %} to allow it to generate higher quality responses. -### Types of custom instructions - -* **Personal custom instructions** apply to all conversations you have with {% data variables.product.prodname_copilot_short %} across the {% data variables.product.github %} website. They allow you to specify your individual preferences, such as preferred language or response style, ensuring that the responses are tailored to your personal needs. -* **Repository custom instructions** apply to conversations within the context of a specific repository. They are useful for defining project-specific coding standards, frameworks, or tools. For example, you can specify that a repository uses TypeScript and a particular library, ensuring consistent responses for all contributors. -* **Organization custom instructions (public preview)** apply to conversations within the context of an organization on the {% data variables.product.github %} website. They are ideal for enforcing organization-wide preferences, such as a common language or security guidelines. Organization custom instructions can only be set by organization owners for organizations with a {% data variables.copilot.copilot_enterprise_short %} subscription. - -### About repository custom instructions - -You can create two types of repository custom instructions for {% data variables.product.prodname_copilot_short %} on {% data variables.product.prodname_dotcom_the_website %}: - -{% data reusables.copilot.custom-instructions-about %} - -{% endwebui %} - -{% vscode %} +## Types of custom instructions -{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create files in your repository that automatically add this information for you. +There are three main types of custom instructions that you can use to customize {% data variables.product.prodname_copilot_short %} responses on the {% data variables.product.github %} website: -There are two types of files you can use to provide context and instructions to {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode_shortname %}: - -* **Repository custom instructions** allow you to specify instructions and preferences that {% data variables.product.prodname_copilot_short %} will consider when working in the context of the repository. -* **Prompt files** (public preview) allow you to save common prompt instructions and relevant context in Markdown files (`*.prompt.md`) that you can then reuse in your chat prompts. {% data reusables.copilot.prompt-files-available-in-editors %} - -While custom instructions help to add codebase-wide context to each AI workflow, prompt files let you add instructions to a specific chat interaction. - -{% endvscode %} - -{% visualstudio %} +* **[Personal custom instructions](#about-personal-custom-instructions)** apply to all conversations you have with {% data variables.copilot.copilot_chat_short %} across the {% data variables.product.github %} website. They allow you to specify your individual preferences, such as preferred language or response style, ensuring that the responses are tailored to your personal needs. +* **[Repository custom instructions](#about-repository-custom-instructions)** apply to conversations within the context of a specific repository. They are useful for defining project-specific coding standards, frameworks, or tools. For example, you can specify that a repository uses TypeScript and a particular library, ensuring consistent responses for all contributors. +* **[Organization custom instructions](#about-organization-custom-instructions)** (public preview) apply to conversations within the context of an organization on the {% data variables.product.github %} website. They are ideal for enforcing organization-wide preferences, such as a common language or security guidelines. Organization custom instructions can only be set by organization owners for organizations with a {% data variables.copilot.copilot_enterprise_short %} subscription. -{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create a custom instructions file in your repository that automatically adds this information for you. The additional information is not displayed in the chat input box, but is available to {% data variables.product.prodname_copilot_short %} to allow it to generate higher quality responses. +## About personal custom instructions -{% endvisualstudio %} +{% data reusables.copilot.personal-instructions-note %} -{% jetbrains %} +You can customize how {% data variables.copilot.copilot_chat_short %} responds to you on {% data variables.product.prodname_dotcom_the_website %} by adding personal instructions, which {% data variables.product.prodname_copilot_short %} will only apply to you. You do this in a popup on the {% data variables.copilot.copilot_chat_short %} page on {% data variables.product.prodname_dotcom_the_website %}. See [AUTOTITLE](/copilot/how-tos/configure-custom-instructions/add-personal-instructions). -{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create a custom instructions file in your repository that automatically adds this information for you. +## About repository custom instructions -There are two types of files you can use to provide context and instructions to {% data variables.product.prodname_copilot_short %} in JetBrains IDEs: +You can use three types of repository custom instructions in {% data variables.product.prodname_copilot_short %} on {% data variables.product.prodname_dotcom_the_website %}: -* **Repository custom instructions** allow you to specify instructions and preferences that {% data variables.product.prodname_copilot_short %} will consider when working in the context of the repository. -* **Prompt files** (public preview) allow you to save common prompt instructions and relevant context in Markdown files (`*.prompt.md`) that you can then reuse in your chat prompts. {% data reusables.copilot.prompt-files-available-in-editors %} +{% data reusables.copilot.custom-instructions-about %} -While custom instructions help to add codebase-wide context to each AI workflow, prompt files let you add instructions to a specific chat interaction. +{% data reusables.copilot.repository-custom-instructions-support %} -{% endjetbrains %} +## About organization custom instructions -{% xcode %} +{% data reusables.copilot.custom-instructions-org-support %} -{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create a custom instructions file in your repository that automatically adds this information for you. The additional information is not displayed in the chat input box, but is available to {% data variables.product.prodname_copilot_short %} to allow it to generate higher quality responses. +Organization owners can add instructions for {% data variables.product.prodname_copilot_short %}, to tailor responses to the needs and preferences of your organization. For example, you can choose to always have {% data variables.product.prodname_copilot_short %} respond in your company's language of choice or with a particular style. -{% endxcode %} +Custom instructions defined in an organization's {% data variables.product.prodname_copilot_short %} settings are used for all members of the organization, irrespective of whether they receive their {% data variables.product.prodname_copilot_short %} subscription from that organization. -{% eclipse %} +Some examples of instructions you could add are: +* `Always respond in Spanish.` +* `Do not generate code blocks in responses.` +* `For questions related to security, use the Security Docs Knowledge Base.` -{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create a custom instructions file in your repository that automatically adds this information for you. The additional information is not displayed in the chat input box, but is available to {% data variables.product.prodname_copilot_short %} to allow it to generate higher quality responses. +## Precedence of custom instructions -There are two types of repository custom instructions you can use to provide context and instructions to {% data variables.product.prodname_copilot_short %} in Eclipse: +{% data reusables.copilot.custom-instructions-chat-precedence %} -* **Workspace custom instructions** which apply to all projects in a workspace, and allow you to specify workspace-wide instructions and preferences, in a single file. -* **Project custom instructions** which apply to a specific project. +The following list shows the complete order of precedence, with instructions higher in this list taking precedence over those lower in the list: -{% endeclipse %} +* Personal custom instructions +* Repository custom instructions: + * Path-specific instructions in any applicable `.github/instructions/**/NAME.instructions.md` file + * Repository-wide instructions in the `.github/copilot-instructions.md` file + * Agent instructions (for example, in an `AGENTS.md` file) +* Organization custom instructions -{% webui %} +{% data reusables.copilot.custom-instructions-conflict %} ## Using custom instructions -Custom instructions consist of natural language instructions and are most effective when they are short, self-contained statements. Consider the scope over which you want the instruction to apply when choosing whether to add an instruction on the personal, repository, or (if available) organization level. - -> [!NOTE] -> * {% data reusables.copilot.custom-instructions-chat-precedence %} -> * {% data reusables.copilot.custom-instructions-conflict %} +Custom instructions consist of natural language instructions and are most effective when they are short, self-contained statements. Consider the scope over which you want the instruction to apply when choosing whether to add an instruction on the personal, repository, or organization level. Here are some common use cases and examples for each type of custom instructions: * **Personal custom instructions:** @@ -139,16 +91,43 @@ Here are some common use cases and examples for each type of custom instructions * Preferred language for a company which exclusively speaks a single language: `Always respond in Portuguese.` * Organization-wide preferences: `Do not generate code blocks in responses.` +{% data reusables.copilot.custom-instructions-effective %} + +## Next steps + +* [AUTOTITLE](/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot) +* [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) +* [AUTOTITLE](/copilot/customizing-copilot/adding-organization-custom-instructions-for-github-copilot) + {% endwebui %} + + + + {% vscode %} +> [!NOTE] This version of this article is about custom instructions and prompt files in {% data variables.product.prodname_vscode_shortname %}. Click the tabs above for other environments. + +## About customizing {% data variables.product.prodname_copilot_short %} responses + +{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create files in your repository that automatically add this information for you. + +There are two types of files you can use to provide context and instructions to {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode_shortname %}: + +* **Repository custom instructions** allow you to specify instructions and preferences that {% data variables.product.prodname_copilot_short %} will consider when working in the context of the repository. +* **Prompt files** (public preview) allow you to save common prompt instructions and relevant context in Markdown files (`*.prompt.md`) that you can then reuse in your chat prompts. {% data reusables.copilot.prompt-files-available-in-editors %} + +While custom instructions help to add codebase-wide context to each AI workflow, prompt files let you add instructions to a specific chat interaction. + ## About repository custom instructions -You can create two types of repository custom instructions for use in {% data variables.product.prodname_vscode_shortname %}: +You can use three types of repository custom instructions in {% data variables.product.prodname_vscode_shortname %}: {% data reusables.copilot.custom-instructions-about %} +{% data reusables.copilot.repository-custom-instructions-support %} + ## About prompt files > [!NOTE] Prompt files are {% data variables.release-phases.public_preview %} and subject to change. @@ -198,15 +177,35 @@ The following examples demonstrate how to use prompt files. … ``` +{% data reusables.copilot.custom-instructions-effective %} + +## Next steps + +* [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) + {% endvscode %} + + + + {% visualstudio %} +> [!NOTE] This version of this article is about custom instructions in {% data variables.product.prodname_vs %}. Click the tabs above for other environments. + +## About customizing {% data variables.product.prodname_copilot_short %} responses + +{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create a custom instructions file in your repository that automatically adds this information for you. The additional information is not displayed in the chat input box, but is available to {% data variables.product.prodname_copilot_short %} to allow it to generate higher quality responses. + ## About repository custom instructions -Repository custom instructions consist of a single file, `.github/copilot-instructions.md`, that you create in a repository. The instructions you add to the file should be short, self-contained statements that add context or relevant information to supplement a {% data variables.product.prodname_copilot_short %} prompt. +In {% data variables.product.prodname_vs %}, repository custom instructions consist of a single file, `.github/copilot-instructions.md`, that you create in a repository. The instructions you add to the file should be short, self-contained statements that add context or relevant information to supplement a {% data variables.product.prodname_copilot_short %} prompt. -Common use cases include: +{% data reusables.copilot.repository-custom-instructions-support %} + +### Use cases for custom instructions + +Common use cases for repository custom instructions include: * **Test generation.** Create instructions for test generation, such as specifying the use of a certain test framework. * **Code review.** Specify instructions for reviewing code, such as telling a reviewer to look for a specific error in the code. @@ -218,15 +217,42 @@ Common use cases include: For a curated collection of examples, see [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions). +{% data reusables.copilot.custom-instructions-effective %} + +## Next steps + +* [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) + {% endvisualstudio %} + + + + {% jetbrains %} +> [!NOTE] This version of this article is about custom instructions and prompt files in JetBrains IDEs. Click the tabs above for other environments. + +## About customizing {% data variables.product.prodname_copilot_short %} responses + +{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create a custom instructions file in your repository that automatically adds this information for you. + +There are two types of files you can use to provide context and instructions to {% data variables.product.prodname_copilot_short %} in JetBrains IDEs: + +* **Repository custom instructions** allow you to specify instructions and preferences that {% data variables.product.prodname_copilot_short %} will consider when working in the context of the repository. +* **Prompt files** (public preview) allow you to save common prompt instructions and relevant context in Markdown files (`*.prompt.md`) that you can then reuse in your chat prompts. {% data reusables.copilot.prompt-files-available-in-editors %} + +While custom instructions help to add codebase-wide context to each AI workflow, prompt files let you add instructions to a specific chat interaction. + ## About repository custom instructions -Repository custom instructions consist of a single file, `.github/copilot-instructions.md`, that you create in a repository. The instructions you add to the file should be short, self-contained statements that add context or relevant information to supplement a {% data variables.product.prodname_copilot_short %} prompt. +In JetBrains IDEs, repository custom instructions consist of a single file, `.github/copilot-instructions.md`, that you create in a repository. The instructions you add to the file should be short, self-contained statements that add context or relevant information to supplement a {% data variables.product.prodname_copilot_short %} prompt. -Common use cases include: +{% data reusables.copilot.repository-custom-instructions-support %} + +### Use cases for custom instructions + +Common use cases for custom instructions include: * **Test generation.** Create instructions for test generation, such as specifying the use of a certain test framework. * **Code review.** Specify instructions for reviewing code, such as telling a reviewer to look for a specific error in the code. @@ -287,35 +313,35 @@ The following examples demonstrate how to use prompt files. … ``` -{% endjetbrains %} +{% data reusables.copilot.custom-instructions-effective %} -{% xcode %} +## Next steps -## About repository custom instructions +* [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) -Repository custom instructions consist of a single file, `.github/copilot-instructions.md`, that you create in a repository. The instructions you add to the file should be short, self-contained statements that add context or relevant information to supplement a {% data variables.product.prodname_copilot_short %} prompt. +{% endjetbrains %} -Common use cases include: + -* **Test generation.** Create instructions for test generation, such as specifying the use of a certain test framework. -* **Code review.** Specify instructions for reviewing code, such as telling a reviewer to look for a specific error in the code. -* **Commit message generation.** Write instructions for generating commit messages, such as format or the type of information to include. + -### Example +{% xcode %} -{% data reusables.copilot.repository-custom-instructions-example %} +> [!NOTE] This version of this article is about custom instructions in Xcode. Click the tabs above for other environments. -{% endxcode %} +## About customizing {% data variables.product.prodname_copilot_short %} responses -{% eclipse %} +{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create a custom instructions file in your repository that automatically adds this information for you. The additional information is not displayed in the chat input box, but is available to {% data variables.product.prodname_copilot_short %} to allow it to generate higher quality responses. ## About repository custom instructions -**Workspace custom instructions** apply to all projects in a workspace, and allow you to specify workspace-wide instructions and preferences. You can use workspace custom instructions to provide context and instructions to {% data variables.product.prodname_copilot_short %} in Eclipse. +In Xcode, repository custom instructions consist of a single file, `.github/copilot-instructions.md`, that you create in a repository. The instructions you add to the file should be short, self-contained statements that add context or relevant information to supplement a {% data variables.product.prodname_copilot_short %} prompt. -**Project custom instructions** consist of a single file, `.github/copilot-instructions.md`, that you create in a project. The instructions you add to the file should be short, self-contained statements that add context or relevant information to supplement a {% data variables.product.prodname_copilot_short %} prompt. +{% data reusables.copilot.repository-custom-instructions-support %} -Common use cases include: +### Use cases for custom instructions + +Common use cases for repository custom instructions include: * **Test generation.** Create instructions for test generation, such as specifying the use of a certain test framework. * **Code review.** Specify instructions for reviewing code, such as telling a reviewer to look for a specific error in the code. @@ -325,68 +351,55 @@ Common use cases include: {% data reusables.copilot.repository-custom-instructions-example %} -For a curated collection of examples, see [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions). - -{% endeclipse %} - -## Writing effective custom instructions - -The instructions you add should ideally be short, self-contained statements provide {% data variables.product.prodname_copilot_short %} with relevant information to help it work. +{% data reusables.copilot.custom-instructions-effective %} -When writing custom instructions for a repository, you should also consider the size and complexity of your repository. The following types of instructions may work for a small repository with only a few contributors, but for a large and diverse repository, **these may cause problems**: - -* Requests to refer to external resources when formulating a response -* Instructions to answer in a particular style -* Requests to always respond with a certain level of detail - -For example, the following instructions **may not have the intended results**: - -```markdown -Always conform to the coding styles defined in styleguide.md in repo my-org/my-repo when generating code. +## Next steps -Use @terminal when answering questions about Git. +* [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) -Answer all questions in the style of a friendly colleague, using informal language. +{% endxcode %} -Answer all questions in less than 1000 characters, and words of no more than 12 characters. -``` + -## Next steps + -{% webui %} +{% eclipse %} -* [AUTOTITLE](/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot) -* [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) -* [AUTOTITLE](/copilot/customizing-copilot/adding-organization-custom-instructions-for-github-copilot) +> [!NOTE] This version of this article is about custom instructions in Eclipse. Click the tabs above for other environments. -{% endwebui %} +## About customizing {% data variables.product.prodname_copilot_short %} responses -{% vscode %} +{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create a custom instructions file in your repository that automatically adds this information for you. The additional information is not displayed in the chat input box, but is available to {% data variables.product.prodname_copilot_short %} to allow it to generate higher quality responses. -* [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) +There are two types of repository custom instructions you can use to provide context and instructions to {% data variables.product.prodname_copilot_short %} in Eclipse: -{% endvscode %} +* **Workspace custom instructions** which apply to all projects in a workspace, and allow you to specify workspace-wide instructions and preferences, in a single file. +* **Project custom instructions** which apply to a specific project. -{% visualstudio %} +## About repository custom instructions -* [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) +**Workspace custom instructions** apply to all projects in a workspace, and allow you to specify workspace-wide instructions and preferences. You can use workspace custom instructions to provide context and instructions to {% data variables.product.prodname_copilot_short %} in Eclipse. -{% endvisualstudio %} +**Project custom instructions** consist of a single file, `.github/copilot-instructions.md`, that you create in a project. The instructions you add to the file should be short, self-contained statements that add context or relevant information to supplement a {% data variables.product.prodname_copilot_short %} prompt. -{% jetbrains %} +Common use cases include: -* [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) +* **Test generation.** Create instructions for test generation, such as specifying the use of a certain test framework. +* **Code review.** Specify instructions for reviewing code, such as telling a reviewer to look for a specific error in the code. +* **Commit message generation.** Write instructions for generating commit messages, such as format or the type of information to include. -{% endjetbrains %} +### Example -{% xcode %} +{% data reusables.copilot.repository-custom-instructions-example %} -* [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) +For a curated collection of examples, see [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions). -{% endxcode %} +{% data reusables.copilot.custom-instructions-effective %} -{% eclipse %} +## Next steps * [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) {% endeclipse %} + + diff --git a/content/copilot/how-tos/configure-custom-instructions/add-organization-instructions.md b/content/copilot/how-tos/configure-custom-instructions/add-organization-instructions.md index 7f2957bf8921..92376d20b276 100644 --- a/content/copilot/how-tos/configure-custom-instructions/add-organization-instructions.md +++ b/content/copilot/how-tos/configure-custom-instructions/add-organization-instructions.md @@ -15,28 +15,9 @@ redirect_from: contentType: how-tos --- -> [!NOTE] -> This feature is currently in {% data variables.release-phases.public_preview %} and is subject to change. -> -> **Support:** Organization custom instructions are currently only supported for {% data variables.copilot.copilot_chat_short %} on {% data variables.product.prodname_dotcom_the_website %} and {% data variables.copilot.copilot_code-review_short %} on {% data variables.product.prodname_dotcom_the_website %}. +{% data reusables.copilot.custom-instructions-org-support %} -For an overview of the methods you can use to customize {% data variables.copilot.copilot_chat %} responses, see [AUTOTITLE](/copilot/concepts/about-customizing-github-copilot-chat-responses?tool=webui). - -## About organization custom instructions for {% data variables.product.prodname_copilot_short %} - -Organization owners can add instructions for {% data variables.product.prodname_copilot_short %}, to tailor responses to the needs and preferences of your organization. For example, you can choose to always have {% data variables.copilot.copilot_chat_short %} respond in your company's language of choice or with a particular style. - -Custom instructions defined in an organization's {% data variables.product.prodname_copilot_short %} settings are used for all members of the organization, irrespective of whether they receive their {% data variables.product.prodname_copilot_short %} subscription from that organization. - -Some examples of instructions you could add are: -* `Always respond in Spanish.` -* `Do not generate code blocks in responses.` -* `For questions related to security, use the Security Docs Knowledge Base.` - -> [!NOTE] -> * {% data reusables.copilot.custom-instructions-chat-precedence %} -> * For {% data variables.copilot.copilot_code-review_short %}, the order of precedence is: instructions in any applicable `.github/instructions/**/NAME.instructions.md` file, then the instructions in the `.github/copilot-instructions.md` file, then the organization-level custom instructions. -> * {% data reusables.copilot.custom-instructions-conflict %} +Organization owners can add instructions for {% data variables.product.prodname_copilot_short %}, to tailor responses to specific needs and preferences across the organization. For an overview of this, and other types of custom instructions for {% data variables.product.prodname_copilot_short %}, see [AUTOTITLE](/copilot/concepts/about-customizing-github-copilot-chat-responses?tool=webui). ## Adding organization custom instructions diff --git a/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md b/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md index 1f7a4487b946..23e686672270 100644 --- a/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md +++ b/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md @@ -19,7 +19,7 @@ redirect_from: This version of this article is for using repository custom instructions on the {% data variables.product.github %} website. Click the tabs above for information on using custom instructions in other environments. -{% data reusables.copilot.repository-custom-instructions-support %} +{% data reusables.copilot.repository-custom-instructions-about %} {% data reusables.copilot.repository-custom-instructions-prerequisites %} @@ -29,7 +29,7 @@ This version of this article is for using repository custom instructions on the This version of this article is for using repository custom instructions and prompt files in {% data variables.product.prodname_vscode_shortname %}. Click the tabs above for instructions on using custom instructions in other environments. -{% data reusables.copilot.repository-custom-instructions-support %} +{% data reusables.copilot.repository-custom-instructions-about %} {% data reusables.copilot.repository-custom-instructions-prerequisites %} @@ -39,7 +39,7 @@ This version of this article is for using repository custom instructions and pro This version of this article is for using repository custom instructions in {% data variables.product.prodname_vs %}. Click the tabs above for instructions on using custom instructions in other environments. -{% data reusables.copilot.repository-custom-instructions-support %} +{% data reusables.copilot.repository-custom-instructions-about %} {% data reusables.copilot.repository-custom-instructions-prerequisites %} @@ -49,7 +49,7 @@ This version of this article is for using repository custom instructions in {% d This version of this article is for using repository custom instructions in JetBrains IDEs. Click the tabs above for instructions on using custom instructions in other environments. -{% data reusables.copilot.repository-custom-instructions-support %} +{% data reusables.copilot.repository-custom-instructions-about %} {% data reusables.copilot.repository-custom-instructions-prerequisites %} @@ -59,7 +59,7 @@ This version of this article is for using repository custom instructions in JetB This version of this article is for using repository custom instructions in Xcode. Click the tabs above for instructions on using custom instructions in other environments. -{% data reusables.copilot.repository-custom-instructions-support %} +{% data reusables.copilot.repository-custom-instructions-about %} {% data reusables.copilot.repository-custom-instructions-prerequisites %} @@ -79,7 +79,7 @@ This version of this article is for using repository custom instructions with th This version of this article is for using repository custom instructions in Eclipse. Click the tabs above for instructions on using custom instructions in other environments. -{% data reusables.copilot.repository-custom-instructions-support %} +{% data reusables.copilot.repository-custom-instructions-about %} {% data reusables.copilot.repository-custom-instructions-prerequisites %} @@ -207,7 +207,7 @@ Once saved, these instructions will apply to the current project in Eclipse that {% copilotcli %} -{% data variables.product.prodname_copilot %} supports three types of repository custom instructions. See the table above for details of which {% data variables.product.prodname_copilot %} features support these types of instructions. +{% data variables.product.prodname_copilot %} supports three types of repository custom instructions. * **Repository-wide custom instructions**, which apply to all requests made in the context of a repository. @@ -243,7 +243,7 @@ Once saved, these instructions will apply to the current project in Eclipse that {% vscode %} -{% data variables.product.prodname_vscode_shortname %} supports three types of repository custom instructions. See the table above for details of which {% data variables.product.prodname_copilot %} features support these types of instructions. +{% data variables.product.prodname_vscode_shortname %} supports three types of repository custom instructions. For details of which {% data variables.product.prodname_copilot %} features support these types of instructions, see [AUTOTITLE](/copilot/concepts/prompting/response-customization?tool=vscode#support-for-repository-custom-instructions-1). * **Repository-wide custom instructions**, which apply to all requests made in the context of a repository. @@ -297,7 +297,7 @@ Once saved, these instructions will apply to the current project in Eclipse that {% webui %} -{% data variables.product.prodname_copilot_short %} on {% data variables.product.github %} supports three types of repository custom instructions. See the table above for details of which {% data variables.product.prodname_copilot %} features support these types of instructions. +{% data variables.product.prodname_copilot_short %} on {% data variables.product.github %} supports three types of repository custom instructions. For details of which {% data variables.product.prodname_copilot %} features support these types of instructions, see [AUTOTITLE](/copilot/concepts/prompting/response-customization?tool=webui#support-for-repository-custom-instructions). * **Repository-wide custom instructions** apply to all requests made in the context of a repository. @@ -311,7 +311,7 @@ Once saved, these instructions will apply to the current project in Eclipse that * **Agent instructions** are used by AI agents. - You can create one or more `AGENTS.md` files, stored anywhere within the repository. When {% data variables.product.prodname_copilot_short %} is working, the nearest `AGENTS.md` file in the directory tree will take precedence. For more information, see the [openai/agents.md repository](https://github.com/openai/agents.md). + You can create one or more `AGENTS.md` files, stored anywhere within the repository. When {% data variables.product.prodname_copilot_short %} is working, the nearest `AGENTS.md` file in the directory tree will take precedence over other agent instructions files. For more information, see the [openai/agents.md repository](https://github.com/openai/agents.md). Alternatively, you can use a single `CLAUDE.md` or `GEMINI.md` file stored in the root of the repository. @@ -438,67 +438,6 @@ Did you successfully add a custom instructions file to your repository? {% endnote %} -## Writing effective repository custom instructions - -The instructions you add to your custom instruction file(s) should be short, self-contained statements that provide {% data variables.product.prodname_copilot_short %} with relevant information to help it work in this repository. Because the instructions are sent with every chat message, they should be broadly applicable to most requests you will make in the context of the repository. - -The exact structure you utilize for your instructions file(s) will vary by project and need, but the following guidelines provide a good starting point: - -* Provide an overview of the project you're working on, including its purpose, goals, and any relevant background information. -* Include the folder structure of the repository, including any important directories or files that are relevant to the project. -* Specify the coding standards and conventions that should be followed, such as naming conventions, formatting rules, and best practices. -* Include any specific tools, libraries, or frameworks that are used in the project, along with any relevant version numbers or configurations. - -The following instructions file(s) is an example of these practices in action: - -```markdown -# Project Overview - -This project is a web application that allows users to manage their tasks and to-do lists. It is built using React and Node.js, and uses MongoDB for data storage. - -## Folder Structure - -- `/src`: Contains the source code for the frontend. -- `/server`: Contains the source code for the Node.js backend. -- `/docs`: Contains documentation for the project, including API specifications and user guides. - -## Libraries and Frameworks - -- React and Tailwind CSS for the frontend. -- Node.js and Express for the backend. -- MongoDB for data storage. - -## Coding Standards - -- Use semicolons at the end of each statement. -- Use single quotes for strings. -- Use function based components in React. -- Use arrow functions for callbacks. - -## UI guidelines - -- A toggle is provided to switch between light and dark mode. -- Application should have a modern and clean design. -``` - -You should also consider the size and complexity of your repository. The following types of instructions may work for a small repository with only a few contributors, but for a large and diverse repository, **these may cause problems**: - -* Requests to refer to external resources when formulating a response -* Instructions to answer in a particular style -* Requests to always respond with a certain level of detail - -For example, the following instructions **may not have the intended results**: - -```markdown -Always conform to the coding styles defined in styleguide.md in repo my-org/my-repo when generating code. - -Use @terminal when answering questions about Git. - -Answer all questions in the style of a friendly colleague, using informal language. - -Answer all questions in less than 1000 characters, and words of no more than 12 characters. -``` - ## Repository custom instructions in use The instructions in the file(s) are available for use by {% data variables.product.prodname_copilot_short %} as soon as you save the file(s). The complete set of instructions will be automatically added to requests that you submit to {% data variables.product.prodname_copilot_short %} in the context of that repository. For example, they are added to the prompt you submit to {% data variables.copilot.copilot_chat_short %}. diff --git a/data/reusables/copilot/custom-instructions-about.md b/data/reusables/copilot/custom-instructions-about.md index 4ba8518d8b38..bd8260771ea1 100644 --- a/data/reusables/copilot/custom-instructions-about.md +++ b/data/reusables/copilot/custom-instructions-about.md @@ -2,15 +2,16 @@ These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. - Repository-wide custom instructions files are used for chat responses, for code review, and also by {% data variables.copilot.copilot_coding_agent %}. - * **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path. These are specified in one or more `NAME.instructions.md` files within the `.github/instructions` directory in the repository. By using path-specific instructions you can avoid overloading your repository-wide instructions with information that only applies to files of certain types, or in certain directories. - > [!NOTE] - > Currently, path-specific custom instructions files are only used by {% data variables.copilot.copilot_code-review_short %}, {% data variables.copilot.copilot_coding_agent %}, and {% data variables.copilot.copilot_chat_short %} in {% data variables.product.prodname_vscode_shortname %}. +* **Agent instructions**, which are similar to repository-wide custom instructions, but are currently not supported by all {% data variables.product.prodname_copilot_short %} features. + + These are specified in files called `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`. + +See the table below for details of support for each of these types of repository custom instructions across different {% data variables.product.prodname_copilot_short %} features. For a curated collection of examples, see [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions). diff --git a/data/reusables/copilot/custom-instructions-effective.md b/data/reusables/copilot/custom-instructions-effective.md new file mode 100644 index 000000000000..b67c576c0360 --- /dev/null +++ b/data/reusables/copilot/custom-instructions-effective.md @@ -0,0 +1,60 @@ +## Writing effective custom instructions + +The instructions you add to your custom instruction file(s) should be short, self-contained statements that provide {% data variables.product.prodname_copilot_short %} with relevant information to help it work in this repository. Because the instructions are sent with every chat message, they should be broadly applicable to most requests you will make in the context of the repository. + +The exact structure you utilize for your instructions file(s) will vary by project and need, but the following guidelines provide a good starting point: + +* Provide an overview of the project you're working on, including its purpose, goals, and any relevant background information. +* Include the folder structure of the repository, including any important directories or files that are relevant to the project. +* Specify the coding standards and conventions that should be followed, such as naming conventions, formatting rules, and best practices. +* Include any specific tools, libraries, or frameworks that are used in the project, along with any relevant version numbers or configurations. + +The following instructions file is an example of these practices in action: + +```markdown +# Project Overview + +This project is a web application that allows users to manage their tasks and to-do lists. It is built using React and Node.js, and uses MongoDB for data storage. + +## Folder Structure + +- `/src`: Contains the source code for the frontend. +- `/server`: Contains the source code for the Node.js backend. +- `/docs`: Contains documentation for the project, including API specifications and user guides. + +## Libraries and Frameworks + +- React and Tailwind CSS for the frontend. +- Node.js and Express for the backend. +- MongoDB for data storage. + +## Coding Standards + +- Use semicolons at the end of each statement. +- Use single quotes for strings. +- Use function based components in React. +- Use arrow functions for callbacks. + +## UI guidelines + +- A toggle is provided to switch between light and dark mode. +- Application should have a modern and clean design. +``` + +You should also consider the size and complexity of your repository. The following types of instructions may work for a small repository with only a few contributors, but for a large and diverse repository, **these may cause problems**: + +* Requests to refer to external resources when formulating a response +* Instructions to answer in a particular style +* Requests to always respond with a certain level of detail + +For example, the following instructions **may not have the intended results**: + +```markdown +Always conform to the coding styles defined in styleguide.md in repo my-org/my-repo when generating code. + +Use @terminal when answering questions about Git. + +Answer all questions in the style of a friendly colleague, using informal language. + +Answer all questions in less than 1000 characters, and words of no more than 12 characters. +``` diff --git a/data/reusables/copilot/custom-instructions-org-support.md b/data/reusables/copilot/custom-instructions-org-support.md new file mode 100644 index 000000000000..9477534df5ec --- /dev/null +++ b/data/reusables/copilot/custom-instructions-org-support.md @@ -0,0 +1,4 @@ +> [!NOTE] +> This feature is currently in {% data variables.release-phases.public_preview %} and is subject to change. +> +> **Support:** Organization custom instructions are currently only supported for {% data variables.copilot.copilot_chat_short %} on {% data variables.product.prodname_dotcom_the_website %} and {% data variables.copilot.copilot_code-review_short %} on {% data variables.product.prodname_dotcom_the_website %}. diff --git a/data/reusables/copilot/repository-custom-instructions-about.md b/data/reusables/copilot/repository-custom-instructions-about.md new file mode 100644 index 000000000000..32b7a8b39909 --- /dev/null +++ b/data/reusables/copilot/repository-custom-instructions-about.md @@ -0,0 +1,3 @@ +## Introduction + +Repository custom instructions let you provide {% data variables.product.prodname_copilot_short %} with repository-specific guidance and preferences. For more information, see [AUTOTITLE](/copilot/concepts/prompting/response-customization). diff --git a/data/reusables/copilot/repository-custom-instructions-support.md b/data/reusables/copilot/repository-custom-instructions-support.md index 0150f5853c9c..cdf2b9bb8b92 100644 --- a/data/reusables/copilot/repository-custom-instructions-support.md +++ b/data/reusables/copilot/repository-custom-instructions-support.md @@ -1,7 +1,3 @@ -## About repository custom instructions for {% data variables.product.prodname_copilot_short %} - -Repository custom instructions let you provide {% data variables.product.prodname_copilot_short %} with repository-specific guidance and preferences. For more information, see [AUTOTITLE](/copilot/concepts/prompting/response-customization). - ### Support for repository custom instructions The following table shows which {% data variables.product.prodname_copilot_short %} features support custom instructions in various environments.