Merge pull request #45154 from github/repo-sync

Repo sync

Author: docs-bot

.github/workflows/ready-for-doc-review.yml

@@ -29,7 +29,7 @@ jobs:
           owner: github
           # Scope must include every repo that calls this reusable workflow, because
           # the script resolves the PR node (ITEM_NODE_ID) in the calling repo.
-          repositories: docs-internal,docs-content,docs-strategy,docs-early-access,github
+          repositories: docs-internal,docs-content,docs-strategy,docs-early-access,docs-team,github
 
       - name: Check out repo content
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

content/copilot/concepts/agents/code-review.md

@@ -186,6 +186,21 @@ The more {% data variables.product.prodname_copilot_short %} knows about the cod
 
 These are short, natural-language statements that you write and store as one or more files in a repository. If you are the owner of an organization on {% data variables.product.github %}, you can also define custom instructions in the settings for your organization. For more information, see [AUTOTITLE](/copilot/concepts/prompting/response-customization?tool=webui#about-repository-custom-instructions).
 
+### Choosing between custom instructions, AGENTS.md, and skills
+
+{% data variables.copilot.copilot_code-review_short %} can draw on several sources of customization, and each serves a different purpose. Use `.github/copilot-instructions.md` for repository-wide rules specific to {% data variables.product.prodname_copilot_short %}, use path-specific `*.instructions.md` files under `.github/instructions/` for rules that apply only to certain files or directories, use `AGENTS.md` for standing rules you want to share across AI tools and agents, and use skills for task-specific workflows that {% data variables.product.prodname_copilot_short %} runs on demand. The following table summarizes when to use each and how to provide rules.
+
+| Use | `copilot-instructions.md` | Path-specific `*.instructions.md` | `AGENTS.md` | Skills |
+| --- | --- | --- | --- | --- |
+| Best for | Repository-wide, always-on rules for {% data variables.product.prodname_copilot_short %} | Always-on rules for specific paths, file types, or directories | Always-on rules shared across AI agents | Task-specific review workflows |
+| Stored in | `.github/copilot-instructions.md` | `.github/instructions/**/*.instructions.md` | Repository root (`AGENTS.md`) | `.github/skills/...` |
+| Examples | Coding standards, architecture defaults, test expectations | `content/**` writing rules, `src/**` coding conventions, language-specific guidance | Shared repository conventions that should apply beyond {% data variables.product.prodname_copilot_short %} | Reviews, releases, migrations, analysis |
+| Activation | Automatic | Automatic when the changed files match the instruction scope | Automatic (read from repository root) | Automatic when relevant (e.g. review-focused skills such as `code-review`), or on demand |
+| Scope | Repository-wide and {% data variables.product.prodname_copilot_short %}-specific | Repository sub-paths and {% data variables.product.prodname_copilot_short %}-specific | Cross-tool / agent-agnostic | Invoked per task |
+| Rule | "{% data variables.product.prodname_copilot_short %}, always know this for this repository" | "{% data variables.product.prodname_copilot_short %}, always know this when working in these paths" | "Any agent, always know this" | "Do this when needed" |
+
+For more information, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills) and [AUTOTITLE](/copilot/how-tos/configure-custom-instructions/add-repository-instructions).
+
 ### {% data variables.copilot.copilot_memory %} ({% data variables.release-phases.public_preview %})
 
 If you have a {% data variables.copilot.copilot_pro_short %}, {% data variables.copilot.copilot_pro_plus_short %}, or {% data variables.copilot.copilot_max_short %} plan, you can enable {% data variables.copilot.copilot_memory %}. This allows {% data variables.product.prodname_copilot_short %} to store useful details it has learned about a repository. {% data variables.product.prodname_copilot_short %} can then use this information when it reviews pull requests in that repository. For more information, see [AUTOTITLE](/copilot/concepts/agents/copilot-memory).

content/copilot/how-tos/copilot-on-github/use-copilot-agents/overview.md

@@ -30,8 +30,8 @@ Pick a repository where {% data variables.copilot.copilot_cloud_agent %} is enab
 While {% data variables.product.prodname_copilot_short %} works on the issue, start a second, non-coding task to see two sessions running in parallel.
 
 1. In the same repository, click the **{% octicon "agent" aria-hidden="true" aria-label="agent" %} Agents** tab.
-1. Type a research prompt. 
-    
+1. Type a research prompt.
+
     For example: `Investigate which dependencies in this repo are outdated and summarize what upgrading would involve.`
 1. Click **{% octicon "paper-airplane" aria-label="Start task" %}** or press <kbd>Enter</kbd>.
 
