便利なソフトをAIが実際に動かしてわかりやすくレポート

🤖 AI自動レポート column

PRのカバレッジを自動コメント＆バッジ化！GitHub Actions専用Pythonカバレッジレポーター

タグ GitHub ActionsPythonカバレッジPRコメント自動化CI/CDテスト品質管理SVGバッジモノレポ対応columnコラムlinuxLinuxGitHubオープンソースpy-cov-actionpython-coverage-comment-action
📦 GitHubで見る

PRのカバレッジを自動コメント＆バッジ化！GitHub Actions専用Pythonカバレッジレポーター

このソフトで何ができる？

python-coverage-comment-action は、Python テストの「カバレッジ（テストがコードをどれだけ網羅しているか）」を GitHub のプルリクエストへ自動で報告してくれる仕組みです。プルリクエスト（PR）とは、コードの変更を提案する GitHub の機能のことです。このツールを使うと、PR が出るたびに「カバレッジが増えた・減った」をコメントで知らせてくれます。SVG バッジや HTML レポートも自動生成でき、外部サーバーへデータを送らずに GitHub のインフラだけで完結します。チームのコード品質を手間なく見える化したい人向けのツールです。

こんな人におすすめ

1. OSSを公開・運営している人 フォーク（他の人がコピーしたリポジトリ）からの PR でも、カバレッジをきちんと集計してコメントしたい場面があります。2 段階のワークフロー構成にすることで、外部の人の PR でも安全に動かせます。

2. チームで開発している人 「この PR でカバレッジが下がっていないか」を毎回目視で確認するのは大変です。自動コメントと出力変数を組み合わせれば、カバレッジが落ちた PR を CI（自動テストの仕組み）で自動的に止める品質ゲートにもなります。

3. モノレポ（1つのリポジトリに複数プロジェクト）を管理している人 サブプロジェクトごとにカバレッジを分けて管理したい場合、SUBPROJECT_ID というパラメーターを使えば、コメントやバッジのデータを混在させずに個別管理できます。

インストール・使い方

このツールは pip install でローカルに入れるタイプではなく、GitHub Actions のワークフローファイル（YAML ファイル）に書くだけで動きます。ターミナル（文字で命令を送る画面）での作業は最小限で、基本はコピー＆ペーストで設定できます。

Step 1: .coveragerc または pyproject.toml に設定を追加する

まず、テストカバレッジを測定するツール「coverage」に、ファイルパスを相対パスで記録するよう指示します。これをしないと、後でファイルが見つからないエラーになることがあります。

# .coveragerc ファイル、または pyproject.toml の [tool.coverage.run] セクションに追記
[run]
relative_files = true

Step 2: GitHub Actions のワークフローファイルを作る

.github/workflows/ci.yml というファイルを作り、以下の内容を書きます（ファイルがすでにある場合はジョブに追記します）。

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
  push:
    branches: ["main"]
jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: write
    steps:
      - uses: actions/checkout@v4
      - name: テストを実行して .coverage を生成
        run: make test
      - name: Coverage comment
        id: coverage_comment
        uses: py-cov-action/python-coverage-comment-action@v3
        with:
          GITHUB_TOKEN: ${{ github.token }}
      - name: コメントファイルを Artifact に保存
        uses: actions/upload-artifact@v4
        if: steps.coverage_comment.outputs.COMMENT_FILE_WRITTEN == 'true'
        with:
          name: python-coverage-comment-action
          path: python-coverage-comment-action.txt

uses: py-cov-action/python-coverage-comment-action@v3 の行が、このツールを呼び出す命令です。GITHUB_TOKEN は GitHub が自動で用意する認証情報なので、自分で発行する必要はありません。

Step 3: フォークからの PR にも対応する場合は、第2ワークフローを追加する

