GitHub Actionsの「複雑さ」という課題

CI/CDを自動化するGitHub Actionsは強力ですが、プロジェクトが成長するにつれてワークフロー(YAMLファイル)は肥大化しがちです。「どのジョブの後にどのジョブが動くのか」を数百行のコードから読み解くのは、想像以上に時間がかかります。

GitHub Actions可視化ツール は、ワークフローYAMLを貼り付けるだけでジョブの依存関係をMermaid形式のグラフとして描画します。処理はブラウザ内で完結し、秘匿性の高いワークフロー定義を外部に送信することはありません。

GitHub Actions ワークフローの可視化:複雑なパイプラインを正しく理解する

needsを図に変換する仕組み

可視化の元になるのは、各ジョブの needs フィールドです。YAML上でジョブごとに散らばって書かれている依存関係を、jobs を走査しながらMermaidの矢印に変換します。

jobs:
  lint:
    runs-on: ubuntu-latest
  test:
    needs: lint
  build:
    needs: lint
  deploy:
    needs: [test, build]
graph TD
    lint["lint"]
    test["test"]
    lint --> test
    build["build"]
    lint --> build
    deploy["deploy"]
    test --> deploy
    build --> deploy

lintがボトルネックで、testとbuildは並列、deployが合流点——というパイプラインの形が一目で分かります。

needsは文字列でも配列でも書ける

GitHub Actionsの仕様上、needs は単一ジョブなら文字列、複数ジョブなら配列のどちらでも書けます。

needs: lint            # 文字列でもよい
needs: [lint, test]    # 配列でもよい

可視化ツールはどちらの表記でも正しく矢印を生成しますが、自分でワークフローを書く際にこの表記揺れを知っておくと、YAMLを読むときに戸惑いません。

よくあるパイプライン構成のパターン

ワークフローを図にすると、実は数パターンの組み合わせでできていることが見えてきます。

  • ファンアウト(並列展開): build の後に test lint security-scan が同時に走る形。CI時間を短縮したいときの基本形
  • ファンイン(集約): 複数のジョブが完了してから deploy に集約する形。needs: [build, test, lint] のように複数指定する
  • マトリックス: strategy.matrix で同じジョブを複数バージョン・OSに展開する形。図では1ノードでも、実体は複数ジョブが並列で動く

図にしたときに「並列のはずが直列になっている」「集約すべき品質チェックが deploy の needs に入っていない」といったズレが見つかれば、それがパイプライン改善の起点になります。CI時間を縮める具体的な書き換えパターンは GitHub Actions needs設計パターン集 にまとめています。

レビューで見る具体例

次のような構成では、deploy が test だけに依存しているため、lint が失敗してもデプロイへ進む可能性があります。

jobs:
  lint:
    runs-on: ubuntu-latest
  test:
    runs-on: ubuntu-latest
  deploy:
    needs: [test]
    runs-on: ubuntu-latest

図にすると lint だけが独立して見えるため、「品質チェックをデプロイ条件に含めるべきか」を議論しやすくなります。deploy の needs を [lint, test] にするだけでよいのか、build ジョブを追加して成果物を共有するのか、といった設計判断にもつなげられます。

循環依存はGitHub Actions自体がエラーにする

needs がループ(AがBに、BがAに依存)していると、GitHub Actionsはワークフローを実行できずエラーになります。数百行のYAMLでは循環を見つけにくいため、まず可視化して依存の流れを目で追うのが実務的な近道です。

詳細表示で runs-on・if・matrix を図に載せる

GitHub Actions可視化ツールの「詳細も表示」にチェックを入れると、ジョブの箱に次の情報が書き足されます。チェックを外せば、従来どおりジョブ名だけの図に戻ります。

