New auto-CCR sub-options and docs for org-level custom instructions (#56922)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

content/copilot/concepts/code-review.md

@@ -78,16 +78,18 @@ By default, {% data variables.product.prodname_copilot_short %} will only review
 
 ### Triggering an automatic pull request review
 
-After you configure automatic code review, {% data variables.product.prodname_copilot_short %} will review pull requests in the following situations:
+The triggers for automatic code review depend on the configuration settings:
 
-* When a pull request is created as an "Open" pull request.
-
-  A review is not triggered if the pull request is created as a "Draft" pull request.
-
-* The first time a "Draft" pull request is switched to "Open".
+* **Basic setting**:
+  * When a pull request is created as an "Open" pull request.
+  * The first time a "Draft" pull request is switched to "Open".
+* **Review new pushes**:
+  * Every time a new commit is pushed to the pull request.
+* **Review draft pull requests**:
+  * Pull requests are automatically reviewed while they are still drafts—before being switched to "Open".
 
 > [!NOTE]
-> {% data variables.product.prodname_copilot_short %} only automatically reviews a pull request once. If you make changes to the pull request after it has been automatically reviewed and you want {% data variables.product.prodname_copilot_short %} to re-review the pull request, you must request this manually. To do this, click the {% octicon "sync" aria-label="Re-request review" %} button next to {% data variables.product.prodname_copilot_short %}'s name in the **Reviewers** menu.
+> Unless {% data variables.product.prodname_copilot_short %} has been configured to review each push to a pull request, it will only review the pull request once. If you make changes to the pull request after it has been automatically reviewed and you want {% data variables.product.prodname_copilot_short %} to re-review the pull request, you can request this manually. To do this, click the {% octicon "sync" aria-label="Re-request review" %} button next to {% data variables.product.prodname_copilot_short %}'s name in the **Reviewers** menu.
 
 ### Limits on automatic pull request reviews
 

content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md

@@ -75,13 +75,13 @@ Repository custom instructions are currently supported for:
 
 {% vscode %}
 
-* The **Use Instruction Files** option must be enabled in your settings. This is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions) later in this article.
+* Custom instructions must be enabled. This feature is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions-1) later in this article.
 
 {% endvscode %}
 
 {% visualstudio %}
 
-* The **Enable custom instructions...** option must be enabled in your settings. This is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions) later in this article.
+* The **Enable custom instructions...** option must be enabled in your settings. This is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions-2) later in this article.
 
 {% endvisualstudio %}
 
@@ -534,6 +534,8 @@ Your choice persists, for all repositories containing a custom instructions file
 1. In the "Options" dialog, type `custom instructions` in the search box, then click **{% data variables.product.prodname_copilot_short %}**.
 1. Select or clear the checkbox for **Enable custom instructions to be loaded from .github/copilot-instructions.md files and added to requests**.
 
+   ![Screenshot of the {% data variables.product.prodname_vs %} Options dialog showing the "Enable custom instructions" option checkbox selected.](/assets/images/help/copilot/vs-custom-instructions-option.png)
+
 {% data reusables.copilot.custom-instructions-enabling-for-ccr %}
 
 {% endvisualstudio %}

content/copilot/how-tos/configure-custom-instructions/index.md

@@ -14,4 +14,3 @@ redirect_from:
   - /copilot/how-tos/custom-instructions
 contentType: how-tos
 ---
-

content/copilot/how-tos/use-copilot-agents/request-a-code-review/configure-automatic-review.md

@@ -22,11 +22,11 @@ This article tells you how to set up {% data variables.copilot.copilot_code-revi
 
 The three sections in this article tell you how to configure automatic code review for:
 
-* [Pull requests that you create yourself](#configuring-automatic-code-review-for-all-pull-requests-you-create)
+* [Pull requests that you create yourself](#configuring-automatic-code-review-for-your-own-pull-requests)
 * [All new pull requests in a repository](#configuring-automatic-code-review-for-a-single-repository)
 * [Pull requests in multiple repositories owned by an organization](#configuring-automatic-code-review-for-repositories-in-an-organization)
 
-## Configuring automatic code review for all pull requests you create
+## Configuring automatic code review for your own pull requests
 
 > [!NOTE]
 > This is only available if you are on the {% data variables.copilot.copilot_pro_short %} or {% data variables.copilot.copilot_pro_plus_short %} plan.
@@ -45,15 +45,7 @@ The three sections in this article tell you how to configure automatic code revi
 {% data reusables.repositories.repo-rulesets-settings %}
 {% data reusables.repositories.repo-new-ruleset %}
 1. Under "Target branches," click **Add target** and choose one of the options—for example, **Include default branch** or **Include all branches**.
-1. Under "Branch rules," select the **Require a pull request before merging** checkbox.
-
-   This expands a set of subsidiary options.
-
-1. Select the **Request pull request review from {% data variables.product.prodname_copilot_short %}** checkbox.
-
-   ![Screenshot of the "Request pull request review from {% data variables.product.prodname_copilot_short %}" branch ruleset option.](/assets/images/help/copilot/code-review/automatic-code-review.png)
-
-1. At the bottom of the page, click **Create**.
+{% data reusables.copilot.auto-code-review-steps %}
 
 ## Configuring automatic code review for repositories in an organization
 
@@ -72,10 +64,4 @@ The three sections in this article tell you how to configure automatic code revi
    > [!NOTE]
    > You can add multiple targeting criteria to the same ruleset. Exclusion patterns are applied after inclusion patterns. For example, you could include any repositories matching the pattern `*cat*`, and specifically exclude a repository matching the pattern `not-a-cat`.
 
-1. Under "Target branches," click **Add target** and choose one of the target options.
-1. Under "Branch rules," select the **Require a pull request before merging** checkbox.
-
-   This expands a set of subsidiary options.
-
-1. Select the **Request pull request review from {% data variables.product.prodname_copilot_short %}** checkbox.
-1. At the bottom of the page, click **Create**.
+{% data reusables.copilot.auto-code-review-steps %}

data/reusables/copilot/auto-code-review-steps.md

@@ -0,0 +1,16 @@
+1. Under "Target branches," click **Add target** and choose one of the target options.
+1. Under "Branch rules," select **Automatically request {% data variables.copilot.copilot_code-review_short %}**.
+
+   This expands a set of subsidiary options.
+
+   ![Screenshot of the "Automatically request {% data variables.copilot.copilot_code-review_short %}" branch ruleset option.](/assets/images/help/copilot/code-review/automatic-code-review.png)
+
+1. Optionally, if you want {% data variables.product.prodname_copilot_short %} to review all new pushes to the pull request, select **Review new pushes**.
+
+   If this option is not selected, {% data variables.product.prodname_copilot_short %} will only review the pull request once.
+
+1. Optionally, if you want {% data variables.product.prodname_copilot_short %} to review pull requests while they are still drafts, select the **Review draft pull requests**.
+
+   This can be a useful option for catching errors early, before requesting a human review.
+
+1. At the bottom of the page, click **Create**.