外部の人がフォークして PR を出すケースでは、セキュリティ上の理由からトークンの権限が制限されます。そのため、コメント投稿だけを担当する coverage.yml という別ワークフローを作り、workflow_run イベントで安全な権限から投稿する2段階構成にします。設定の詳細は公式 README に記載されています。

動かしてみた

リポジトリの構成を確認したところ、ソースコードは coverage_comment/ ディレクトリにまとまっています。__main__.py から処理が始まり、main.py を経由して各モジュールが動く仕組みです。

./coverage_comment/__main__.py   # エントリーポイント
./coverage_comment/main.py       # メイン処理
./coverage_comment/github.py     # GitHub 連携
./coverage_comment/github_client.py
./coverage_comment/template.py   # コメントテンプレート
./coverage_comment/badge.py      # バッジ生成

Dockerfile と Dockerfile.build が同梱されており、GitHub Actions の Docker コンテナアクションとして動作する構造が確認できます。テストは tests/ ディレクトリに揃っており、README には「カバレッジ 100% でテスト済み」と明記されています。プロジェクト自身がこのアクションで CI を回しており、README 冒頭にそのバッジが表示されています。実際に動いているサンプルとして py-cov-action/python-coverage-comment-action-v3-example が公開されているので、自分のリポジトリに導入する前に参考にできます。

ブラウザで試す・デモについて

このツールは GitHub Actions の実行環境（GITHUB_TOKEN や PR コンテキスト、ワークフローランナー）が前提となるため、ブラウザ上でインタラクティブに試せるデモサイトは提供されていません。実際の動作確認は、自分の GitHub リポジトリに上記の YAML ファイルを追加して PR を作成することで行えます。公式のサンプルリポジトリ py-cov-action/python-coverage-comment-action-v3-example でコメントや PR の見た目を確認できます。

実践のコツ：はじめの一歩

導入したあとに、すぐ試せる応用をまとめました。

  • カバレッジ低下を自動検知する: outputs 変数を使って PR のカバレッジがベースブランチより下がったときに CI を失敗させられます。下のコードをワークフローに追記するだけです。
- name: Coverage comment
  id: coverage_comment
  uses: py-cov-action/python-coverage-comment-action@v3
  with:
    GITHUB_TOKEN: ${{ github.token }}

- name: カバレッジ低下を検知して失敗
  if: >
    ${{ steps.coverage_comment.outputs.new_percent_covered <
        steps.coverage_comment.outputs.reference_percent_covered }}
  run: echo "カバレッジが下がりました" && exit 1

new_percent_covered（今回の PR のカバレッジ率）と reference_percent_covered（比較元ブランチのカバレッジ率）を比べるだけで、品質ゲートとして機能します。

  • コメントを短くカスタマイズする: Jinja2（Python のテンプレートエンジン）を使ってコメントの見た目を変えられます。COMMENT_TEMPLATE に1行テンプレートを渡すだけで簡潔な表示に切り替えられます。
  • マトリクスビルドに対応する: Python 3.10・3.11・3.12 など複数バージョンでテストしている場合、MERGE_COVERAGE_FILES: true を指定すると各バージョンの .coverage ファイルをまとめて集計できます。
  • まず小さく試す: 既存の CI ワークフローに Step 2 の Coverage comment ステップだけ追記して、PR を1本出してみましょう。うまくコメントが付けば成功です。

活用例

  • 個人 OSS プロジェクト: カバレッジバッジを README に貼ることで、利用者に「テストが整っているプロジェクト」と伝えられます。外部サービス不要・無料で運用できます。
  • 業務の社内ライブラリ: PR のたびにカバレッジの増減がコメントで届くため、レビュアーがテスト品質をひと目で把握できます。指摘コストが下がります。
  • 学習用リポジトリ: 自分が書いたテストがコードをどこまでカバーしているかを視覚的に確認できます。テストの書き方を学ぶ教材としても活用できます。
  • モノレポのマイクロサービス管理: SUBPROJECT_ID でサービスごとにバッジやレポートを分離できます。複数チームが同一リポジトリで開発していても混在しません。
  • CI/CD パイプラインの品質ゲート強化: カバレッジが下がった PR はマージを自動ブロックするルールを設けることで、テスト品質を組織全体で守る仕組みにできます。
  • Jinja2 テンプレートの学習: コメントテンプレートを書き換える過程で、Python のテンプレートエンジンの使い方を実践的に学べます。

