CICD AIops

CICD AIops

面向自托管 GitLab 和 Gitea 的受治理 AI 运维。

cicd-aiops 面向使用自己的 CI/CD 代码托管平台的团队——部署在自有硬件、实验室或 VPN 后方的 GitLab 实例或 Gitea 服务。这些团队需要 AI Agent 来回答“流水线为何失败？”，“哪个运行器卡住了？”，“40 GB 的制品存储空间去哪了？”以及“哪些工作已过期？”，并通过经过审计、设有预算、按风险分级且记录撤销操作的治理框架来执行操作（重试、取消、暂停、删除、保护）。它不是 SaaS 集成：它直接通过 GitLab REST API v4 和 Gitea API v1 连接你的服务，凭据在静态存储时会加密。

验证状态：根据各项目的公开 API 文档建模，并通过模拟 HTTP 响应进行测试；目前尚无针对真实服务的端到端运行记录。cicd-aiops doctor 是最快的实时检查方式——请参阅 docs/VERIFICATION.md。

路由：请勿将此工具用于 Kubernetes 部署状态——请使用 k8s-aiops。本工具的范围止于 CI/CD 服务的 API（流水线、运行器、制品、仓库维护）。

此工具负责什么，不负责决定什么

它准确、高效地执行 CI/CD 操作——读取和写入——并记录每一项操作。它不会决定是否允许执行写入。这由 Agent 判断，或由你连接时使用的令牌权限决定：如果提供的 GitLab/Gitea 访问令牌没有写入权限，写入操作就会在服务端失败——权限实际由服务端管理。

因此，这里没有只读开关、策略文件或需要配置的审批关卡。此工具唯一保证的是没有任何操作会悄无声息：通过 MCP 和 CLI 发出的每次调用都会在 ~/.cicd-aiops/audit.db 中生成一条审计记录，破坏性写入仍会捕获操作前状态，并在存在相应逆向操作时记录该操作。

每个工具都会声明 risk_level，并通过测试确保其与文档中的 [READ]/[WRITE] 标签一致；该等级也会作为描述性级别写入审计记录，让审查者一眼就能看出某条记录对应高风险删除操作。它只是标签，不是关卡。

如果你运行的是较小型／本地模型，请参阅 agent-guardrails.md——其中列出了此工具为你执行的防护措施（这样你就不必在提示词中重复说明），并提供了可直接使用的系统提示词，用于处理剩余事项。

快速开始

作为 Claude Code 插件

安装一次，即可让 Agent 同时获得技能和 MCP 服务：

/plugin marketplace add AIops-tools/marketplace
/plugin install cicd-aiops@aiops-tools

MCP 服务通过 uv 获取，并固定到此插件声明的程序包版本，以便将审计记录追溯到写入记录的代码。凭据仍通过 cicd-aiops init 配置——见下文。

作为 OpenClaw 插件

同一套程序包发布在 ClawHub，安装一次即可同时获得技能和 MCP 服务：

openclaw plugins install clawhub:@zw008/cicd-aiops
openclaw skills info cicd-aiops          # expect: Visible to model: yes

之后重启 OpenClaw 网关，使其加载插件。MCP 服务通过 uv 获取，并固定到此确切版本，因此 uvx 必须位于 PATH 中——否则技能仍会安装，但会报告 Visible to model: no。凭据按下文所述配置。

作为 CLI 或独立 MCP 服务

uv tool install cicd-aiops        # or: pip install cicd-aiops

cicd-aiops init        # wizard: base URL + token (encrypted) + TLS verify
cicd-aiops doctor      # connectivity + token-scope probe per target
cicd-aiops overview    # version, identity, projects, runners at a glance

接下来是重点内容：

cicd-aiops rca pipelines dev/api        # classify recent failed pipelines
cicd-aiops rca runners                  # offline/stale runners, tag saturation
cicd-aiops rca storage                  # artifact/repo bloat, reclaimable bytes
cicd-aiops rca stale dev/api            # stale MRs/branches, protection gaps

cicd-aiops pipelines retry dev/api 42 --dry-run
cicd-aiops artifacts delete dev/api --older-than-days 30 --dry-run

每项写入操作都支持 --dry-run 和双重确认，并通过 MCP 工具使用的同一条受治理路径执行——因此 CLI 写入操作也会经过审计。

支持范围

接口	GitLab（REST v4，自托管）	Gitea（API v1，可自托管）
服务版本 + 令牌身份	✅	✅
项目 + 存储统计信息	✅（statistics=true）	✅（仓库 size）
流水线 / 运行、作业、日志尾部	✅	✅（Actions 运行、作业、日志）
Runner 集群（列表/详情）	✅	❌ 教学错误（API v1 中无对应接口）
合并请求/拉取请求、分支、保护规则、发布版本	✅	✅
制品清单	✅（通过作业）	✅（Actions 制品）
retry_pipeline / cancel_pipeline	✅	❌ 教学错误
pause_runner / resume_runner	✅	❌ 教学错误
delete_artifacts	✅	❌ 教学错误
update_branch_protection	✅	✅

如果平台不支持某个接口，平台注册表会抛出教学错误，指出实际可用的资源，让 Agent 从中学习，而不是遇到不明原因的 404。GitLab.com / Gitea Cloud SaaS 账户有意不在支持范围内：此工具面向自托管实例。

