ci-debugger — GitHub Actions ワークフローのローカルデバッグツール

DevOps
ci-debugger — GitHub Actions ワークフローのローカルデバッグツール

ci-debugger — GitHub Actions ワークフローのローカルデバッグツール

GitHub Actions のワークフローをローカルでステップ実行・ブレークポイント付きでデバッグするためのツールです。何度もコミットしては失敗ログを読み解くループを断ち切り、YAML で定義したジョブやステップをそのままローカルで再現・中断・検査できます。Go 製の軽量バイナリとして提供され、goreleaser や Makefile を用いたビルド/配布が想定されています。デバッグ体験を改善し、CI フローの開発サイクルを高速化します。

https://github.com/murataslan1/ci-debugger

概要

ci-debugger は「GitHub Actions ワークフローをローカルでデバッグできる」ことを目的としたツールです。特にブレークポイント機能に注力しており、既存ツール（例: act）が提供するローカル実行機能に対して「途中で停止して状態を調べる」というデバッグ体験を追加します。YAML を編集して何度もコミットする従来のサイクルを減らし、ステップ単位での停止・シェル起動・環境確認を通じて原因特定を速めます。Go 言語で実装され、軽量バイナリとして配布される設計です。

GitHub

リポジトリの統計情報

  • スター数: 5
  • フォーク数: 0
  • ウォッチャー数: 5
  • コミット数: 3
  • ファイル数: 14
  • メインの言語: Go

主な特徴

  • ブレークポイントによるステップ単位の停止とインタラクティブデバッグ
  • ローカル実行で快速なフィードバックループを実現（push を待たない）
  • Go 製の単一バイナリ、goreleaser/Makefile による配布とビルド定義
  • ワークフローの状態確認（環境変数・ファイルシステム・コマンド出力）の簡易的な参照

技術的なポイント

ci-debugger の技術的なコアは「ワークフロー定義の解釈」と「実行中の制御」にあります。まず YAML（.github/workflows/*.yml）を解析してジョブとステップの実行順序を再構築し、各ステップをローカル環境で再現可能な形に変換します。特に注目すべきはブレークポイント実装で、指定したステップに到達した際にそのステップの実行を中断し、ユーザーにシェルや REPL ライクな対話を提供して環境やファイル、環境変数を直接確認・操作できる点です。

このアプローチによりエラー発生箇所の前後で状態を観察でき、単純なログ出力では見えない問題（環境変数の欠落、ファイルパスの誤り、コマンドの依存関係など）を迅速に特定できます。実行基盤はホスト上のプロセス実行やコンテナ実行を選べる設計が想定され、Go で書かれているため依存が少なく配布が容易です。ビルドとリリースは .goreleaser.yml と Makefile が整備されており、クロスコンパイルやリリースアーティファクト生成が自動化される想定です。ログやデモ GIF（assets/demo.gif）が付属し、CLI は直感的なコマンド（例: ci-debugger run —step）を提供しています。既存ツールとの違いは「単に実行する」ではなく「途中で止めて中を覗ける」点にあり、CI の開発サイクル短縮に直接寄与します。

プロジェクトの構成

主要なファイルとディレクトリ：

  • .github: dir
  • .gitignore: file
  • .goreleaser.yml: file
  • LICENSE: file
  • Makefile: file
  • README.md: file（使い方・デモ GIF を含む）
  • assets/: dir（demo.gif 等のデモ資産）
  • go.mod / go.sum: file（Go モジュール管理）
  • main.go / cmd/（CLI エントリーポイントやフラグ処理を含む可能性高）
  • その他の実装ファイルやユーティリティファイル

リポジトリは比較的軽量で、ビルド・リリースの設定が整っている点が特徴です。CLI 実行部分（run コマンドや —step オプション）は README に例示されており、ユーザーはローカルで即座に試せる設計になっています。Go モジュールを使った依存管理と goreleaser を使った配布フローが確認できるため、CI/CD に組み込んだ配布も想定可能です。

まとめ

ワークフローの問題箇所を直接覗けるブレークポイントで、CI デバッグを効率化する実用的なツールです。

リポジトリ情報：

READMEの抜粋：

ci-debugger

Debug GitHub Actions workflows locally — with breakpoints.

You shouldn’t have to push 47 commits to figure out why your CI is failing.

ci-debugger demo

ci-debugger run --step

The Problem

Every developer knows the loop:

  1. Write some YAML
  2. Push to GitHub
  3. Wait 5 minutes
  4. See a cryptic error
  5. Repeat

Existing tools like act help run workflows locally, but they’re missing the one thing that makes debugging actually useful: **t…