Ansible Backport 自动化脚本详解：用 backport_of_line_adder.py 为 Backport PR 自动补全 "Backport of" 引用

本文以 Ansible 仓库 hacking/backport/ 目录下的 README 文档为核心，讲解其中 backport PR 维护脚本 backport_of_line_adder.py 的用途、调用方式与交互流程，并结合 脚本源码 深入剖析其 PR 地址归一化、auto 模式自动溯源、以及 PR 正文改写等底层实现，帮助 Ansible 维护者理解并正确使用这套 backport 维护工具链。

背景：Ansible 的分支模型为什么需要 Backport 工具

在深入脚本之前，先明确它解决的实际问题。根据仓库的贡献规范 context/contributing.md，Ansible 的分支与发布管理遵循以下规则：

• 所有 PR 默认指向 devel 分支；
• Bug 修复只回移（backport）到最新的 stable 分支；
• 关键 Bug 修复回移到最新与次新的两个 stable 分支；
• 验证顺序上，应先确认问题在 devel 上已修复，再针对 stable 版本提问题。

这意味着同一个修复往往会在 GitHub 上产生"原始 PR + 若干 backport PR"。Backport PR 的正文里需要一条 Backport of <原 PR 链接> 引用，方便审查者确认回移来源。README（hacking/backport/README.md）说明：该目录存放"用于处理和回移维护的脚本，依赖 pygithub，并要求环境变量 GITHUB_TOKEN 中有一个有效的 GitHub token"。目前目录中实际提供的是 backport_of_line_adder.py 这一个可执行脚本（另有空的 init.py）。

使用方式与前提准备

准备 GitHub Token

脚本通过 GitHub REST API 读取并修改 PR 正文，因此必须有一个具备 repo 权限的 personal access token。脚本在缺少 GITHUB_TOKEN 时会直接退出并提示：

Go to https://github.com/settings/tokens/new and generate a
token with "repo" access, then set GITHUB_TOKEN to that token.

（对应 backport_of_line_adder.py 的入口检查）。README 同样说明 token 需到 GitHub 的 token 设置页面生成。

基本调用形式

README 给出的标准用法是：

./backport_of_line_adder.py <backport> <original PR>

即第一个参数是新的 backport PR，第二个参数是已经被合入的原始 PR。脚本会尝试向 backport PR 的正文中添加一行 Backport of <原 PR URL>。

README 同时指出，脚本内置了"自动推断原始 PR"的逻辑，只要把第二个参数写成 auto 即可触发：

./backport_of_line_adder.py 12345 auto

这个例子会为 backport PR #12345 寻找应当引用的原始 PR。无论哪种模式，README 都强调：脚本在执行任何修改前都会提示你确认，并让你先审阅它即将引用的那个 PR。写入位置规则是——如果 backport PR 正文里存在 SUMMARY 标题行，引用行就加在它的正下方；否则加在正文最底部。

参数解析：normalize_pr_url 支持哪些输入形式

README 只说了参数是"PR"，而源码揭示了它对输入形式的宽容度。backport_of_line_adder.py 中的 normalize_pr_url() 是参数归一化的核心：

def normalize_pr_url(pr, allow_non_ansible_ansible=False, only_number=False):
    """
    Given a PullRequest, or a string containing a PR number, PR URL,
    or internal PR URL (e.g. ansible-collections/community.general#1234),
    return either a full github URL to the PR (if only_number is False),
    or an int containing the PR number (if only_number is True).

    Throws if it can't parse the input.
    """

从源码结构看，它接受三类输入：

1. 纯数字（如 12345）：直接视为 ansible/ansible 仓库的 PR 号；
2. 完整 PR URL（https://github.com/.../pull/1234）：按 PULL_HTTP_URL_RE 正则匹配；
3. 简写引用（ansible-collections/community.general#1234 这种 user/repo#number 内部引用格式）：按 PULL_URL_RE 正则匹配。

其中 only_number=True 时只返回 PR 号（整数），否则返回可打开的完整 URL。一个值得注意的细节：第二个参数（原始 PR）在解析时会额外传 allow_non_ansible_ansible=True（见 主流程），即允许引用其他仓库（比如 ansible-collections 下的 collection 仓库）的 PR；而第一个参数（backport PR 本身）则默认要求必须是 ansible/ansible，否则抛出 Non ansible/ansible repo given where not expected 异常。

自动推断模式：search_backport 的溯源策略

当第二个参数为 auto 时，search_backport() 就是 README 所说的"自动推断原始 PR"的"大脑"。它按优先级从 backport PR 中提取候选来源，最终返回一个候选 PullRequest 列表：