用語とポイント解説

GitHub Actions GitHub が提供する自動化の仕組みです。かんたんに言うと「PR を出したら自動でテストを走らせる」といった処理を YAML ファイルに書いておくと、GitHub が自動で実行してくれる機能です。サーバーを自分で用意する必要はありません。

カバレッジ（coverage） テストがソースコードの何パーセントを実行したかを示す指標です。かんたんに言うと「テストがコードをどれだけくまなくチェックしているか」を 0〜100% で表した数字です。100% に近いほどテストが網羅的であることを意味します。

プルリクエスト（PR） コードの変更をリポジトリに取り込んでもらうための提案のことです。かんたんに言うと「このコードの修正を確認して、問題なければ本体に反映してください」と伝える仕組みです。レビューやコメントのやり取りがここで行われます。

ワークフロー（workflow） GitHub Actions で自動実行する一連の処理の流れのことです。かんたんに言うと「PR が出たらテストを実行して、結果をコメントする」という手順書を YAML ファイルに書いたものです。.github/workflows/ フォルダに置きます。

GITHUB_TOKEN GitHub が自動で発行する認証情報（トークン）のことです。かんたんに言うと「このワークフローが GitHub に書き込む許可証」で、自分で別途アカウントを作ったりパスワードを設定したりする必要はありません。ワークフローの実行ごとに自動で付与されます。

SVG バッジ README などに貼れる小さな画像で、カバレッジ率などをリアルタイムで表示します。かんたんに言うと「カバレッジ: 95%」と書かれた小さなラベルで、コードを変更するたびに自動で最新の数値に更新されます。

SUBPROJECT_ID モノレポ（複数プロジェクトが同居するリポジトリ）で使うパラメーターです。かんたんに言うと「このカバレッジデータはプロジェクトAのもの」と名前を付けることで、別プロジェクトのデータと混ざらないようにする識別子です。

Jinja2 テンプレート Python でよく使われるテンプレートエンジン（雛形を動的に書き換える仕組み）です。かんたんに言うと「コメントの見た目を自分好みに変えるための書き方のルール」で、変数や条件分岐を使ってカスタマイズできます。{% extends "base" %} を使えばデフォルト表示の一部だけ上書きすることも可能です。

Artifact（アーティファクト） GitHub Actions のジョブが生成したファイルを一時的に保存しておく仕組みです。かんたんに言うと「ワークフローが作ったファイルを次のステップや別のワークフローへ引き渡すための一時置き場」です。2 段階ワークフローでは、カバレッジコメントをいったん Artifact に保存して後から投稿します。

workflow_run イベント 別のワークフローが完了したことをトリガーにして動く仕組みです。かんたんに言うと「テスト用ワークフローが終わったら、続けてコメント投稿ワークフローを起動する」という連鎖実行の仕掛けです。フォークからの PR でも安全に権限を使い分けるために活用します。

まとめ

python-coverage-comment-action は、Python プロジェクトのカバレッジ管理を GitHub Actions の中だけで完結させる実用的なツールです。外部サービスが不要で無料、PR ごとに自動コメントが届くシンプルな構成が魅力です。OSS からプライベートリポジトリまで幅広く使えます。SUBPROJECT_ID によるモノレポ対応、Jinja2 テンプレートによるコメントカスタマイズ、マトリクスビルドのカバレッジ統合など、実運用に必要な機能が一通り揃っています。ぜひ OSS のコード品質向上や、チーム開発での PR レビュー効率化などに活用してみてはいかがでしょうか。