CICD AIops

CICD AIops

セルフマネージドの GitLab とセルフホストの Gitea 向けに、ガバナンスを適用した AI 運用。

cicd-aiops は、自前の CI/CD フォージを運用するチーム向けです。自社のハードウェア上、ラボ内、VPN の内側にある GitLab インスタンスや Gitea サーバーを使い、「パイプラインが失敗した理由は？」「応答しなくなったランナーはどれ？」「アーティファクトストレージの 40 GB はどこへ消えた？」「どの作業が滞留している？」といった質問に答え、その後、監査済みで、予算管理され、リスクレベル別に分類され、取り消し記録が残るガバナンスハーネスを通じてのみ操作（再試行、キャンセル、一時停止、削除、保護）できる AI エージェントを求めるチーム向けです。SaaS との連携ではありません。GitLab REST API v4 と Gitea API v1 を通じてサーバーに直接接続し、認証情報は保存時に暗号化されます。

検証状況：各プロジェクトの公開 API ドキュメントに基づいてモデル化し、モック HTTP レスポンスを使って動作を確認しています。実サーバーに対するエンドツーエンドの実行記録はまだありません。実環境での最速の確認方法は cicd-aiops doctor です。詳しくは docs/VERIFICATION.md を参照してください。

ルーティング：Kubernetes のデプロイ状態には使用しないでください。k8s-aiops を使用してください。このツールは CI/CD サーバーの API（パイプライン、ランナー、アーティファクト、リポジトリの整理）までを対象とします。

このツールが判断すること、判断しないこと

このツールは CI/CD 操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを許可するかどうかは判断しません。それはエージェントの判断、または接続するトークンの権限によります。書き込みスコープのない GitLab/Gitea アクセストークンを渡した場合、実際に権限を管理する場所であるサーバーで書き込みが失敗します。

そのため、読み取り専用スイッチも、ポリシーファイルも、設定が必要な承認ゲートもありません。このツールが保証するのは、何もひそかに実行されないことです。MCP と CLI のどちらを通じた呼び出しも、すべて監査行として ~/.cicd-aiops/audit.db に記録されます。また、破壊的な書き込みでは、実行前の状態を取得し、可能な場合は取り消し操作も記録します。

各ツールには risk_level が宣言されています。テストによって [READ]／[WRITE] のドキュメントタグと一致するように保たれ、説明用の階層として監査行にも記録されるため、レビュー担当者は高リスクの削除操作だったことをすぐに確認できます。これはラベルであり、制限機能ではありません。

より小規模なモデルやローカルモデルを実行していますか？agent-guardrails.md を参照してください。このツールが適用するガードレール（プロンプトの予算を使って繰り返し指示する必要がありません）の一覧と、残りの指示に使える、そのまま利用可能なシステムプロンプトを掲載しています。

クイックスタート

Claude Code プラグインとして

1 回のインストールで、エージェントにスキルと MCP サーバーの両方が導入されます。

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

MCP サーバーは uv で取得され、このプラグインが宣言するパッケージバージョンに固定されます。そのため、監査行から、それを書き込んだコードをたどることができます。認証情報は引き続き cicd-aiops init で設定します。詳しくは以下を参照してください。

OpenClaw プラグインとして

同じバンドルは ClawHub でも公開されており、1 回のインストールでスキルと MCP サーバーが一緒に導入されます。

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

その後、プラグインを読み込むために OpenClaw ゲートウェイを再起動してください。MCP サーバーは uv で取得され、このリリースのバージョンに固定されるため、uvx が PATH 上にある必要があります。uvx がない場合、スキルはインストールされますが、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 の実行／ジョブ／ログ）
ランナーフリート（一覧／詳細）	✅	❌ 教育的エラー（API v1 に相当機能なし）
マージ／プルリクエスト、ブランチ、保護、リリース	✅	✅
アーティファクトの一覧	✅（ジョブ経由）	✅（Actions アーティファクト）
retry_pipeline ／ cancel_pipeline	✅	❌ 教育的エラー
pause_runner ／ resume_runner	✅	❌ 教育的エラー
delete_artifacts	✅	❌ 教育的エラー
update_branch_protection	✅	✅

プラットフォームに対応するサーフェスがない場合、プラットフォームレジストリは利用可能なリソースを示す教育的エラーを発生させます。これにより、エージェントは原因不明の 404 に遭遇するのではなく、学習できます。GitLab.com ／ Gitea Cloud の SaaS アカウントは、設計上サポート対象外です。このツールはセルフマネージドインスタンスを対象としています。

