【実務・中級編】GitHub Actionsの「Job Summaries」でカスタムMarkdownレポートを動的に作成する方法 – バージョン管理・CI/CD活用バイブル

【GitHub Actions】Job SummariesでCI/CDレポートを極限までリッチ化し、チームの開発スピードを爆上げする方法

テックリードの私たちが日々の開発で最もストレスに感じる瞬間の一つは、「なぜ今回のCIが失敗したのか」「今回のデプロイにはどの変更とどのバージョンが含まれているのか」を把握するために、数千行の長大なログの海をさまようことだ。

GitHub Actionsの標準UIは優れているが、コンソールログは本質的に「流し読みするもの」であり、経営層、QA、他の開発メンバーがサクッと状況を把握するには向いていない。

そこで活用すべきなのが `$GITHUB_STEP_SUMMARY` である。
これを使えば、任意のMarkdownをワークフローの実行完了後にリポジトリのPRやアクション詳細画面の「Summary（サマリー）」タブに美しくレンダリングできる。

今回は、単なる「文字の出力」にとどまらず、テストカバレッジ、脆弱性スキャン結果、デプロイ先URLを構造化し、チームの誰もが1秒でCIの結果を理解できる「究極のダッシュボード」を動的に構築するプロの実践テクニックを伝授しよう。

—

1. Job Summaries の基本思想と仕組み

仕組みは極めてシンプルだ。環境変数 `$GITHUB_STEP_SUMMARY` にパスが格納されているファイルに対して、標準出力やファイル書き込みでMarkdownを追記するだけである。

echo “

🚀 デプロイが完了しました” >> $GITHUB_STEP_SUMMARY

これだけで、GitHub側がよしなにパースしてリッチなUIに変換してくれる。
しかし、現場のCIでこれを実用レベルに引き上げるには、以下の3つの設計原則を守る必要がある。

1. 可読性のサイエンス: テーブル、絵文字、折りたたみ（`

`）を駆使し、情報密度を保ちつつノイズを削る。
2. 失敗時のアピール: テスト失敗やセキュリティ脆弱性検知時は、視覚的に即座に気づける警告カラーやバッジを配置する。
3. トレーサビリティの確保: コミットハッシュ、ブランチ、デプロイ先URLをワンクリックでアクセスできるようにする。

—

2. 実践：最強のカスタムMarkdownレポートを生成するワークフロー

以下のYAMLは、テスト実行、カバレッジ測定、脆弱性スキャン、そしてそれらの結果を統合してJob Summaryに流し込む、プロダクション品質の完全なワークフローのベストプラクティス構成例だ。

name: Production-Grade CI & Summary Report

on:
pull_request:
branches: [ main ]
push:
branches: [ main ]

jobs:
build-and-test:
name: Build, Test & Report
runs-on: ubuntu-latest

permissions:
contents: read
pull-requests: write

steps:

name: 📥 Checkout Repository

uses: actions/checkout@v4

name: ⎔ Set up Node.js

uses: actions/setup-node@v4
with:
node-version: ’20’
cache: ‘npm’

name: 📦 Install Dependencies

run: npm ci

name: 🧪 Run Tests & Generate Coverage

id: run_tests
run: |
# テストを実行し、JSON形式のカバレッジとサマリーを出力する想定
npm run test:ci — –coverage –reporter=json-summary || true

# ステータスを保持しておく
echo “test_status=$?” >> $GITHUB_OUTPUT

name: 🔒 Run Security Audit

id: security_audit
run: |
npm audit –json > audit-results.json || true
# 脆弱性の数を抽出（jqを使用）
HIGH_VULNS=$(jq ‘.metadata.vulnerabilities.high + .metadata.vulnerabilities.critical’ audit-results.json)
echo “high_vulns=$HIGH_VULNS” >> $GITHUB_OUTPUT

name: 📊 Generate Dynamic Job Summary

