GitHub Actions Visualizerのイメージ

YAMLの森で迷子になるエンジニアたち

CI/CD（継続的インテグレーション）が当たり前になった今の時代、皆さんのプロジェクトの workflow.yml は何行くらいありますか？

最初は「Lintしてテストしてビルドするだけ！」みたいな可愛いものだったのに、プロダクトが育つにつれて「E2EテストがコケたらSlackに通知する」「特定のブランチだけデプロイスキップ」みたいな要件が継ぎ足されていき……気づけば数百行の怪物YAMLが出来上がっていませんか？

  build:
    needs: [test-frontend, test-backend, check-format]
  deploy:
    needs: [build, security-scan]

こんなコードをGitHubの黒い画面でぼーっと眺めていると、「結局、テストが終わるまでフロントのビルドって待たされてるんだっけ？」と、自分の書いたコードなのに迷子になってしまうことが何度もありました。人間の脳は、テキストの羅列から複雑なネットワーク構造を読み取るようにはできていないんです。

「見えない繋がり」を線で結びたい

「頭の中でツリー構造を思い描くの、もう限界だ。全部フローチャートにして見たい」

そう思って作り始めたのが、この可視化ツールです。
YAMLを丸ごとペーストすると、裏側でJavaScriptが needs: パラメータをすかさず拾い上げて、自動的にジョブの親子関係をMermaidの美しいグラフにしてくれる、という仕組みです。

作ってみて一番面白かったのは、エラーハンドリングの部分です。
YAMLってインデントが1スペースずれただけでパースエラーになる悪魔のような仕様なんですが、ただ「エラーです」って出すだけだと腹が立ちますよね（笑）。だから、どこでインデントが死んでいるのか、なるべく分かりやすく画面上に怒りのエラーメッセージを出せるように工夫しました。

今では、新しくチームに入ってきたメンバーに「うちのCIこうなってるよ」と説明する用のドキュメントとしても重宝しています。YAML地獄で発狂しそうになったら、ぜひ一度コードを流し込んでみてください。「あ、意外と綺麗な形してたんだな」って安心できるかもしれません。

実際に助かった場面

あるワークフローでは、deploy が build にだけ依存していて、security-scan が独立したまま走っていました。YAML上では近くに書かれていたので見落としていましたが、図にすると security-scan から deploy へ線が伸びていないことが一目で分かりました。

deploy:
  needs: [build]

この場合、修正後は needs: [build, security-scan] に変更し、セキュリティチェックが終わってからデプロイされるようにしました。単に図を眺めるためのツールではなく、「このジョブは本当にデプロイ条件に入っているか」を確認するレビュー道具として使えるのが大きな価値です。

図にすると、レビューの会話が変わる

テキストのYAMLをレビューしていると、コメントはどうしても「ここのインデントが」「この needs の配列が」みたいな、細かい構文の話になりがちです。でも図にして見せると、会話の粒度が一段上がります。「このセキュリティスキャン、デプロイの前提に入ってなくない？」という、設計そのものへの指摘が自然に出てくるんです。

新しくチームに入った人に「うちのCIどうなってるの？」と聞かれたときも、数百行のYAMLを一緒にスクロールするより、1枚のフローチャートを見せたほうが圧倒的に早い。図は、コードを書く道具であると同時に、人に説明するための共通言語にもなります。CIが複雑になってきたな、と感じたら、まず全体像を絵にしてみるのがおすすめです。

よくある質問

貼り付けた workflow YAML は外部に送信されますか？

いいえ。YAMLの解析と図の生成はすべてブラウザ内で完結します。社内のCI/CD定義やジョブ名、デプロイ先の情報が含まれていても、外部のサーバーへ送られることはありません。

needs の依存はどんな図になりますか？

needs: を拾って、ジョブ同士の親子関係を矢印付きのグラフにします。どこが直列で、どこが並列で動くのか、依存の指定漏れがないかが一目で分かります。YAMLを上から読むより、見落としが減ります。

生成した図はGitHubに貼れますか？

はい。出力されるMermaidコードをコピーすれば、READMEやドキュメントにそのまま貼れます。新しいメンバーへCI構成を説明する資料としても使えます。

YAMLがエラーで図が出ないときはどうすればいいですか？

多くはインデントのズレが原因です。YAMLはスペース1つで構造が変わるので、ジョブのネストが揃っているか、タブではなくスペースで字下げしているかを確認してください。エラーメッセージで示された箇所の周辺から見直すと早いです。