本页目录

本页目录

流水线

适用范围

这些规则适用于任何系统中的 CI/CD 流水线——GitHub Actions、GitLab CI、CircleCI、Jenkins 或其他系统。所选系统的专属规则见对应的工具链文档。

默认选择

用户未指定流水线系统时,默认使用 GitHub Actions。平台专属规则见 GitHub Actions。

复杂度增加时的结构调整

平铺命令的流水线一旦变长就会难以阅读。应使用工具提供的阶段(stage)、任务(job)和独立文件来组织结构,不要不断堆砌未命名的 step。

  • 每个流水线单元只处理一项工作:一个流水线文件对应一个触发条件或受众,一个 job 对应一项职责,一个 step 对应一条命令。
  • 优先使用多个较小的流水线文件,不要让单个文件不断膨胀。
  • 调用项目自身的任务,而不是把项目逻辑复制进流水线 YAML(见 mise)。

完整上报每项检查

  • 只在单一触发条件下运行的任务,不要放进多触发条件的流水线里再用条件判断跳过;应为它单独建一个只绑定该触发条件的流水线文件。
  • 被条件跳过的任务仍会在运行列表中显示为 skipped,读者需要区分预期跳过和运行失败,还得推断触发条件。
  • 单看运行列表就应能一眼判断通过还是失败:流水线里的每个单元,在该流水线每次触发时都应实际执行。
  • 合并门禁会把 skipped 的必需检查视为通过,因此上述规则主要是为了可读性。真正会卡住合并的隐患是从不上报结果的必需检查:如果工作流根本没触发,或过滤条件排除了对应 job,该检查就会一直停在 pending 状态。合理拆分流水线,确保每个必需检查在任何需要它的场景下都会上报结果。

命名与可读性

只看运行日志,就能说清流水线每一层在做什么。

  • 给流水线、每个 job、每个 step 都命名。
  • 名称表达职责,而不是工具调用:使用 Validate,而不是 cog。
  • step 名称应使用简短的祈使短语,说明该 step 执行或校验的内容。在运行日志中显示为原始命令的 step,实际上等同于未命名 step;命令不是文档。

相关文档