1. 标题匹配。正则 PULL_BACKPORT_IN_TITLE（第 29 行）匹配形如 foo bar change (#12345) 或 foo bar change (backport of #54321) 的标题后缀，抽出其中的 PR 号并在 ansible/ansible 仓库中加载对应 PR；
2. 正文逐行扫描，寻找两类线索：
   • cherry-pick 引用行：正则 PULL_CHERRY_PICKED_FROM（第 30 行）匹配 cherry-picked from commit XXXXX 这类 git 回移惯例写法。拿到 commit hash 后，调用 get_prs_for_commit()，通过 GitHub 的 commit 搜索 API（hash:<hash> org:ansible org:ansible-collections is:public）反查该 commit 出现在哪些 PR 中；
   • 其他 PR 引用：行内出现的 #12345（默认归属 ansible/ansible）、user/repo#1234 简写、以及完整 PR URL，都会被收集并逐个尝试加载为 PullRequest 对象（跨仓库引用会先 g.get_repo(repo_path) 取仓库对象）。

代码中对每条线索的解析都包在 try/except 里静默跳过失败项，因此该函数可以返回多个候选。不过 主流程中的注释 坦承了一个已知局限：目前只取第一个候选（"也是可能性最大的候选"），循环提示用户选择的逻辑仍是 TODO。若一个候选都找不到，脚本打印 No match found, manual review required. 并退出——这正是 README 所说的"触发自动推断逻辑"的兜底路径，此时需要人工判断。

写入 PR 正文：generate_new_body 与幂等保护

README 描述的"加在 SUMMARY 下方、否则加在末尾"的行为，由 generate_new_body() 实现。逐行看它的规则：

• 待插入的文本固定为 \nBackport of <原 PR URL>\n；
• 逐行遍历 backport PR 现有正文，如果任何一行已包含 Backport of http，立即抛出 Already has a backport line, aborting. ——这是一道幂等保护，防止脚本被重复执行时叠加多条引用；
• 遇到以 # 开头且去掉空白后以 SUMMARY 结尾的行（如 PR 模板里的 ##### SUMMARY），就把引用行插到它后面并标记成功；
• 遍历结束仍无 SUMMARY 行，则把引用行追加到正文最底部。

这与 Ansible 的 PR 模板是一致的：仓库中 Bug fix.md、New feature.md、Tests.md、Documentation change.md 等模板的第一行均为 ##### SUMMARY，所以绝大多数规范模板创建的 PR 都会命中"SUMMARY 下方插入"这条路径，引用行恰好出现在摘要之后、正文细节之前。

真正的写入动作在 commit_edit() 中完成：它先打印"我认为这个 PR 可能来自："、候选 PR 的标题和 URL，调用 prompt_add() 交互式询问 Shall I add the reference? [Y/n]: （回车、y、yes 均视为同意），确认后才调用 new_pr.edit(body=new_body) 通过 API 修改 PR 正文，最后打印 I probably added the reference successfully.（源码用"probably"措辞，因为 API 调用成功并不等于编辑已完全生效，这是一种谨慎表述）。

入口检查与错误处理一览

脚本入口 定义了完整的失败路径，实际使用时可对照排错：

情况	脚本行为
参数个数不是 2 个，或第一个参数不是纯数字	打印 Usage: <new backport PR> <already merged PR, or "auto">，退出码 1
未设置 GITHUB_TOKEN	提示到 GitHub token 设置页生成 repo 权限的 token，退出码 1
第一个参数无法解析或对应 PR 加载失败	打印 Could not load PR <参数>，退出码 1
auto 模式未找到任何候选	打印 No match found, manual review required.，退出码 1
第二个参数指定的 PR 无法加载	打印异常信息与 Could not load PR <参数>，退出码 1
backport PR 已含 Backport of http 行	抛出 Already has a backport line, aborting.

实操建议

• 优先用 auto，失败再手动。按 context/contributing.md 的规则，backport 的 commit 通常来自对 stable 分支的 git cherry-pick，若 backport PR 正文里写明了 cherry-picked from commit <hash>，auto 模式的 commit 反查命中率最高；
• 标题里带上原始 PR 号是最省事的习惯。若标题写成 ... (backport of #12345) 或 ... (#12345)，search_backport 的第一步就能锁定候选；
• 始终审阅提示中的候选 PR。脚本在修改前展示的只是"最可能的候选"（auto 模式只取第一个），来源 PR 标题、URL 确认无误后再按 y；
• 该脚本面向 ansible/ansible 仓库的 backport 流程，若你要维护其他项目，可参考 normalize_pr_url 的 allow_non_ansible_ansible 机制理解其仓库边界的实现方式，而不要直接假定它适用于任意仓库。

综上，backport_of_line_adder.py 虽然只有两百多行，但完整覆盖了 backport 维护中的典型痛点：PR 地址格式多样、来源信息散落在标题/正文/cherry-pick 注释中、以及误操作风险——分别以输入归一化、多路线索溯源和"先确认再写入 + 幂等保护"来应对。配合 context/contributing.md 中的回移策略，它构成了 Ansible 稳定分支维护工作中一条轻量的自动化链路。