if: always() # テストが失敗しても必ずサマリーを生成する
run: |
# ==========================================
# 1. ヘッダーとメタ情報の出力
# ==========================================
echo “# 🛠️ CI/CD 実行レポート” >> $GITHUB_STEP_SUMMARY
echo “” >> $GITHUB_STEP_SUMMARY
echo “| 項目 | ステータス / 詳細 |” >> $GITHUB_STEP_SUMMARY
echo “| :— | :— |” >> $GITHUB_STEP_SUMMARY
echo “| トリガー | \`${{ github.event_name }}\` |” >> $GITHUB_STEP_SUMMARY
echo “| コミット | [\`${{ github.sha }}\](https://github.com/${{ github.repository }}/commit/${{ github.sha }}) |” >> $GITHUB_STEP_SUMMARY
echo “| ブランチ | \`${{ github.ref_name }}\` |” >> $GITHUB_STEP_SUMMARY
echo “| 実行者 | @${{ github.actor }} |” >> $GITHUB_STEP_SUMMARY
echo “” >> $GITHUB_STEP_SUMMARY

# ==========================================
# 2. テスト結果セクション
# ==========================================
echo “

🧪 テスト & カバレッジ結果” >> $GITHUB_STEP_SUMMARY

if [ “${{ steps.run_tests.outputs.test_status }}” = “0” ]; then
echo “> ✅ テスト成功: すべてのテストケースを通過しました。” >> $GITHUB_STEP_SUMMARY
else
echo “> ❌ テスト失敗: 一部のテストが失敗しています。ログを確認してください。” >> $GITHUB_STEP_SUMMARY
fi
echo “” >> $GITHUB_STEP_SUMMARY

# カバレッジサマリーの埋め込み（JestのJSON出力等をパースする例）
if [ -f “coverage/coverage-summary.json” ]; then
PCT_LINES=$(jq ‘.total.lines.pct’ coverage/coverage-summary.json)
PCT_FUNC=$(jq ‘.total.functions.pct’ coverage/coverage-summary.json)
echo “

カバレッジメトリクス” >> $GITHUB_STEP_SUMMARY

echo “- 📏 ラインカバレッジ: ${PCT_LINES}%” >> $GITHUB_STEP_SUMMARY
echo “- ギア関数カバレッジ: ${PCT_FUNC}%” >> $GITHUB_STEP_SUMMARY
fi
echo “” >> $GITHUB_STEP_SUMMARY

# ==========================================
# 3. セキュリティ監査セクション
# ==========================================
echo “

🛡️ セキュリティ監査” >> $GITHUB_STEP_SUMMARY

HIGH_VULNS=”${{ steps.security_audit.outputs.high_vulns }}”

if [ “$HIGH_VULNS” -eq “0” ]; then
echo “🟢 深刻な脆弱性 (High/Critical) は検出されませんでした。” >> $GITHUB_STEP_SUMMARY
else
echo “🔴 警告: 深刻な脆弱性が ${HIGH_VULNS}件 検出されました！早急な対応が必要です。” >> $GITHUB_STEP_SUMMARY
fi

# ==========================================
# 4. デプロイプレビューリンク（PRの場合）
# ==========================================
if [ “${{ github.event_name }}” = “pull_request” ]; then
echo “” >> $GITHUB_STEP_SUMMARY
echo “—” >> $GITHUB_STEP_SUMMARY
echo “🌐 プレビュー環境: 準備中（デプロイ完了後にここにURLが追加されます）” >> $GITHUB_STEP_SUMMARY
fi

—

3. プロの技：Node.jsやPythonスクリプトでリッチなHTML/Markdownを構築する

Bashの `echo` 連打は、複雑なテーブルや条件分岐が増えてくるとメンテナンス地獄になる。
大規模プロジェクトやチーム共有のアクション（Composite Actions）を作る場合は、専用のスクリプト（Node.jsやPython）をステップから呼び出す手法を強く推奨する。

ここでは、Node.jsを使って型安全かつエレガントにサマリーを生成するアプローチを紹介する。

スクリプト例: `.github/workflows/scripts/generate-summary.mjs`

import fs from ‘fs’;
import path from ‘path’;

async function run() {
const summaryFile = process.env.GITHUB_STEP_SUMMARY;
if (!summaryFile) {
console.warn(‘GITHUB_STEP_SUMMARY environment variable is not found.’);
return;
}

// 外部から渡されたJSONデータなどを読み込む想定
const testResults = {
total: 120,
passed: 118,
failed: 2,
duration: ‘14.2s’
};

const markdown = [];

markdown.push(‘# 🎯 拡張CI/CD 解析ダッシュボード’);
markdown.push(`> 🕒 実行日時: \`${new Date().toISOString()}\“);
markdown.push(”);

// 2カラムレイアウト風のテーブル
markdown.push(‘| メトリクス | 値 |’);
markdown.push(‘| :— | :— |’);
markdown.push(`| 総テスト数 | ${testResults.total} |`);
markdown.push(`| 成功 | 🟢 ${testResults.passed} |`);
markdown.push(`| 失敗 | 🔴 ${testResults.failed} |`);
markdown.push(`| 実行時間 | ⏱️ ${testResults.duration} |`);
markdown.push(”);

// 折りたたみ要素（Details）を活用した詳細ログの格納
if (testResults.failed > 0) {
markdown.push(‘

‘);
markdown.push(‘

🔍 失敗したテストの詳細（クリックして展開）

‘);
markdown.push(”);
markdown.push(”);
markdown.push(‘FAIL: src/components/__tests__/Button.test.tsx’);
markdown.push(‘ – should handle click event properly’);
markdown.push(‘FAIL: src/utils/__tests__/auth.test.ts’);
markdown.push(‘ – should expire token correctly’);
markdown.push(”);
markdown.push(”);
markdown.push(‘

‘);
}

// ファイルへ書き込み
fs.writeFileSync(summaryFile, markdown.join(‘\n’), { flag: ‘a’ });
}

run().catch(err => {
console.error(err);
process.exit(1);
});

このスクリプトをワークフローから呼び出すだけで、保守性が劇的に向上する。

name: 📝 Generate Advanced Summary with Node.js

if: always()
run: node .github/workflows/scripts/generate-summary.mjs

—

4. チーム開発を加速させる「神テクニック」と共有化ルール

1. `if: always()` を制する者はJob Summariesを制する

テストやビルドが途中でコケた（failure）場合、デフォルトではその後のステップはスキップされる。しかし、「失敗した理由」こそサマリーに出力したい。
そのため、サマリー生成ステップには必ず `if: always()` を付与し、前のステップの成否を変数や `steps..conclusion` で取得してMarkdownのトーン（成功/失敗）を切り替えよ。

2. PRコメントへの自動クロスポスト

Job SummariesはGitHubのUI上で非常に見やすいが、メンバーがPRをレビューする際に見落とされがちだ。
もしPRに対して直接このサマリー内容を同期させたい場合は、OSSの神アクション `actions/github-script` や専用のサマリー転記アクションを組み合わせることで、「PRのコメント欄にも同じレポートを自動投稿する」ことが可能だ。

name: 💬 Post Summary to PR Comment

if: github.event_name == ‘pull_request’
uses: marocchino/sticky-pull-request-comment@v2
with:
path: ${{ env.GITHUB_STEP_SUMMARY }} # または生成したMarkdownファイルを指定

—

まとめ：CIを「ただの関所」から「チームの羅針盤」へ

CI/CDパイプラインは、コードをビルドしてテストするだけの冷たい自動機械ではない。チーム全体の開発フィードバックループを高速化するための最強のコミュニケーターであるべきだ。

今回紹介した Job Summaries によるカスタムレポート構築を取り入れれば：

ログの海から解放され、3秒でCIの結果が全貌把握できる
カバレッジやセキュリティリスクが視覚化され、品質の意識がチーム全体で自然と高まる
トラブルシューティングの初動スピードが圧倒的に早くなる

明日からのあなたのパイプラインに、さっそくこの「美しく実用的なサマリー」を組み込んでみてほしい。チームの生産性が一段上のステージへと引き上げられることを、私が保証しよう。