旗舰分析（本工具存在的理由）

1. pipeline_failure_rca — 获取近期失败的流水线及失败作业的日志尾部，并对每项失败进行分类：测试失败 / 依赖网络 / Runner 超时 / 内存溢出 / 脚本错误，同时提供匹配到的证据、原因，以及针对每条流水线的操作建议。
2. runner_health_rca — 检测离线/陈旧/暂停的 Runner（按联系时间阈值判断）、排队时间超过阈值的作业，以及按标签统计的饱和度（排队作业数与在线 Runner 数）。
3. artifact_storage_bloat_analysis — 按仓库和制品字节数对项目排序，识别已过期但仍保留的制品，并估算可回收字节数，可直接传入 delete_artifacts --dry-run。
4. stale_work_audit — 审计闲置超过 N 天的合并请求/拉取请求、N 天未提交过更改的分支，以及保护规则缺失情况（默认分支未受保护、允许强制推送）。

以上四项都是透明的启发式分析：阈值均为命名参数，每个标记都附带具体数值。

治理（内置且始终启用）

每个 MCP 工具和每次 CLI 写入都会经过 cicd_aiops/governance/ 中随项目提供的治理工具。它负责记录，不负责授权（见上文）。

• 审计 — 每次调用（参数、结果、状态、耗时、风险等级，以及操作员提供的审批人/理由）都会记录到 ~/.cicd-aiops/audit.db（可通过 CICD_AIOPS_HOME 更改位置）。CLI 写入与 MCP 路径写入相同的记录行，因此不存在未经审计的入口。
• 失控防护 — 这是安全后备机制，并非授权门槛：短时间内反复执行相同调用会触发断路器，防止失控的 Agent 无限制地消耗调用次数/时间。使用 CICD_RUNAWAY_MAX=0 禁用；也可通过 CICD_MAX_TOOL_CALLS / CICD_MAX_TOOL_SECONDS 设置硬性上限。
• 撤销 — 可逆写入会根据获取到的变更前状态，在 ~/.cicd-aiops/undo.db 中记录可重放的逆向操作： pause_runner ⇄ resume_runner，而 update_branch_protection 会重放之前的设置。不可逆写入（retry_pipeline、cancel_pipeline、delete_artifacts）则改为记录 priorState（状态 / 字节数+数量）。
• 风险等级 — 根据 risk_level 派生的审计记录描述性标签（读取为 low；修改类写入为 medium；delete_artifacts 为 high）；不会限制任何操作。
• 全程支持试运行 — 每项写入都接受 dry_run=True（MCP）/ --dry-run（CLI），并会预览操作，而不调用服务。
• 净化 — 所有服务返回的文本都会通过可防注入的规范化处理（限制字符串长度、限制深度）后再交给 Agent；所有路径参数都会进行百分号编码，确保标识符绝不会改写 URL。

密钥

令牌存储在 ~/.cicd-aiops/secrets.enc 中，使用 Fernet 加密，密钥通过 scrypt 从主密码派生。磁盘上绝不存储明文。非交互式/MCP 使用时，请设置 CICD_AIOPS_MASTER_PASSWORD，并使用 cicd-aiops secret set|list|remove|migrate 管理。TLS 验证默认开启 （初始化向导会在关闭验证以使用实验室证书前征求确认）。

MCP 服务

提供 26 个受管控的工具（20 个读取工具，包括四项旗舰分析，以及 6 个写入工具）。

{
  "mcpServers": {
    "cicd-aiops": {
      "command": "uvx",
      "args": ["--from", "cicd-aiops", "cicd-aiops-mcp"],
      "env": {
        "CICD_AIOPS_MASTER_PASSWORD": "your-master-password"
      }
    }
  }
}

环境块注意事项：MCP 客户端启动服务时使用的是最小化 环境，不会加载 shell 配置文件。服务所需的一切 （CICD_AIOPS_MASTER_PASSWORD、CICD_AIOPS_HOME，以及任何可选的 CICD_AUDIT_APPROVED_BY 审计注释）都必须设置在上方的 env 块中， 而不是 ~/.zshrc 中。

或者：cicd-aiops mcp（同一服务的命令行入口）。

配置

~/.cicd-aiops/config.yaml（向导会写入此文件）：

targets:
  - name: gl1
    platform: gitlab            # or: gitea
    base_url: https://git.example.com
    verify_ssl: true            # default ON; set false only for lab certs

每个目标的令牌都会以该目标的名称为键加密存储。 使用 CICD_AIOPS_HOME 可迁移所有状态（配置、审计、撤销记录、密钥）。

开发

uv sync
uv run pytest -q
uv run ruff check .

缺功能？

欢迎留言提交问题或 PR——如果缺少你需要的 GitLab/Gitea 功能 （较新版本 Gitea 的运行器管理、按作业重试、计划流水线、 组级汇总等），请到 https://github.com/AIops-tools/CICD-AIops 提交问题或 PR。平台注册表经过设计， 新增资源只需添加一条路径映射，而不必重构。

许可证

MIT。GitLab 是 GitLab Inc. 的商标；Gitea 是其项目所有者的商标。本项目独立开发，与两者均无关联。