许多团队曾在此踩坑——.gitlab-ci.yml虽然配置详尽，却遗漏了Webhook的启用；或者相反，Webhook设置正确，但CI中未声明codequality报告产物，导致LLM的审查结果无法嵌入到Diff视图中。要确保流程畅通，需注意以下三点：
- Webhook需勾选“Merge request events”选项，并将URL指向自部署的Flask/Python服务（例如
/webhook/mr） - CI配置中必须明确添加
artifacts: reports: codequality，且报告格式须为GitLab兼容的JSON，其中必须包含description、severity、location字段 - MR事件需区分
open和update：对于open事件，应拉取全量diff；对于update事件，建议仅分析变更行，否则每次调用LLM都会重复扫描整个文件，导致延迟大幅增加
让GitLab正确识别HTML代码质量的方法
GitLab默认不会自动解析HTML文件进行质量扫描——需要显式启用对应的linter，并输出标准格式的报告。仅运行htmlhint或eslint-plugin-html，MR的“代码质量”面板中并不会显示结果。
关键在于报告路径和格式。GitLab仅识别gl-code-quality-report.json这个文件名（或通过codequality关键字声明），且内容必须包含type: "issue"以及可定位的location字段。推荐做法如下：
- 在
.gitlab-ci.yml中添加一个独立job，例如命名为html-quality，使用node:18-alpine镜像 - 命令示例：
npx htmlhint --format=codeclimate src/**/*.html > gl-code-quality-report.json - 确保
artifacts中包含该文件，并在reports下进行声明：codequality: gl-code-quality-report.json - 如果使用自定义工具（例如Python配合BeautifulSoup检查内联script标签），输出JSON时
severity字段只能取值为info、minor、major、critical之一，其他值GitLab将无法识别
AI审查结果为何未显示在MR Diff区域
LLM生成的评审意见默认仅作为MR评论（Note）存在，不会自动注入到代码行级视图中。若希望在Diff行旁边看到气泡提示，需要调用GitLab API的POST /projects/:id/merge_requests/:mr_iid/notes接口，并传入position参数——这并非简单的文本评论，而是包含上下文锚点的结构化数据。
容易忽略的是position字段的构造相当复杂：需要包含base_sha、start_sha、head_sha、old_path、new_path、position_type（通常为text），以及line（新文件中的行号）。只要缺少任一字段，API就会返回400 Bad Request。
- 这些SHA值不能硬编码，必须从Webhook payload的
object_attributes.last_commit和diff_refs中动态提取 - 行号计算需格外谨慎：HTML文件中的空行、注释行是否计入？
htmlhint输出的行号为源码行号，而GitLab Diff显示的是“新文件”逻辑行号，两者可能不一致 - 如果MR包含多个文件，每个评论必须单独POST，且不能并发调用——GitLab API存在速率限制，并发请求很容易触发429响应
为何本地测试通过，MR流水线中的HTML扫描却失败
根本原因通常是环境差异：本地使用全局安装的htmlhint，而CI中使用的却是镜像内的Node版本和依赖树。最常见的坑是package-lock.json未提交，或npm ci被跳过，导致插件版本不一致。
另一个隐蔽问题是路径匹配。CI中的工作目录为$CI_PROJECT_DIR，但htmlhint默认会递归扫描当前目录下所有.html文件——如果项目中包含node_modules或构建产物（如dist/），则可能因文件权限或体积超限而失败。以下是一些实用建议：
- 强制指定扫描路径：
npx htmlhint --config=.htmlhintrc src/**/*.{html,htm} - 在
.gitlab-ci.yml中添加一段before_script检查：ls -la src/ | head -5，确保HTML文件确实存在 - 避免使用
**通配符匹配过深目录，改用src/{components,pages}/**/*.html精确控制范围 - 如果报错
ENOSPC（磁盘空间不足），说明镜像中的临时空间不足，可以添加cache: {key: "$CI_JOB_NAME", paths: ["node_modules/"]}来复用缓存
GitLab对HTML质量的反馈，依赖于精确的报告结构和上下文锚定，绝非“跑完工具就完事”。行级评论需要完整的Git引用信息，而HTML扫描失败往往卡在环境或路径细节上——这些地方既没有日志也没有提示，只能通过手动验证每一步输出，才能逐一填平这些坑。