主力分析（このツールが存在する理由）

1. pipeline_failure_rca — 最近失敗したパイプラインと、失敗したジョブのトレース末尾を取得し、各失敗を分類します：test-failure / dependency-network / runner-timeout / oom / script-error。各パイプラインについて、一致した証拠、原因、アクションを示します。
2. runner_health_rca — オフライン／古い／一時停止中のランナー（最終接続からの経過時間のしきい値）、しきい値を超えてキューに滞留しているジョブ、タグごとの飽和状態（キュー内のジョブ数とオンラインランナー数）を調べます。
3. artifact_storage_bloat_analysis — リポジトリとアーティファクトの合計バイト数でプロジェクトを順位付けし、期限切れ後も保持されているアーティファクトを特定して、回収可能なバイト数を推定します。この推定値は delete_artifacts --dry-run にそのまま渡せます。
4. stale_work_audit — N 日を超えて更新のないマージ／プルリクエスト、N 日間コミットのないブランチ、保護設定の不備（デフォルトブランチが保護されていない、強制プッシュが許可されている）を調べます。

4 つすべてが透明性のあるヒューリスティックです。しきい値は名前付きパラメーターで指定され、各フラグにはその数値が表示されます。

ガバナンス（組み込み、常時有効）

すべての MCP ツールと CLI の書き込み操作は、cicd_aiops/governance/ に同梱されたハーネスを通ります。記録は行いますが、認可は行いません（上記を参照）。

• 監査 — すべての呼び出し（パラメーター、結果、ステータス、所要時間、リスクティア、オペレーターが指定した承認者／理由）は ~/.cicd-aiops/audit.db に記録されます（CICD_AIOPS_HOME で保存先を変更できます）。CLI は MCP と同じ行を記録するため、監査されないエントリーポイントはありません。
• 暴走防止ガード — 認可ゲートではなく、安全策です。同じ呼び出しが短時間に繰り返されるとサーキットブレーカーが作動し、停止したエージェントが無制限に呼び出しや時間を消費するのを防ぎます。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）を受け付け、サーバーを呼び出すことなく実行内容をプレビューできます。
• サニタイズ — サーバーから返されたすべてのテキストは、エージェントに渡す前にインジェクション対策済みの正規化処理（文字列の長さ制限、深さの上限）を通ります。すべてのパスパラメーターはパーセントエンコードされるため、識別子によって URL が書き換えられることはありません。

シークレット

トークンは ~/.cicd-aiops/secrets.enc に保存されます。Fernet で暗号化され、マスターパスワードから scrypt で鍵が導出されます。ディスク上に平文で保存されることはありません。非対話型／MCP で使用する場合は CICD_AIOPS_MASTER_PASSWORD を設定し、cicd-aiops secret set|list|remove|migrate で管理してください。TLS 検証はデフォルトで有効です（初期設定ウィザードでは、ラボ用証明書のために無効にする前に確認されます）。

MCP サーバー

ガバナンスが適用された 26 個のツール（読み取り 20 個（主要な 4 つの分析を含む）、書き込み 6 個）を提供します。

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

環境ブロックに関する注意：MCP クライアントは、最小限の環境変数でサーバーを起動するため、シェルプロファイルは読み込まれません。サーバーが必要とする環境変数（CICD_AIOPS_MASTER_PASSWORD、CICD_AIOPS_HOME、および任意の監査注釈 CICD_AUDIT_APPROVED_BY）は、~/.zshrc ではなく、上記の env ブロックに設定する必要があります。

別の方法として、cicd-aiops mcp を実行できます（同じサーバーを起動する CLI エントリーポイントです）。

設定

~/.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 .

機能が足りない場合

必要な機能が不足している場合は、issue／PR を歓迎します。必要な GitLab／Gitea の機能（新しい Gitea での Runner 管理、ジョブごとの再試行、スケジュール済みパイプライン、グループレベルの集計など）が不足している場合は、https://github.com/AIops-tools/CICD-AIops で issue または PR を作成してください。プラットフォームレジストリは、新しいリソースをリファクタリングではなく、パスマップのエントリー 1 つで追加できるように設計されています。

ライセンス

MIT。GitLab は GitLab Inc. の商標であり、Gitea はそのプロジェクト所有者の商標です。このプロジェクトは独立しており、いずれとも提携していません。