ci-cd-pipeline-builder

name	ci-cd-pipeline-builder
description	CI/CD 流程构建器 Use when this capability is needed.
metadata	{"author":"AgentWorkers"}

CI/CD 管道构建工具

级别： 高级
类别： 工程
领域： DevOps / 自动化

概述

该工具能够根据项目代码库中的信息自动生成实用的 CI/CD 管道，而非依赖猜测。它专注于快速生成基线配置、执行可重复的测试，并实现与环境相匹配的部署流程。

核心功能

• 从代码库文件中检测编程语言、运行时环境及使用的工具链
• 推荐相应的 CI 阶段（如代码检查、测试、构建、部署）
• 生成适用于 GitHub Actions 或 GitLab CI 的初始管道配置
• 根据检测结果配置缓存策略及并行构建策略
• 输出机器可读的检测结果，以便自动化流程使用
• 确保管道逻辑与项目的锁定文件（lockfile）和构建命令保持一致

使用场景

• 为新代码库设置 CI 流程
• 替换现有的、容易出问题的手动配置文件
• 在 GitHub Actions 与 GitLab CI 之间进行迁移
• 审查管道步骤是否与实际项目配置相符
• 在进行自定义安全加固之前创建可复现的基线配置

关键工作流程

1. 检测项目配置（Detect Stack）

支持通过标准输入（stdin）或 --input 文件输入数据，以进行离线分析。

2. 根据检测结果生成管道（Generate Pipeline）

可以根据检测结果直接生成完整的 CI/CD 管道配置；或者从代码库直接生成。

3. 合并前验证（Validate Before Merge）

• 确认项目中存在必要的构建命令（test、lint、build）。
• 尽可能在本地运行生成的管道配置。
• 确保所有需要的密钥和环境变量都已正确记录。
• 确保部署任务仅能在受保护的分支或环境中执行。

4. 安全地添加部署阶段（Add Deployment Stages）

• 先设置仅包含代码检查（lint、test、build）的简单管道。
• 添加带有明确环境配置的预发布（staging）部署阶段。
• 添加需要人工审核的生产环境部署阶段。
• 确保部署命令清晰明了且可审计。

脚本接口

• python3 scripts/stack_detector.py --help
  • 从代码库文件中检测项目配置信息
  • 从标准输入或 --input 文件读取可选的 JSON 数据
• python3 scripts/pipeline_generator.py --help
  • 根据检测结果生成适用于 GitHub 或 GitLab 的 YAML 配置文件
  • 将配置内容输出到标准输出或指定文件

常见问题

• 将 Node.js 相关的 CI 配置直接复制到 Python 或 Go 项目的代码库中
• 在未完成稳定测试之前就启用部署任务
• 忘记配置缓存相关设置
• 对每个分支都执行耗时的并行构建操作
• 生产环境部署任务缺乏必要的保护机制
• 将敏感信息硬编码在 YAML 配置中而非使用专门的密钥管理工具

最佳实践

• 先检测项目配置，再生成相应的 CI/CD 管道。
• 将生成的配置文件纳入版本控制。
• 逐步引入优化措施（如缓存机制、并行构建策略）。
• 确保所有部署任务都在通过代码检查后才能执行。
• 使用受保护的环境来存储生产环境所需的凭证。
• 当项目配置发生重大变化时重新生成管道配置。

参考资料

• references/github-actions-templates.md
• references/gitlab-ci-templates.md
• references/deployment-gates.md
• README.md

检测策略

该工具优先使用确定的文件信息来进行判断，而非依赖启发式方法：

• 锁定文件（lockfile）用于确定项目使用的包管理器类型
• 语言相关信息用于确定运行时环境
• 存在的脚本命令用于触发相应的代码检查/测试/构建操作
• 如果缺少相关脚本，则使用默认的、保守的默认操作

生成策略

初始配置应尽可能简单且可靠：

1. 检出项目依赖并设置运行时环境
2. 使用缓存策略安装依赖库
3. 分别执行代码检查、测试和构建操作
4. 仅在所有步骤都通过后才能发布最终成果

平台选择建议

• 对于与 GitHub 生态系统紧密集成的场景，选择 GitHub Actions
• 对于需要集成源代码管理（SCM）和持续集成（CI）功能的自托管环境，选择 GitLab CI
• 每个代码库应使用统一的管道配置模板，以减少配置差异

验证 checklist

• 生成的 YAML 配置文件能够成功解析。
• 所有引用的命令都存在于代码库中。
• 缓存策略与项目使用的包管理器类型相匹配。
• 所需的敏感信息已正确记录（而非直接嵌入配置文件中）。
• 分支或环境访问规则符合组织的安全政策。

扩展指南

• 当单个构建任务耗时超过 10 分钟时，按阶段拆分任务。
• 仅在确实需要时才启用并行构建功能。
• 将部署任务与代码检查任务分开执行，以加快反馈速度。
• 将管道执行时间和稳定性作为关键指标进行监控。

---

Source: AgentWorkers/skills — distributed by TomeVault.