# 向组织推出堆积拉取请求

计划和推出堆积拉取请求给组织，以便团队可以将大型更改作为小型可查看层交付，而不会影响现有规则和检查。

> \[!NOTE]
> 堆积拉取请求处于 公开预览 其中且可能会更改。

堆叠拉取请求可让开发人员将大型更改分解成一系列小型、集中的拉取请求，这些请求相互构建，使每一层更易于查看、合并和交付。 堆积拉取请求使开发人员能够灵活地完成一项工作，并直接移动到下一个工作，而无需等待评审到达。 当工作自然取决于它之前的情况，当团队在处理大型发布和最后一次更改时，这一点很重要。

本教程将指导你为堆积拉取请求准备组织：查看推出注意事项、了解分支保护规则和 CI 如何处理堆栈以及开始团队。 若要基本了解堆积拉取请求，请参阅 [关于堆积拉取请求](/zh/pull-requests/get-started/about-stacked-prs)。

## Prerequisites

如果团队已在使用拉取请求，则会设置为使用堆积拉取请求。 本教程中的其他所有内容都是可选的，但假设你的组织具有以下功能：

* GitHub CLI，安装 `gh-stack` 扩展。 CLI 扩展是创建和管理堆栈的最全面方法。
* 为默认分支配置的分支保护规则。
* GitHub Actions 针对默认分支的拉取请求运行的工作流。

Copilot 不需要使用堆叠拉取请求，但对于想要堆叠 AI 生成的更改的团队，建议使用此方法。 堆叠拉取请求还使用提供代理技能处理其他 AI 编码代理，例如 Claude Code 和 Codex。 请参阅“[拉取请求中堆栈 AI 生成的代码](/zh/copilot/tutorials/stack-ai-generated-code-in-pull-requests)”。

## 1. 查看推出注意事项

在向团队引入堆积拉取请求之前，请查看以下注意事项，以便每个人都知道预期内容。

### 堆栈必须是线性的，不能包含分叉

堆栈中的每个拉取请求都必须是同一存储库的一部分，并且构建在单个线性分支链上。 不支持具有分支结构的堆栈或从分支拉取请求。 如果团队依赖于分叉进行贡献，请计划暂时将这些贡献保留在堆栈之外。

### 重新排序堆栈需要 GitHub CLI

如果你的团队需要在堆栈中重新排序拉取请求，则需要在扩展中使用`gh stack modify``gh stack`GitHub CLI。 无法从 GitHub 网站重新排序堆栈。 在本地不使用 CLI 的团队应仔细规划其堆栈顺序，或为此任务安装扩展。

### 无法扩展已完成的堆栈

堆栈中的每个拉取请求合并后，该堆栈就会关闭。 如果团队在顶部添加新分支并运行 `gh stack submit`，CLI 会启动具有相同基分支的新堆栈。 想要继续处理堆栈的团队应计划让堆栈保持打开状态，直到完成所有工作。

## 2. 了解分支保护规则和 CI 如何使用堆栈

堆积拉取请求旨在以与任何其他拉取请求相同的方式强制实施现有规则，但值得了解的方式，因为堆栈中的每个拉取请求的评估方式与预期略有不同。

堆栈中的每个拉取请求（而不仅仅是底部请求）都会根据 **堆栈的基** 数（通常 `main`）而不是直接面向的分支进行评估。 也就是说：

* 针对堆栈中每个拉取请求的堆栈基分支强制实施所需的评审、所需的状态检查和 CODEOWNERS。
* GitHub Actions针对堆栈**中每个**拉取请求运行的事件`main`触发`pull_request`的工作流，因此现有 CI 配置不需要更改。
* 如果要专门为堆积拉取请求自定义工作流行为，则堆栈元数据可通过工作流表达式 `github.event.pull_request.stack`获取。 由于工作流在堆栈中每个拉取请求运行一次，因此团队可以使用此元数据跳过冗余运行中的昂贵作业，并减少 CI 使用率。 有关详细信息，请参阅 [优化堆积拉取请求的 CI](/zh/pull-requests/how-tos/merge-and-close-pull-requests/optimizing-ci-for-stacked-pull-requests)。

（可选）可以通过使用标准规则集和所需检查的存储库打开一个小测试堆栈，并确认：

1. 堆栈中每个拉取请求都需要评审和状态检查，而不仅仅是底部请求。
2. CI 工作流在堆栈中的每个拉取请求上运行。
3. 合并将被阻止，直到要合并的堆栈中的拉取请求及其下方的所有内容都满足你的要求。

有关规则和要求的完整列表，请参阅 [堆积拉取请求](/zh/pull-requests/reference/stacked-pull-requests)。

## 3.开始团队

查看推出注意事项并了解规则和 CI 如何使用堆栈后，请将团队指向 [堆积拉取请求](/zh/pull-requests/how-tos/stacked-pull-requests)，它将开始创建、审阅和合并堆积拉取请求所需的所有内容组合在一起。

## 4.更新编程工具

由于组织采用堆积拉取请求，请查看以编程方式创建、合并或跟踪拉取请求的任何内部工具、机器人或仪表板，并更新这些请求以考虑堆栈。

> \[!IMPORTANT]
> 合并堆积拉取请求需要堆栈 API。 旧拉取请求合并终结点无法合并堆栈。 如果组织以编程方式合并拉取请求，例如，通过内部工具或 ChatOps 机器人，请在推出堆积拉取请求之前更新该工具以调用 Stacks API。

你可能还希望以编程方式跟踪堆栈活动，例如跨仪表板、机器人或内部工具。

* **REST API**：API 返回的每个拉取请求都包括一个 `stack` 对象，当它属于堆栈时，它显示堆栈的数量、大小、拉取请求的位置以及堆栈的基分支。 专用堆栈 API （`GET /repos/{owner}/{repo}/stacks`） 还会列出存储库中的每个堆栈，或包含给定拉取请求的特定堆栈。 请参阅“[REST 和 GraphQL API 中的堆积拉取请求](/zh/pull-requests/reference/stacked-pull-requests-rest-and-graphql-apis)”。
* **Webhook**： `pull_request` 每当拉取请求属于堆栈时，Webhook 有效负载都包含相同的 `stack` 对象。 首次将拉取请求添加到堆栈时，将触发专用 `stacked` 操作，因此你可以对堆栈形成的那一刻做出反应。

在这两种情况下， `stack` 该字段用于 `null` 独立拉取请求，因此不需要堆栈的现有集成将继续保持不变。