メインコンテンツへスキップ
見出し画像

【GitHub Actions 初心者向け】Job Summary と PRコメント

    はじめに

    GitHub Actions の CI 結果を、毎回ログを開いて確認するのは面倒です。この記事では、実行結果のサマリを見やすい場所に自動表示する2つのアプローチを、コピペで動く最小サンプル付きで紹介します。

    • Job Summary:Actions の実行ページに Markdown で結果を表示する

    画像
    Job Summaryイメージ
    • PRコメント:Pull Request のコメント欄に自動で結果を投稿する

    画像
    PRコメントイメージ

    想定するプロジェクトは Node.js(Vitest / ESLint / TypeScript)ですが、他の言語でも考え方はそのまま使えます。細かなオプションや応用は本記事では踏み込まないので、詳しく知りたい場合は各ツールのドキュメントを参照してください。


    Job Summary

    まずは Job Summary から始めます。追加の action が不要で、特別な権限設定も不要なので、いちばん導入コストが低い方法です。

    GitHub Actions のランナーには $GITHUB_STEP_SUMMARY という環境変数が用意されていて、この変数が指すファイルに Markdown を書き込むと、Actions の実行ページに描画されます。echo や cat で追記するだけなので、シェルスクリプトが書ければすぐに使えます。

    最小の設定サンプル

    .github/workflows/ci.yml に次のようなステップを1つ追加するだけです。

    name: CI
    
    on:
      pull_request:
        branches: [main]
    
    jobs:
      test:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
    
          - name: Write summary
            run: |
              echo "## テスト結果" >> "$GITHUB_STEP_SUMMARY"
              echo "" >> "$GITHUB_STEP_SUMMARY"
              echo "- passed: 42" >> "$GITHUB_STEP_SUMMARY"
              echo "- failed: 0" >> "$GITHUB_STEP_SUMMARY"
    

    これを push すると、Actions の実行ページに「テスト結果」という見出しと箇条書きが表示されます。

    ここからは、実際のプロジェクトで出したくなる情報別にサブ章として書き分けていきます。

    テスト結果を Job Summary に出す

    test-summary/action を使うと、JUnit XML 形式のテスト結果ファイルを Job Summary に整形してくれます。

    まず Vitest 側で JUnit 形式の出力を有効にします。Vitest はテスト実行時に outputFile.junit で指定したパスへ自動的に JUnit XML を出力するので、npm run test:unit を叩くだけで XML が生成されます。

    // vitest.config.ts
    import { defineConfig } from 'vitest/config'
    
    export default defineConfig({
      test: {
        reporters: ['default', 'junit'],
        outputFile: {
          junit: './test-results/junit.xml',
        },
      },
    })

    ワークフローには次のステップを追加します。

          - name: Run tests
            id: unit
            continue-on-error: true
            run: npm run test:unit
    
          - name: Test summary
            if: always()      # 失敗時もサマリを出したいので always()
            uses: test-summary/action@v2
            with:
              paths: "test-results/junit.xml"
              show: "fail, skip"

    show: "fail, skip" は失敗・スキップだけを詳細表示するオプションです。全件表示にしたい場合は show: "all" に変更してください。

    カバレッジを Job Summary に出す

    irongut/CodeCoverageSummary は Cobertura 形式のカバレッジを解析して、パッケージ別の表として Job Summary に出してくれます。

    Vitest 側でカバレッジを有効にします(@vitest/coverage-v8 の追加インストールが必要です)。

    // vitest.config.ts
    export default defineConfig({
      test: {
        coverage: {
          provider: 'v8',
          reporter: ['text', 'cobertura'],  // cobertura が必須
          reportsDirectory: './coverage',
        },
      },
    })
    

    ワークフローに次のステップを追加します。

          - name: Run tests with coverage
            run: npm run test:unit -- --coverage
    
          - name: Coverage summary
            if: always()
            uses: irongut/CodeCoverageSummary@v1.3.0
            with:
              filename: "coverage/cobertura-coverage.xml"
              format: markdown
              output: file
    
          - name: Append coverage to Job Summary
            if: always()
            run: cat code-coverage-results.md >> "$GITHUB_STEP_SUMMARY"
    

    これでパッケージ別の Line Rate / Branch Rate などが並んだ表が Job Summary に表示されます。

    Lint / TypeCheck の結果を Job Summary に出す

    Lint と TypeCheck は「どこで引っかかったのか」まで Job Summary に出しておくと、ログをスクロールせずに済みます。基本パターンは共通で、出力をファイルに保存してコードブロックとして貼るだけです。

    Lint(ESLint)

          - name: Lint
            id: lint
            continue-on-error: true
            run: npm run lint > lint-output.txt 2>&1
    
          - name: Lint summary
            if: always()
            run: |
              {
                echo "## Lint Results"
                if [ "${{ steps.lint.outcome }}" = "failure" ]; then
                  echo '```'
                  cat lint-output.txt
                  echo '```'
                else
                  echo "✅ No lint errors."
                fi
              } >> "$GITHUB_STEP_SUMMARY"
    

    TypeCheck

          - name: Type check
            id: typecheck
            continue-on-error: true
            run: npm run typecheck > typecheck-output.txt 2>&1
    
          - name: Type check summary
            if: always()
            run: |
              {
                echo "## Type Check Results"
                if [ "${{ steps.typecheck.outcome }}" = "failure" ]; then
                  echo '```'
                  cat typecheck-output.txt
                  echo '```'
                else
                  echo "✅ No type errors."
                fi
              } >> "$GITHUB_STEP_SUMMARY"
    

    どちらも continue-on-error: true を付けて後続に進めるようにし、サマリ側は if: always() で必ず実行させています。

    4つのステップを1ジョブにまとめるときの仕上げ

    Lint / TypeCheck / Test / Coverage のステップを1つのジョブに順に並べれば、Actions のページに順にサマリが並びます。仕上げに、continue-on-error: true で握りつぶした失敗を顕在化させるステップを最後に置いておくと、失敗があるのにジョブが緑になる事故を防げます。

          - name: Fail job if any step failed
            if: |
              steps.lint.outcome == 'failure' ||
              steps.typecheck.outcome == 'failure' ||
              steps.unit.outcome == 'failure'
            run: exit 1
    

    注意点

    Job Summary には 1ジョブあたり最大 1MiB の上限があり、その job の 1 回の実行分しか表示されません。「大量ログを丸ごと流し込む」「履歴を残す」用途には向かない、と押さえておけば十分です。


    PRコメント

    Job Summary は便利ですが、「実行ページを開かないと見えない」という弱点があります。レビュアーの目に確実に触れさせたいときは、PR コメントとして投稿する方が確実です。

    PR コメント投稿にはいくつかやり方がありますが、初心者にまずおすすめなのが marocchino/sticky-pull-request-comment です。同じコメントを更新してくれる(sticky = 貼りっぱなし)ので、CI を再実行するたびにコメントが増えることがありません。

    最小の設定サンプル

    以下は on: pull_request トリガーを前提としたサンプルです(push トリガーで動かす場合は、PR 番号を取得して number: 入力で明示的に渡す必要があります)。marocchino/sticky-pull-request-comment を使う最小構成は次の2ステップで、テスト実行結果を GITHUB_OUTPUT に流し込み、それをコメントとして貼る流れです。ワークフローの permissions: に pull-requests: write を付けておく点だけ忘れなければ、これだけで動きます。

    permissions:
      pull-requests: write
      contents: read
          - name: Run tests
            id: test
            run: |
              # 実際のテストコマンドの結果を GITHUB_OUTPUT に格納する例
              echo "result<<EOF" >> "$GITHUB_OUTPUT"
              npm test 2>&1 | tail -20 >> "$GITHUB_OUTPUT"
              echo "EOF" >> "$GITHUB_OUTPUT"
    
          - name: Comment on PR
            uses: marocchino/sticky-pull-request-comment@v3
            with:
              header: test-summary
              message: |
                ## ✅ テスト結果
                ```
                ${{ steps.test.outputs.result }}
                ```

    ポイントは header: test-summary の部分です。この文字列を「コメントを識別するキー」として使い、次回以降の実行では同じ header のコメントを見つけて上書きします。これによって PR にコメントが積み重ならず、常に最新の結果だけが見える状態になります。

    header を使い分けて複数のコメントを並べる

    header の値を変えれば、1つの PR に複数の sticky コメントを共存させられます。たとえば「テスト結果用」と「デプロイ URL 用」を別々に更新できます。

          - name: Post test summary
            uses: marocchino/sticky-pull-request-comment@v3
            with:
              header: test-summary       # ← テスト結果用のキー
              message: |
                ## ✅ テスト結果 …
    
          - name: Post deploy URL
            uses: marocchino/sticky-pull-request-comment@v3
            with:
              header: deploy-url         # ← デプロイURL用のキー
              message: |
                ## 🚀 プレビュー環境
                <https://preview-${{ github.event.pull_request.number }}.example.com>
    

    Job Summary と PRコメントの使い分け

    役割を分けて併用すると使い勝手が良くなります。

    • PRコメント:レビュアーに見せたい要点(合否・件数)だけを載せる

    • Job Summary:詳細(失敗したテスト名・Lint エラー箇所・カバレッジ表など)を全部載せる

    PR コメントに情報を詰め込むと逆に読み飛ばされやすくなるため、要点は PR コメント、詳細は Job Summary の使い分けが無難です。


    つまずきやすいポイント

    • permissions の書き忘れ:pull-requests: write が無いと PR コメント投稿は 403 で失敗します

    • if: always() の書き忘れ:失敗時にサマリを出したいなら必須です

    • コメントが積み重なる:sticky でない方法だと実行のたびにコメントが増えます。header などの識別キーで「同じコメントを更新する」設定にしてください


    まとめ

    • とりあえず結果を見えるようにしたい → Job Summary。echo ... >> "$GITHUB_STEP_SUMMARY" だけで動く

    • レビュアーの目に確実に触れさせたい → PRコメント。marocchino/sticky-pull-request-comment@v3 + pull-requests: write の権限

    • 両方使いたい → 要点は PRコメント、詳細は Job Summary

    まずは Job Summary の最小サンプルをコピペして動作確認するのが一番ハマりにくい入り口です。細かいオプションや応用は、必要になったタイミングで各ツールのドキュメントを見に行けば十分です。

    あなたへのおすすめ