Envoy 开发支持工具链support/实战指南DCO 自动签名与 Git Hook 格式校验【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy导读Envoy 仓库根目录下的support/目录维护着一套面向 Envoy 贡献者的命令行开发支持工具其核心职责是围绕代码评审流程做自动化在每次 commit 时自动补全 DCODeveloper Certificate of Origin签名在每次 push 前对本次 diff 涉及的所有文件自动执行 DCO 与代码格式检查。读完本文你将掌握如何一键初始化这套工具链./support/bootstrap、理解两个 Git Hook 的底层实现原理以及在格式检查失败时如何用 Bazel 命令或 Docker 环境快速修复格式问题。一、support/ 工具链是什么support/是一组 CLI 工具的集合定位是支撑并自动化 Envoy 开发过程中的各个侧面尤其是与代码评审相关的部分原文见 support/README.md。目前它公开了两大核心功能自动追加 DCO 签名若一条 commit message 末尾尚不存在Signed-off-by:签名则在提交前自动将其追加到 commit message 末尾该逻辑正确处理了git commit --amend与rebase等边界场景。push 前自动校验在git push之前自动对本次推送涉及 diff 的所有文件执行 DCO 签名检查与代码格式检查从源头拦截不合规提交进入远端分支。整个support/目录结构非常精简仅包含三个文件support/ ├── README.md # 使用说明本文的主体文档 ├── bootstrap # 一键初始化脚本安装 git hooks 到 .git/hooks └── hooks/ ├── prepare-commit-msg # commit 钩子自动追加 DCO 签名 └── pre-push # push 钩子DCO 格式检查这套工具链与仓库根目录的 DCO 文件直接呼应。DCO文件收录的是 Linux Foundation 发布的 Developer Certificate of Origin 1.1 版本全文贡献者通过在自己的提交信息中附加Signed-off-by:行声明自己对提交内容拥有相应权利并同意其被公开记录与再分发。二、一键初始化./support/bootstrap使用这套工具链只需在 Envoy 项目根目录执行一条命令./support/bootstrap该命令会自动完成开发支持工具链的安装。工具链大量依赖 Git Hooks 机制因此bootstrap的核心动作就是把support/hooks下的钩子脚本以符号链接方式安装到本仓库的.git/hooks目录。2.1 bootstrap 的源码级细节阅读 support/bootstrap 脚本源码可以看到几个值得注意的实现要点根目录校验脚本开头会做一次尽力而为的检查确认当前工作目录就是 Envoy 源码树的根目录通过比较pwd -P与git rev-parse --show-toplevel的输出不满足时直接报错退出。路径计算辅助函数脚本内置了abspath与relpath两个函数注释说明这段代码取自 Apache Mesos 项目并沿用 Apache V2 许可用于计算钩子安装时的相对符号链接路径。兼容子模块场景脚本优先使用较新的git rev-parse --git-common-dir定位.git目录即使仓库是作为子模块存在也能正确工作若该命令不可用则回退到旧的git rev-parse --git-dir。幂等安装与强制重装只有当.git/hooks/prepare-commit-msg或.git/hooks/pre-push不存在时才会安装对应钩子如果设置了环境变量REINSTALL_HOOKS则无论钩子是否已存在都会重新创建符号链接。安装完成后.git/hooks下会出现两个指向support/hooks的符号链接prepare-commit-msg与pre-push。之后的每次 commit / push 都会自动触发钩子逻辑。三、commit 钩子DCO 签名自动追加prepare-commit-msg是 Git 在执行默认提交信息生成之后、打开提交信息编辑器之前触发的钩子非常适合在此阶段向 commit message 注入内容。查看 support/hooks/prepare-commit-msg 的完整实现COMMIT_MESSAGE_FILE$1 AUTHOR$(git var GIT_AUTHOR_IDENT) SIGNOFF$(echo $AUTHOR | sed -n s/^\(.*\).*$/Signed-off-by: \1/p) if ! grep -qs ^$SIGNOFF $COMMIT_MESSAGE_FILE; then echo -e \n$SIGNOFF $COMMIT_MESSAGE_FILE echo -e Appended the following signoff to the end of the commit message:\n $SIGNOFF\n fi其工作原理可分三步理解通过git var GIT_AUTHOR_IDENT读取当前提交作者的身份信息形如Name email timestamp tz用sed提取其中的email部分拼装出标准 DCO 签名行Signed-off-by: Name email用grep -qs检查提交信息中是否已存在该签名行若不存在则在 commit message 末尾追加一行空行 签名并在终端打印提示。正是追加发生在编辑器打开之前这一时序设计让该钩子天然兼容git commit --amend与rebase场景——无论提交信息来自默认模板、-m参数还是 amend 时复用的旧信息只要缺少签名就会被自动补上从而保证仓库内每一条提交都满足 DCO 要求。四、push 钩子push 前的 DCO 与格式双保险pre-push钩子在git push建立与远端连接之后、实际推送对象之前执行是防止不合规代码流向远端分支的最后一道关卡。完整实现见 support/hooks/pre-push其执行流程如下。4.1 跳过机制NO_VERIFY钩子开头会加载仓库根目录下的.env文件若存在并检查NO_VERIFY环境变量一旦置位则直接exit 0跳过全部检查。因此有两种官方支持的跳过方式详见 support/README.md# 方式一git 原生跳过钩子 git commit --no-verify # 方式二把 NO_VERIFY 写入仓库根目录 .env推荐可持久生效 echo NO_VERIFY1 .env # 方式三临时导出环境变量 export NO_VERIFY1注意钩子本身在运行时也会打印提示告知开发者跳过方式是push --no-verify或在.env中加入NO_VERIFY1。4.2 按推送场景计算检查范围钩子逐条读取git push提供的LOCAL_REF LOCAL_SHA REMOTE_REF REMOTE_SHA四元组并根据三种场景计算需要检查的 commit 范围RANGE删除分支LOCAL_SHA为全零的DUMMY_SHA无事可做直接退出新建分支REMOTE_SHA为DUMMY_SHA校验最近一次提交LOCAL_SHA~1..LOCAL_SHA注释说明虽然无法确定新代码具体在哪个提交里但校验最近提交是大概率覆盖新代码的做法更全面的检查交给 CI 兜底更新已有分支校验REMOTE_SHA..LOCAL_SHA即本次推送新增的所有提交。4.3 第一道检查DCO 签名校验注释明确解释了为什么 DCO 检查排在格式检查之前格式检查存在偶发失败的概率而 DCO 检查理论上绝不应该失败。其实现思路是SIGNED_OFF$(git rev-list --no-merges --author $AUTHOR --grep ^Signed-off-by: $RANGE) NOT_SIGNED_OFF$(git rev-list --no-merges --author $AUTHOR $RANGE | grep -Fxv $SIGNED_OFF)即从范围内排除 merge commit筛选出当前作者名下没有Signed-off-by:签名的提交一旦存在就在 stderr 打印错误并逐一列出缺失签名的提交形如git log --prettyoneline --abbrev-commit的摘要随后以退出码 1 终止 push。这里采用只要存在签名即通过的宽松策略因为无法假设提交一定由推代码的人签名。4.4 第二道检查格式校验DCO 通过后钩子取出范围内发生变更的文件列表git diff --name-only ... --diff-filterACMR只考虑新增/复制/修改/重命名依次执行三道格式相关检查bazel run //tools/code_format:check_format -- check ${CHANGES[]} # C/代码格式 $CI_DIR/do_ci.sh check_proto_format # proto 格式 bazel run //tools/code:check -- -s main -v warn # 静态代码检查任一环节失败都会中断 push。可见该钩子实际串联了仓库内的多个检查工具tools/code_format/check_format.py 负责 C/BUILD 等文件格式其 argparse 定义了check/fix两种模式及--fail_on_diff等选项ci/do_ci.sh 中的check_proto_format分支调用 tools/proto_format/proto_format.sh 做 proto 格式校验//tools/code:check目标则执行代码规范检查。此外钩子还内建了一个贴心机制通过PRE_PUSH_REMOTE_IDLE_WARNING_SECONDS默认 300 秒监控钩子总耗时若检查时间过长导致与远端的 SSH 连接可能超时会打印警告并建议重试同一 push 命令第二次本地缓存已热通常更快且能成功。五、修复格式问题三种途径当 pre-push 的格式检查报错时support/README.md 给出了两条修复路径手动修复受影响的文件或运行官方提供的格式修复脚本。以下是文档原生的三个可直接复制的命令。5.1 本地直接运行格式修复bazel run //tools/code_format:check_format -- fix bazel run //tools/code:check -- fix -s main -v warn//tools/code_format:check_format -- fix以fix模式运行格式检查工具直接改写不合规的源文件与 pre-push 中使用的check模式相对check只报告不修改。//tools/code:check -- fix -s main -v warn以fix模式运行代码规范检查-s main指定检查集set为main-v warn将日志级别设为warn。5.2 在 Docker 容器内执行 format 检查Envoy 的 CI 依赖一套 Docker 化的标准环境本地复现同样环境可借助 ci/run_envoy_docker.sh./ci/run_envoy_docker.sh ./ci/do_ci.sh format这条命令会在 Envoy 官方开发容器内执行ci/do_ci.sh的format分支。查看 ci/do_ci.sh 第 990 行附近的实现该分支会调用 ci/format_pre.sh依次执行//tools/code:check_test代码检查自身的测试//tools/spelling:check_spelling_pedantic -- --mark check --target_root$PWD拼写检查rules_rust//:rustfmtRust 代码格式检查若 rustfmt 产生了改动则报错//tools/code_format:check_format -- fix --fail_on_diff以fix模式运行格式修复并通过--fail_on_diff在修复后仍有 diff 时判失败。任何一步失败脚本都会把建议修复的 diff 输出到DIFF_OUTPUT默认/build/fix_format.diff并在日志中提示应用以下 diff 即可修复部分问题。5.3 在 Docker 容器内运行 clang-tidy对于更深入的静态分析可以使用 clang-tidy。由于它需要完整的编译数据库compilation database耗时会显著变长support/README.md 原文也特别提醒了这一点./ci/run_envoy_docker.sh ci/do_ci.sh clang_tidy查看 ci/do_ci.sh 第 624 行附近的clang-tidy分支其流程包括设置--configclang-tidy编译配置以生成编译数据库在指定目标CLANG_TIDY_TARGETS上运行 clang-tidy最后通过//tools/clang-tidy:collect_fixes目标把收集到的修复结果汇总为clang-tidy-fixes.yaml文件供开发者查阅。六、在提交流中的完整工作链路把上述机制串起来一位 Envoy 贡献者的标准提交流程是这样的./support/bootstrap # 1. 一次性安装 hooks新克隆仓库后 ... 修改代码 ... # 2. 开发 git commit -m fix: xxx # 3. 提交prepare-commit-msg 自动补 DCO 签名 git push # 4. 推送pre-push 校验 DCO 格式失败则阻断其中第 3 步若 commit message 缺签名会被自动补上并打印提示第 4 步若 DCO 缺失会列出具体提交号若格式不合规则需要参照第五节的三条命令修复后重推。由于 pre-push 校验的是本次推送的新增提交REMOTE_SHA..LOCAL_SHA历史遗留问题不会阻塞增量推送而新建分支场景则用最近一次提交近似覆盖最终兜底交给 CI。七、扩展阅读DCODeveloper Certificate of Origin 1.1 全文理解Signed-off-by:行法律语义的第一手材料support/bootstrap钩子安装脚本完整源码support/hooks/prepare-commit-msg、support/hooks/pre-push两个钩子的完整实现tools/code_format/check_format.py格式检查/修复工具的入口支持check/fix模式及--fail_on_diff、--add-excluded-prefixes、--api-prefix等参数ci/format_pre.shCIformat流程中各检查步骤的实际执行顺序ci/do_ci.shformat、check_proto_format、clang-tidy等 CI 分支的实现其中format-api/fix_proto_format分支还提供 proto 格式的检查与修复ci/run_envoy_docker.sh本地以 Docker 复现 CI 环境的入口脚本。需要说明的是本文介绍的所有安装、检查与修复操作都只涉及本地开发环境与 Git 配置.git/hooks、.env不会改动仓库受版本控制的源码文件可放心按文档操作。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考