diff --git a/.github/workflows/ready-for-doc-review.yml b/.github/workflows/ready-for-doc-review.yml index 3b46c6335de5..e21156a2e74e 100644 --- a/.github/workflows/ready-for-doc-review.yml +++ b/.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 diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md b/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md index fafd9ef8d623..36f346db0872 100644 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md +++ b/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md @@ -679,6 +679,8 @@ To show the full hook payload, result, and any exceptions for the delivery: ghe-webhook-logs -g DELIVERY_GUID ``` +{% ifversion ghes > 3.21 %} + ## Backup and restore ### ghe-backup-prune-snapshots @@ -689,8 +691,6 @@ This utility prunes old or invalid backup snapshot directories. ghe-backup-prune-snapshots ``` -{% ifversion ghes > 3.21 %} - ### ghe-backup-healthcheck This utility quickly confirms that GHES backups are being written, are recent, and that the backup disk is not in a risky state. For example, if usage is 90% or higher, it reports an error because the backup disk may be close to full. Setting `-no-color` gives plain text output, for example in logs or monitoring systems. diff --git a/content/admin/backing-up-and-restoring-your-instance/backup-service-settings-reference.md b/content/admin/backing-up-and-restoring-your-instance/backup-service-settings-reference.md index 2b71fec686ba..fb92df4237f7 100644 --- a/content/admin/backing-up-and-restoring-your-instance/backup-service-settings-reference.md +++ b/content/admin/backing-up-and-restoring-your-instance/backup-service-settings-reference.md @@ -17,8 +17,10 @@ You can configure the following options in the "Backup Service" section of the { * **Number of snapshots**: Sets how many backup snapshots to retain (default: `10`). Older snapshots are automatically pruned after each successful backup. +{% ifversion ghes > 3.21 %} > [!NOTE] > You can run the `ghe-backup-prune-snapshots` utility to prune old and invalid snapshots manually. +{% endif %} ## Restore options diff --git a/content/code-security/tutorials/remediate-leaked-secrets/evaluating-alerts.md b/content/code-security/tutorials/remediate-leaked-secrets/evaluating-alerts.md index 860eb73f1fd7..78288374afdc 100644 --- a/content/code-security/tutorials/remediate-leaked-secrets/evaluating-alerts.md +++ b/content/code-security/tutorials/remediate-leaked-secrets/evaluating-alerts.md @@ -22,7 +22,7 @@ There are some additional features that can help you to evaluate alerts in order * Check the validity of a secret, to see if the secret is still active. {% ifversion fpt or ghec %}**Applies to {% data variables.product.company_short %} tokens only**.{% endif %} See [Checking a secret's validity](#checking-a-secrets-validity).{% ifversion secret-scanning-validity-check-partner-patterns %} * Perform an "on-demand" validity check, to get the most up to date validation status. See [Performing an on-demand validity check](#performing-an-on-demand-validity-check).{% endif %} * Review a token's metadata. **Applies to {% data variables.product.company_short %} tokens only**. For example, to see when the token was last used. See [Reviewing {% data variables.product.company_short %} token metadata](#reviewing-github-token-metadata).{% ifversion secret-scanning-extended-metadata-checks %} -* Review extended metadata checks for an exposed secret, to see details such as who owns the secret and how to contact the secret owner. **Applies to OpenAI API, Google OAuth, and Slack tokens only**. See [Reviewing extended metadata for a token](#reviewing-extended-metadata-for-a-token).{% endif %}{% ifversion secret-scanning-multi-repo-public-leak %} +* Review extended metadata checks for an exposed secret, to see details such as who owns the secret and how to contact the secret owner. **Applies to OpenAI API, Google OAuth, Slack, and Replicate tokens only**. See [Reviewing extended metadata for a token](#reviewing-extended-metadata-for-a-token).{% endif %}{% ifversion secret-scanning-multi-repo-public-leak %} * Review the labels assigned to the alert. For more information, see [Reviewing alert labels](#reviewing-alert-labels).{% endif %} ## Checking a secret's validity @@ -95,7 +95,7 @@ Tokens, like {% data variables.product.pat_generic %} and other credentials, are In the view for an active {% data variables.product.company_short %} token alert, you can see extended metadata information, such as owner and contact details. -The following table shows **all the available metadata**. Note that metadata checks are currently limited to OpenAI API, Google OAuth, and Slack tokens, and the metadata shown for each token may represent only a subset of what exists. +The following table shows **all the available metadata**. Note that metadata checks are currently limited to OpenAI API, Google OAuth, Slack, and Replicate tokens, and the metadata shown for each token may represent only a subset of what exists. | Metadata type | Description | | ------------------ | --------------------------------------------------------------------------------------------------- | diff --git a/content/copilot/concepts/agents/code-review.md b/content/copilot/concepts/agents/code-review.md index 2cc3063f8849..f37a0f9c5e09 100644 --- a/content/copilot/concepts/agents/code-review.md +++ b/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). diff --git a/content/copilot/concepts/agents/github-copilot-app.md b/content/copilot/concepts/agents/github-copilot-app.md index 0259388d2469..b7f0886e851d 100644 --- a/content/copilot/concepts/agents/github-copilot-app.md +++ b/content/copilot/concepts/agents/github-copilot-app.md @@ -2,7 +2,7 @@ title: About the GitHub Copilot app shortTitle: GitHub Copilot app intro: 'The {% data variables.copilot.github_copilot_app %} is a desktop application for agent-driven development that brings parallel workstreams, {% data variables.product.github %} integration, and PR lifecycle management into one place.' -product: '{% data reusables.gated-features.github-app %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' +product: '{% data reusables.gated-features.github-app %}
Download {% data variables.copilot.github_copilot_app %} {% octicon "link-external" height:16 %}' versions: feature: copilot contentType: concepts @@ -12,8 +12,6 @@ category: - Learn about Copilot --- -Install the app from the [download page for {% data variables.copilot.github_copilot_app %}](https://gh.io/app?ref_product=copilot&ref_type=engagement&ref_style=text&utm_source=docs-about-app-download&utm_medium=docs&utm_campaign=github-copilot-app-ga-2026). - ## Introduction The {% data variables.copilot.github_copilot_app %} is a desktop application purpose-built for agent-driven development. It gives you a single place to direct AI agents across parallel workstreams, work with {% data variables.product.github %} issues and pull requests, and manage the full development lifecycle—without context-switching between terminals, IDEs, and browser tabs. diff --git a/content/copilot/how-tos/copilot-on-github/use-copilot-agents/overview.md b/content/copilot/how-tos/copilot-on-github/use-copilot-agents/overview.md index 08ce20ac8723..945ae16c17e1 100644 --- a/content/copilot/how-tos/copilot-on-github/use-copilot-agents/overview.md +++ b/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 Enter. @@ -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. diff --git a/content/copilot/how-tos/github-copilot-app/agent-sessions.md b/content/copilot/how-tos/github-copilot-app/agent-sessions.md index 46d0a9a4c888..61a4bf55c60d 100644 --- a/content/copilot/how-tos/github-copilot-app/agent-sessions.md +++ b/content/copilot/how-tos/github-copilot-app/agent-sessions.md @@ -3,7 +3,7 @@ title: Working with agent sessions in the GitHub Copilot app shortTitle: Agent sessions intro: 'Run multiple isolated agent sessions simultaneously, each with its own branch, and steer them using different session modes, models, and tools.' allowTitleToDifferFromFilename: true -product: '{% data reusables.gated-features.github-app %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' +product: '{% data reusables.gated-features.github-app %}
Download {% data variables.copilot.github_copilot_app %} {% octicon "link-external" height:16 %}' versions: feature: copilot contentType: how-tos diff --git a/content/copilot/how-tos/github-copilot-app/customize-github-copilot-app.md b/content/copilot/how-tos/github-copilot-app/customize-github-copilot-app.md index 6e103d878661..a993efb5eaa8 100644 --- a/content/copilot/how-tos/github-copilot-app/customize-github-copilot-app.md +++ b/content/copilot/how-tos/github-copilot-app/customize-github-copilot-app.md @@ -3,7 +3,7 @@ title: Customizing the GitHub Copilot app shortTitle: Customize the GitHub Copilot app intro: 'Customize the {% data variables.copilot.github_copilot_app %} so it works the way you and your team do.' allowTitleToDifferFromFilename: true -product: '{% data reusables.gated-features.github-app %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' +product: '{% data reusables.gated-features.github-app %}
Download {% data variables.copilot.github_copilot_app %} {% octicon "link-external" height:16 %}' versions: feature: copilot contentType: how-tos diff --git a/content/copilot/how-tos/github-copilot-app/getting-started.md b/content/copilot/how-tos/github-copilot-app/getting-started.md index c419a2068bed..e186f1fdff93 100644 --- a/content/copilot/how-tos/github-copilot-app/getting-started.md +++ b/content/copilot/how-tos/github-copilot-app/getting-started.md @@ -3,7 +3,7 @@ title: Getting started with the GitHub Copilot app shortTitle: Quickstart allowTitleToDifferFromFilename: true intro: 'Sign in to the {% data variables.copilot.github_copilot_app %}, ask your first question in a quick chat, and then create a full agent session to make changes to your code.' -product: '{% data reusables.gated-features.github-app %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' +product: '{% data reusables.gated-features.github-app %}
Download {% data variables.copilot.github_copilot_app %} {% octicon "link-external" height:16 %}' versions: feature: copilot contentType: how-tos @@ -25,7 +25,7 @@ For a conceptual overview of the {% data variables.copilot.github_copilot_app %} ## Installing the {% data variables.copilot.github_copilot_app %} -1. Visit the [download page for {% data variables.copilot.github_copilot_app %}](https://gh.io/app?ref_product=copilot&ref_type=engagement&ref_style=text&utm_source=docs-getting-started-download&utm_medium=docs&utm_campaign=github-copilot-app-ga-2026). +1. Visit the [download page for {% data variables.copilot.github_copilot_app %}](https://github.com/features/ai/github-app). 1. Download the app for your platform. ## Opening the {% data variables.copilot.github_copilot_app %} for the first time diff --git a/content/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests.md b/content/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests.md index 3573098097d1..cfa307a90649 100644 --- a/content/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests.md +++ b/content/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests.md @@ -3,7 +3,7 @@ title: Managing issues and pull requests with the GitHub Copilot app shortTitle: Managing issues and pull requests allowTitleToDifferFromFilename: true intro: 'Pick up an issue, direct an agent to implement changes, and land a pull request—all without leaving the {% data variables.copilot.github_copilot_app %}.' -product: '{% data reusables.gated-features.github-app %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' +product: '{% data reusables.gated-features.github-app %}
Download {% data variables.copilot.github_copilot_app %} {% octicon "link-external" height:16 %}' versions: feature: copilot contentType: how-tos diff --git a/content/copilot/how-tos/github-copilot-app/open-with-deep-links.md b/content/copilot/how-tos/github-copilot-app/open-with-deep-links.md index 75ccb24ac35f..62abb105b496 100644 --- a/content/copilot/how-tos/github-copilot-app/open-with-deep-links.md +++ b/content/copilot/how-tos/github-copilot-app/open-with-deep-links.md @@ -3,7 +3,7 @@ title: Using deep links to open the GitHub Copilot app shortTitle: Open with deep links allowTitleToDifferFromFilename: true intro: "Use deep links to launch the {% data variables.copilot.github_copilot_app %} from the terminal, tickets, and internal tools, so people can jump directly into the right repository, pull request, automation, or session." -product: '{% data reusables.gated-features.github-app %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' +product: '{% data reusables.gated-features.github-app %}
Download {% data variables.copilot.github_copilot_app %} {% octicon "link-external" height:16 %}' versions: feature: copilot contentType: how-tos diff --git a/content/copilot/how-tos/github-copilot-app/use-byok-models.md b/content/copilot/how-tos/github-copilot-app/use-byok-models.md index 431e7bd36cce..264be63c1fdd 100644 --- a/content/copilot/how-tos/github-copilot-app/use-byok-models.md +++ b/content/copilot/how-tos/github-copilot-app/use-byok-models.md @@ -3,7 +3,7 @@ title: Using your own LLM models in the GitHub Copilot app shortTitle: Use your own model provider intro: 'Connect a model from an external provider of your choice by supplying your own API key, then use the model in agent sessions.' allowTitleToDifferFromFilename: true -product: '{% data reusables.gated-features.github-app %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' +product: '{% data reusables.gated-features.github-app %}
Download {% data variables.copilot.github_copilot_app %} {% octicon "link-external" height:16 %}' versions: feature: copilot contentType: how-tos diff --git a/content/copilot/how-tos/github-copilot-app/using-automations.md b/content/copilot/how-tos/github-copilot-app/using-automations.md index f126993f0344..12a38ac10453 100644 --- a/content/copilot/how-tos/github-copilot-app/using-automations.md +++ b/content/copilot/how-tos/github-copilot-app/using-automations.md @@ -3,7 +3,7 @@ title: Using automations in the GitHub Copilot app shortTitle: Automations intro: 'Automate recurring agent tasks so they run on a schedule or on demand, without manual intervention.' allowTitleToDifferFromFilename: true -product: '{% data reusables.gated-features.github-app %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' +product: '{% data reusables.gated-features.github-app %}
Download {% data variables.copilot.github_copilot_app %} {% octicon "link-external" height:16 %}' versions: feature: copilot contentType: how-tos diff --git a/content/copilot/how-tos/github-copilot-app/working-with-canvas-extensions.md b/content/copilot/how-tos/github-copilot-app/working-with-canvas-extensions.md index 2022894b1095..d47773367cf6 100644 --- a/content/copilot/how-tos/github-copilot-app/working-with-canvas-extensions.md +++ b/content/copilot/how-tos/github-copilot-app/working-with-canvas-extensions.md @@ -3,7 +3,7 @@ title: Working with canvas extensions in the GitHub Copilot app shortTitle: Canvas extensions intro: 'Use canvases in the {% data variables.copilot.github_copilot_app %} to build shared, agent-driven artifacts and interfaces for human-agent collaboration.' allowTitleToDifferFromFilename: true -product: '{% data reusables.gated-features.github-app %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' +product: '{% data reusables.gated-features.github-app %}
Download {% data variables.copilot.github_copilot_app %} {% octicon "link-external" height:16 %}' versions: feature: copilot contentType: how-tos diff --git a/content/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review.md b/content/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review.md index 6b7e3ec50fbf..59598339764f 100644 --- a/content/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review.md +++ b/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). diff --git a/content/copilot/reference/custom-instructions-support.md b/content/copilot/reference/custom-instructions-support.md index 33a2d9896054..0bb28e017b7f 100644 --- a/content/copilot/reference/custom-instructions-support.md +++ b/content/copilot/reference/custom-instructions-support.md @@ -52,6 +52,7 @@ WRITING NOTE: The following tables have been written using HTML rather than Mark diff --git a/content/copilot/tutorials/customize-code-review.md b/content/copilot/tutorials/customize-code-review.md index d08cf0da7399..bf7cfb761c16 100644 --- a/content/copilot/tutorials/customize-code-review.md +++ b/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 diff --git a/content/copilot/tutorials/index.md b/content/copilot/tutorials/index.md index 668bcfbc4d03..82591f16d340 100644 --- a/content/copilot/tutorials/index.md +++ b/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 diff --git a/content/copilot/tutorials/use-copilot-code-review-across-the-pull-request-lifecycle.md b/content/copilot/tutorials/use-copilot-code-review-across-the-pull-request-lifecycle.md new file mode 100644 index 000000000000..be06455d09c7 --- /dev/null +++ b/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). diff --git a/data/reusables/copilot/byok-no-subscription-required.md b/data/reusables/copilot/byok-no-subscription-required.md deleted file mode 100644 index debc57271583..000000000000 --- a/data/reusables/copilot/byok-no-subscription-required.md +++ /dev/null @@ -1 +0,0 @@ -Using your own API keys does not require a {% data variables.product.prodname_copilot_short %} subscription. However, without a subscription, you won't have access to other {% data variables.product.prodname_copilot_short %} capabilities such as mobile access, automation, and remote server features. diff --git a/data/reusables/copilot/code-review/custom-instructions-information.md b/data/reusables/copilot/code-review/custom-instructions-information.md index 3a4575c6ccc4..8bc5a541e511 100644 --- a/data/reusables/copilot/code-review/custom-instructions-information.md +++ b/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). diff --git a/data/reusables/copilot/gpt-55-promo-period.md b/data/reusables/copilot/gpt-55-promo-period.md deleted file mode 100644 index a5d0647e207c..000000000000 --- a/data/reusables/copilot/gpt-55-promo-period.md +++ /dev/null @@ -1 +0,0 @@ -> [!IMPORTANT] {% data variables.copilot.copilot_gpt_55 %} is available at a promotional multiplier of 7.5x. diff --git a/src/article-api/tests/pageinfo.ts b/src/article-api/tests/pageinfo.ts index 461da304936b..f17804619633 100644 --- a/src/article-api/tests/pageinfo.ts +++ b/src/article-api/tests/pageinfo.ts @@ -58,6 +58,19 @@ describe('pageinfo api', () => { expect(res.headers['surrogate-key']).toBe(makeLanguageSurrogateKey('en')) }) + test('corrupted translation frontmatter falls back to English title', async () => { + // The Japanese counterpart of this page has frontmatter whose ASCII `:` + // key/value separators were replaced with fullwidth colons (`：`), so the + // YAML parses to a scalar string rather than an object. When that happens + // none of the frontmatter keys exist. Without the non-object fallback in + // page-data, `meta.title` comes back empty and the search scraper rejects + // the record with "Record has empty title". It must fall back to English. + const res = await get(makeURL('/ja/get-started/foo/broken-frontmatter-translation')) + expect(res.statusCode).toBe(200) + const meta = JSON.parse(res.body) as PageMetadata + expect(meta.title).toBe('Broken frontmatter translation fallback') + }) + test('a pathname that does not exist', async () => { const res = await get(makeURL('/en/never/heard/of')) expect(res.statusCode).toBe(404) diff --git a/src/fixtures/fixtures/content/get-started/foo/broken-frontmatter-translation.md b/src/fixtures/fixtures/content/get-started/foo/broken-frontmatter-translation.md new file mode 100644 index 000000000000..8543c7489d09 --- /dev/null +++ b/src/fixtures/fixtures/content/get-started/foo/broken-frontmatter-translation.md @@ -0,0 +1,14 @@ +--- +title: Broken frontmatter translation fallback +intro: Demonstrates falling back to English when a translation's frontmatter is corrupted. +versions: + fpt: "*" + ghes: "*" + ghec: "*" +--- + +## Intro + +This page exists to test that a translated file whose frontmatter is corrupted +into a non-object (for example, fullwidth colons replacing the ASCII `:` +separators) falls back to the English title instead of rendering an empty title. diff --git a/src/fixtures/fixtures/content/get-started/foo/index.md b/src/fixtures/fixtures/content/get-started/foo/index.md index 774984fc4731..198a9293a549 100644 --- a/src/fixtures/fixtures/content/get-started/foo/index.md +++ b/src/fixtures/fixtures/content/get-started/foo/index.md @@ -1,11 +1,11 @@ --- title: Fooing Around shortTitle: Foo -intro: 'The most basic of fixture data for {% data variables.product.product_name %}' +intro: "The most basic of fixture data for {% data variables.product.product_name %}" versions: - fpt: '*' - ghes: '*' - ghec: '*' + fpt: "*" + ghes: "*" + ghec: "*" children: - /bar - /autotitling @@ -19,4 +19,5 @@ children: - /table-with-ifversions - /code-snippet-with-hashbang - /journey-test-article + - /broken-frontmatter-translation --- diff --git a/src/fixtures/fixtures/translations/ja-jp/content/get-started/foo/broken-frontmatter-translation.md b/src/fixtures/fixtures/translations/ja-jp/content/get-started/foo/broken-frontmatter-translation.md new file mode 100644 index 000000000000..9c79f06b9184 --- /dev/null +++ b/src/fixtures/fixtures/translations/ja-jp/content/get-started/foo/broken-frontmatter-translation.md @@ -0,0 +1,9 @@ +--- +title： 壊れたフロントマターのフォールバック shortTitle： フォールバック intro： 翻訳のフロントマターが壊れているときに英語にフォールバックすることを示します。 +versions： fpt： '*' ghes： '*' ghec： '*' +--- + +## Intro + +このページは、翻訳ファイルのフロントマターが非オブジェクトに壊れている場合に、 +空のタイトルではなく英語のタイトルにフォールバックすることをテストするために存在します。 diff --git a/src/frame/lib/page-data.ts b/src/frame/lib/page-data.ts index dbc435a2f31a..4d23884281c5 100644 --- a/src/frame/lib/page-data.ts +++ b/src/frame/lib/page-data.ts @@ -164,7 +164,7 @@ async function translateTree( content = read.content data = read.data as Record - if (!data) { + if (!data || typeof data !== 'object' || Array.isArray(data)) { // If the file's frontmatter Yaml is entirely broken, // the result of `readFileContents()` is that you just // get a `errors` key. E.g. @@ -177,6 +177,15 @@ async function translateTree( // } // ] // + // A translated file can also be corrupted so that the frontmatter + // parses to a non-object. For example, if machine translation replaces + // the ASCII `:` key/value separators with fullwidth colons (`：`), YAML + // parses the whole block as a single scalar string. `data` is then a + // string rather than an object, so none of the frontmatter keys (like + // `title`) exist and the per-key English fallback below never fires, + // leaving the page with an empty title. Treat that the same as entirely + // broken frontmatter and fall back to English. + // // If this the case throw error so we can lump this error with // how we deal with the file not even being present on disk. throw new FrontmatterParsingError(JSON.stringify(read.errors), true)