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] に変更し、セキュリティチェックが終わってからデプロイされるようにしました。単に図を眺めるためのツールではなく、「このジョブは本当にデプロイ条件に入っているか」を確認するレビュー道具として使えるのが大きな価値です。