@@ -52,7 +52,7 @@ For more details on monitoring, steering, and stopping sessions, see [AUTOTITLE]
 When the coding task finishes, {% data variables.product.prodname_copilot_short %} opens a pull request and adds you as a reviewer.
 
 1. Open the pull request from the notification or from the session log.
-1. In the right sidebar, click **Reviewers**, then select **{% data variables.product.prodname_copilot_short %}**.
+1. Under "Reviewers" in the right sidebar, next to **{% data variables.product.prodname_copilot_short %}**, click **Request**.
 1. Wait for {% data variables.copilot.copilot_code-review_short %} to leave comments—usually under 30 seconds.
 
 Read through the review comments. {% data variables.product.prodname_copilot_short %} may suggest changes you can apply directly with a click.

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

@@ -24,6 +24,8 @@ category:
 
 For a full introduction to {% data variables.copilot.copilot_code-review %}, see [AUTOTITLE](/copilot/concepts/agents/code-review).
 
+{% data variables.copilot.copilot_code-review_short %} uses {% data variables.product.prodname_actions %} to run agentic capabilities. For more information, see [Agentic capabilities for {% data variables.copilot.copilot_code-review_short %}](/copilot/concepts/agents/code-review#usage-of-github-actions-runners-for-agentic-capabilities-in-code-review).
+
 {% webui %}
 
 {% data variables.copilot.copilot_code-review_short %} is also available for organization members without a {% data variables.product.prodname_copilot_short %} license, when enabled by an enterprise administrator or organization owner. See [{% data variables.copilot.copilot_code-review_short %} for organization members without a {% data variables.product.prodname_copilot_short %} license](/copilot/concepts/agents/code-review#copilot-code-review-for-organization-members-without-a-copilot-license).

content/copilot/reference/custom-instructions-support.md

@@ -52,6 +52,7 @@ WRITING NOTE: The following tables have been written using HTML rather than Mark
         <ul style="list-style: none; padding-left: 1.5em; margin-left: 0;">
           {% data reusables.copilot.ci-support-repository %}
           {% data reusables.copilot.ci-support-path %}
+          {% data reusables.copilot.ci-support-agents-only %}
           {% data reusables.copilot.ci-support-organization %}
         </ul>
       </td>

content/copilot/tutorials/customize-code-review.md

@@ -109,10 +109,11 @@ const activeUsers = users.filter(user => user.isActive);
 
 ## Organizing instructions across files
 
-{% data variables.copilot.copilot_code-review_short %} supports two types of instruction files:
+{% data variables.copilot.copilot_code-review_short %} supports several types of instruction files:
 
 1. **`copilot-instructions.md`**: Repository-wide instructions that apply to all files.
 1. **`*.instructions.md`**: Path-specific instructions that apply to certain files or directories.
+1. **`AGENTS.md`**: Repository-level agent-specific instructions.
 
 Use path-specific instructions to keep {% data variables.product.prodname_copilot_short %} focused and prevent it from applying language-specific rules to the wrong files.
 
@@ -229,11 +230,37 @@ applyTo: "src/components/**/*.{tsx,jsx}"
 - Ensure color contrast meets WCAG AA standards
 ````
 
+### When to use agent-specific instructions
+
+Use `AGENTS.md` for instructions that apply to specific {% data variables.copilot.custom_agents_short %} in your repository. This allows you to tailor the behavior of different agents for different tasks, including shaping {% data variables.copilot.copilot_code-review_short %} feedback to better reflect your repository's conventions and expectations.
+
+**Example: Agent-specific instructions**
+
+Create a file called `AGENTS.md` at the root of your repository:
+
+````markdown copy
+# AGENTS.md
+
+## Code Review
+
+Your primary goal is to validate that incoming code changes are secure, performant, and match this repository's engineering standards.
+
+### Code Style & Anti-Patterns
+
+Enforce these strict patterns for code inspection:
+
+- **Asynchronous Code:** Prefer `async/await` syntax over explicit `.then()` chains.
+- **Error Handling:** Every API call must be wrapped in a structured `try/catch` block.
+- **State Management:** React components must keep local UI state completely isolated from global stores.
+````
+
 ### Breaking up complex instruction sets
 
 For large repositories with many concerns, break instructions into multiple focused files:
 
 ```text
+AGENTS.md                          # Agent-specific
+
 .github/
   copilot-instructions.md          # General standards
 

content/copilot/tutorials/index.md

@@ -11,6 +11,7 @@ children:
   - /budgets
   - /spark
   - /customize-code-review
+  - /use-copilot-code-review-across-the-pull-request-lifecycle
   - /enhance-agent-mode-with-mcp
   - /compare-ai-models
   - /speed-up-development-work

content/copilot/tutorials/use-copilot-code-review-across-the-pull-request-lifecycle.md

@@ -0,0 +1,124 @@
+---
+title: Use GitHub Copilot code review across the pull request lifecycle
+shortTitle: Pull request lifecycle
+allowTitleToDifferFromFilename: true
+intro: Build a repeatable workflow for {% data variables.copilot.copilot_code-review_short %} from draft pull request to merge.
+versions:
+  feature: copilot
+contentType: tutorials
+category:
+  - Accelerate PR velocity
+  - Team collaboration
+  - Author and optimize with Copilot
+---
+
+## Introduction
+
+{% data variables.copilot.copilot_code-review_short %} is most effective when you use it as part of a pull request workflow. This tutorial shows how to choose between manual and automatic reviews, request reviews early on draft pull requests, and decide when to trigger re-review before merge.
+
+You will also learn when to use customization, skills, MCP servers, and runner options to tailor {% data variables.product.prodname_copilot_short %}'s reviews to your needs.
+
+## Work through the pull request lifecycle
+
+Choose a review model and set up early feedback for draft and active pull requests.
+
+### Choose the right review model for your team
+
+{% data variables.copilot.copilot_code-review_short %} can run manually, when you trigger it yourself, or automatically, at one or more points in a pull request's lifecycle. Manual reviews give you control over exactly when {% data variables.copilot.copilot_code-review_short %} weighs in. Automatic reviews ensure consistent coverage, and you can choose whether they trigger on open, on draft, or on every new push.
+
+| Review model | Best for | Why |
+| --- | --- | --- |
+| Manual review request | High-context changes or selective use | You can trigger {% data variables.product.prodname_copilot_short %} only when you want another perspective. |
+| Automatic review on open pull requests | Teams that want broad, consistent coverage | Every pull request gets baseline feedback without relying on individual habits. |
+| Automatic review on draft pull requests | Teams that want earlier feedback loops | Authors can fix issues before human review starts. |
+| Automatic review on new pushes | Fast-moving pull requests with multiple revisions | {% data variables.product.prodname_copilot_short %} reevaluates substantial updates as the pull request evolves. |
+
+For setup steps, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review) and [AUTOTITLE](/copilot/how-tos/copilot-on-github/set-up-copilot/configure-automatic-review).
+
+### Use {% data variables.copilot.copilot_code-review_short %} early on draft pull requests
+
+Reviewing draft pull requests with {% data variables.copilot.copilot_code-review_short %} gives you an early, dependable check on your code before you request a review from your team.
+
+A useful draft workflow is:
+
+1. Open a pull request as draft.
+1. Request a review from {% data variables.copilot.copilot_code-review_short %} under **Reviewers**, or enable automatic review for draft pull requests.
+1. Address high-confidence feedback first, such as correctness, security, and clear maintainability issues.
+1. Push updates and confirm that major comments have been resolved.
+1. Mark the pull request as ready for human review.
+
+This approach helps your team spend more human review time on design tradeoffs and product impact, instead of obvious issues that could have been caught earlier.
+
+## Tune review quality
+
+Improve review quality by deciding when to request re-review and where customization, external context, and runners add value.
+
+### Use re-review before merge
+
+After substantial changes, request re-review to check whether new risks were introduced while addressing earlier feedback.
+
+Request re-review when you:
+
+* Update multiple files across service or package boundaries.
+* Change security-sensitive or data-sensitive behavior.
+* Apply a large batch of suggested changes and want a final pass.
+
+For teams with frequent updates to active pull requests, enabling automatic reviews on new pushes can reduce manual re-review requests while keeping feedback current.
+
+### Match customization to your workflow
+
+Customization is most useful when each file type supports a review decision point in your workflow:
+
+* Use `.github/copilot-instructions.md` for repository-wide review expectations that should apply to most pull requests.
+* Use `.github/instructions/**/*.instructions.md` for agent-specific and path-specific guidance when different parts of the codebase have different standards.
+* Use `AGENTS.md` to provide repository context that improves relevance, such as intentional patterns, architecture boundaries, or review priorities.
+
+Keep these files focused on what reviewers need to decide during pull requests. Avoid turning them into full engineering handbooks.
+
+For detailed customization mechanics and examples, see [AUTOTITLE](/copilot/tutorials/customize-code-review).
+
+### Use agent skills and MCP servers for specialized review goals
+
+Agent skills and MCP servers are most valuable when your team needs reviews that depend on organization-specific context.
+
+Use agent skills when you want reusable review routines, for example:
+
+* Applying a standard checklist to migration pull requests.
+* Running language- or framework-specific review passes in a monorepo.
+* Prioritizing certain risk areas, such as authorization or billing logic.
+
+Use MCP servers when reviews should reference context outside the pull request itself, for example:
+
+* Linking pull request changes to issue, incident, or service ownership data.
+* Checking expected rollout or operational context from internal systems.
+* Validating implementation details against external documentation sources.
+
+For setup details, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills) and [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers).
+
+### Decide whether you need self-hosted runners
+
+In many cases, standard {% data variables.product.prodname_dotcom %}-hosted runners are sufficient for {% data variables.copilot.copilot_code-review_short %} and require no setup; they are configured for you by default.
+
+Consider self-hosted or larger runners when you need:
+
+* Better performance for heavier review workloads.
+* Network access to internal systems required by your organization.
+
+Runners are required because {% data variables.copilot.copilot_code-review_short %} uses {% data variables.product.prodname_actions %} for agentic operations, such as deeper context gathering and tool-calling. If {% data variables.product.prodname_dotcom %}-hosted runners are unavailable and no supported self-hosted option is configured correctly, reviews will fall back to a more limited mode.
+
+For planning and setup details, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/set-up-copilot/configure-runners).
+
+## Recommended workflows by scenario
+
+| Team scenario | Recommended workflow |
+| --- | --- |
+| Small team with frequent pull requests | Enable automatic reviews for all pull requests, review drafts for early feedback, and use manual re-review before merge when changes are substantial. |
+| Large monorepo with mixed stacks | Enable automatic reviews and review new pushes, add path-specific instructions for each major area, and use skills for repeated review patterns. |
+| Security-sensitive or regulated codebase | Use draft pull request reviews plus required re-review before merge, keep repository-wide security expectations in `.github/copilot-instructions.md`, and use MCP servers for incident or compliance context stored outside of GitHub. |
+| Team with internal platform dependencies | Start with automatic review, then add self-hosted runners and MCP context only when internal-system access is required for useful review feedback. |
+
+## Next steps
+
+* For broader concepts, including review effort and agentic capabilities, see [AUTOTITLE](/copilot/concepts/agents/code-review).
+* To tune automated review quality for specific repositories, see [AUTOTITLE](/copilot/tutorials/optimize-code-reviews).
+* For excluded file types and other limits, see [AUTOTITLE](/copilot/reference/review-excluded-files).

data/reusables/copilot/code-review/custom-instructions-information.md

@@ -1,8 +1,10 @@
-You can customize {% data variables.copilot.copilot_code-review_short %} by adding custom instructions to your repository.
+You can customize {% data variables.copilot.copilot_code-review_short %} by adding custom instructions to your repository. Repository custom instructions can either be repository wide or path specific.
 
-Repository custom instructions can either be repository wide or path specific. You specify repository-wide custom instructions in a `.github/copilot-instructions.md` file in your repository. You can use this file to store information that you want {% data variables.product.prodname_copilot_short %} to consider when reviewing code anywhere in the repository.
+Use `.github/copilot-instructions.md` for repository-wide review guidance that should apply across the entire codebase. This is a good place to describe organization-wide expectations, such as coding standards, review criteria, or general practices that {% data variables.product.prodname_copilot_short %} should consider in every review.
 
-You can also write instructions that {% data variables.product.prodname_copilot_short %} will only use when reviewing code in files that match a specified path. You write these instructions in one or more `.github/instructions/**/*.instructions.md` files.
+Use an `AGENTS.md` file in the root of your repository to provide additional repository context that helps {% data variables.product.prodname_copilot_short %} better understand how your project works. For example, you can explain which patterns are intentional, which parts of the codebase need closer scrutiny, and what your team considers good architecture, testing, and implementation practices. This helps make reviews more relevant and aligned with the way your team builds software.
+
+Use `.github/instructions/**/*.instructions.md` files for path-specific instructions that only apply when reviewing matching files. This is useful when different parts of the repository follow different conventions, require specialized checks, or need review guidance tailored to a particular language, framework, or subsystem.
 
 For more information, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions).