【GitHub Actions】ログ内容をAnnotationsに表示する

はじめに

GitHub Actionsで実行したチェック(自動テスト・静的解析ツール等)が失敗した時、
Jobの実行ログを確認するのは地味に手間がかかります。
このときActionsのSummaryにあるAnnotationsに、
「Jobが失敗した」という通知に加えてエラー内容も表示されていると、
なぜ失敗したかをより簡単に把握できるようになります。
この記事ではProblem Matchersを使ってエラー内容を確認しやすくする方法についてまとめました。

Problem Matchersとは

Problem MatchersはGitHub Actionsに備わったツールの1つです。
指定した正規表現をもとにJobのログ出力をスキャンし、
マッチした部分をAnnotationsに表示してくれます。

Problem Matchersの使い方

ここでは例として以下のように出力されたログをAnnotationsに表示していきます。

Failure:
BooksControllerTest#test_AAAの場合_XXXになる [/home/runner/work/sample-app/sample-app/test/controllers/books_controller_test.rb:7]:
Expected false to be truthy.

Matcherの作成

.githubディレクトリにjsonファイルを作成してMatcherを定義します。

problem-matcher.json

{
  "problemMatcher": [
    {
      "owner": "test-failure",
      "pattern": [
        {
          "regexp": "^Failure:$"
        },
        {
          "regexp": "^.*?#test_.*?\\s\\[/home/runner/work/sample-app/sample-app/(.*?\\.rb):(\\d+)\\]:$",
          "file": 1,
          "line": 2
        },
        {
          "regexp": "^(.*)$",
          "message": 1
        }
      ]
    }
  ]
}

マッチさせたいログについて、行ごとに正規表現パターンを指定します。
file line messageといったプロパティでは、
正規表現中で()で括った部分のうち
何番目がファイル名・行番号・メッセージにあたるのかを指定しています。
同様に設定できるプロパティは他にもcode(エラーコード)等いくつか存在します(参考)。

Matcherの有効化

jsonで定義したMatcherを、対象のチェックを実行する前の段階で有効化しておきます。

- name: Enable Problem Matcher
  run: |
    echo "::add-matcher::.github/problem-matcher.json"

これにより直後に実行されるチェックのログ出力のうち、
マッチした部分がAnnotationsに表示されるようになります。

また、生成されたAnnotationはプルリクエストのファイル差分にも表示されます。

参考

toolkit/problem-matchers.md at main · actions/toolkit
toolkit/commands.md at main · actions/toolkit