test      → test / runs-on: ubuntu-latest / matrix: 6 (+1 include)
deploy    → deploy / runs-on: self-hosted, linux / if: github.ref == 'refs/heads/main' / environment: production
call      → call / uses: ci.yml@v1
  • runs-on: 文字列でも配列([self-hosted, linux])でも書き足します
  • matrix: 配列どうしの組み合わせ数です。include で増える分は +N include と別に書きます。${{ fromJson(…) }} のような式のときは数えられないので (dynamic) と表示します
  • if: 条件の ${{ }} を外して書き足し、そのジョブの枠を破線にします。いつも動くとは限らないジョブが、一目で分かります
  • uses / environment: 再利用ワークフローを呼ぶジョブは uses(ファイル名とタグ)、デプロイ先があるジョブは environment を書き足します
  • 長い条件は60文字で切り詰め、< > " & は Mermaid の構文を壊さないよう実体参照にします

高機能 SVG で、ジョブの関係を動かしながら読む

依存関係は、Mermaid の図としてだけでなく、**自前の「高機能 SVG」**でも描けます(表示方式の初期値です。Mermaid の表示と、Mermaid コードのコピーも、これまでどおり使えます)。

  • ステージを左から右へ: needs の深さごとに列を作り、同じ深さのジョブを縦に並べます。ステージごとの枠(Stage 2 · 3 のような見出し付き)と、ジョブの種類のアイコン(再利用・マトリクス・デプロイ)も付けられます
  • 最長の連なりを強調: クリティカルパスを橙の太い線で示し、その連なりの timeout-minutes の合計も出します(timeout を書いていないジョブの数つき)
  • マトリクスは重ねた箱、needs.<job>.outputs を使っている依存は、線に「outputs」と書きます
  • ジョブの箱をクリックすると、runs-on・ステップ名・依存先が出ます。箱に重ねる(キーボードならフォーカスする)と、そのジョブの上流と下流の線だけが残ります
  • ドラッグで並べ替え: 箱をドラッグ(またはフォーカスして矢印キー)で動かせます。動かしている間は、ステージの枠を隠します
  • 図は幅に合わせて縮小でき、拡大・縮小、SVG と PNG での保存もできます

入力した YAML と表示のオプション、動かした位置は、このブラウザの中に自動で保存されます。次に開いたときも続きから使え、保存した内容は消す・JSON で書き出す・読み込むこともできます。サーバーには送りません。

よくある質問

needs を指定しないジョブはどう動きますか?

needs を持たないジョブは、ワークフロー開始と同時に並列で実行されます。順番を制御したい場合は needs: [job-id] で依存先を明示します。図にすると、独立して走るジョブと直列のジョブの境界が一目でわかります。

依存関係が循環しているとどうなりますか?

needs がループしていると、GitHub Actionsはワークフローを実行できずエラーになります。数百行のYAMLでは循環を見つけにくいため、DAG(有向非巡回グラフ)として可視化して確認するのが有効です。

ワークフローYAMLを外部ツールに貼っても安全ですか?

ワークフローにはシークレット名やデプロイ先などの情報が含まれることがあります。GitHub Actions可視化ツールはブラウザ内で処理が完結し、YAMLをサーバーへ送信しないため、こうしたファイルでも安全に図示できます。

マトリックスビルドはどう表示されますか?

strategy.matrix で複数の組み合わせに展開されるジョブは、定義上は1つのジョブのため、図でも1つのノードとして表示されます。実行時には組み合わせの数だけ並列にジョブが走る点を念頭に置いてください。依存関係(needs)の流れを把握する目的なら、1ノードで表現されていても十分に役立ちます。

まとめ

  • 可視化は各ジョブの needs をMermaidの矢印に変換しているだけ。仕組みはシンプル
  • needs は文字列/配列どちらの表記も許容される
  • 図にすると「無駄な直列化」「意図しない並列」「循環依存」が見つかる
  • CI高速化のための具体的なパターンは別記事の設計パターン集を参照

複雑なジョブ構成でエラーが出た際は、まず図にして実行の順番を再確認するのがおすすめです。