【Github】Github Actions ～ Annotations / Matcher ～

Github

■ はじめに

Github Actions で 「Annotations」とか「Matcher」とか
でてきたので、調べてみた

あと、ついでに「GITHUB_STEP_SUMMARY」も載せておく

目次

【１】GitHub Annotations
　１）Annotationsの表示方法
　２）サンプル
　３）使用上の注意
【２】Problem Matchers
　１）Matchers の使い方
　２）Matchers の 有効化・無効化
　３）使用上の注意
　４）サンプル
【３】おまけ：GITHUB_STEP_SUMMARY

【１】GitHub Annotations

* GitHub Actionsでworkflowを開くとみることができる Annotations欄
* 以下が分かりやすい

https://scrapbox.io/uochan/Github_Actions_Annotations

cf. Annotation = 注釈

１）Annotationsの表示方法

* 以下の構文で表示できるが、サンプルを一旦見てもらう方が早い

https://docs.github.com/ja/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error

構文 

echo '::<Type> file=<FileName>,line=<Num>,col=<Num>::<Message>'

２）サンプル

name: DemoAnnotations

on:
  workflow_dispatch:

jobs:
  sample-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Demo
        run: |
           echo '::error file=README.md,line=1,col=3::line and column'
           echo '::warning file=README.md::file name only'
           echo '::notice::111'
           echo '::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon'
        continue-on-error: true

３）使用上の注意

* 表示には制限あり

https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md#limitations

* 10 warning annotations, 10 error annotations,
　 and 10 notice annotations per step
* 50 annotations per job
　(sum of annotations from all the steps)
* 50 annotations per run
　(separate from the job annotations,
　these annotations aren’t created by users)

【２】Problem Matchers

* GitHub Action の出力を正規表現マッチングしたものを
　アノテーションとして表示する機能

https://github.com/actions/toolkit/blob/master/docs/problem-matchers.md

１）Matchers の使い方

* .github/<FileName>.json を新規追加

構文
https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md#single-line-matchers

{
  "problemMatcher": [ // <= 絶対 "problemMatcher"。別の値にしてめちゃくちゃハマった
    {
      "owner": "ID (無効化する際に使用)【必須】",
      "severity": "'warning' or 'error' (Defaults to 'error')"
      "pattern": [
        {
            regexp: 正規表現 【必須】
            file: ファイル名
            fromPath: ファイルパス (e.g. a project file)
            line: 行数
            column: カラム数
            severity: 'warning' or 'error' Defaults to `error`
            code: エラーコード
            message: メッセージ【必須】
        }, ...
      ]
    }
  ]
}

２）Matchers の 有効化・無効化

https://github.com/actions/toolkit/blob/main/docs/commands.md#problem-matchers

[1] 有効化 

* add-matcher コマンドで定義 JSON ファイルを指定

例 

      # ★有効化
      - name: Enable Matchers
        run: echo "::add-matcher::【FileName】"

[2] 無効化 

* remove-matcher コマンドで
　Problem Matcher の ID （owner プロパティの値）を指定

例 

      # ★無効化
      - name: Disable Matchers
        run: echo "::remove-matcher owner=【OwnerID】::"

３）使用上の注意

[1] 「"problemMatcher"」は必須 

* 構文にあるように「"problemMatcher"」は必須で別名にしちゃだめ

４）サンプル

* 以下のようなメッセージを検知したら、エラー/警告で出力する
~~~~~~
badFile.js: line 50, col 11, Error - 'myVar' is defined but ...
~~~~~~

.github/demo_matcher.json 

{
  "problemMatcher": [
    {
      "owner": "hello_demo",
      "pattern": [
        {
          "regexp": "^(.+):\\sline\\s(\\d+),\\scol\\s(\\d+),\\s(Error|Warning|Info)\\s-\\s(.+)\\s\\((.+)\\)$",
          "file": 1,
          "line": 2,
          "column": 3,
          "severity": 4,
          "message": 5,
          "code": 6
        }
      ]
    }
  ]
}

.github/workflows/demo_annotations.yml 

name: DemoAnnotations

on:
  workflow_dispatch:

jobs:
  sample-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4      
      # ★有効化
      - name: Enable Matchers
        run: echo "::add-matcher::.github/demo_matcher.json"
      # エラーで表示
      - name: Demo for Matchers 1
        run: |
           echo 'badFile.js: line 50, col 11, Error - 'myVar' is defined but never used. (no-unused-vars)'
        continue-on-error: true
      # 警告で表示
      - name: Demo for Matchers 2
        run: |
           echo 'badFile.js: line 50, col 11, Warning - 'myVar' is defined but never used. (no-unused-vars)'
        continue-on-error: true
      # ここは、Info なので非表示
      - name: Demo for Matchers 3
        run: |
           echo 'badFile.js: line 50, col 11, Info - 'myVar' is defined but never used. (no-unused-vars)'
        continue-on-error: true
      # ★無効化
      - name: Disable Matchers
        run: echo "::remove-matcher owner=hello_demo::"

【３】おまけ：GITHUB_STEP_SUMMARY

* こだわると「GITHUB_STEP_SUMMARY」てのもあるらしい

https://synamon.hatenablog.com/entry/2023/01/06/181710

* ワークフロー実行のサマリーページに表示

https://docs.github.com/ja/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary

      # ★これで、「summary」部分にテーブルで表示される
      - name: Demo for GITHUB_STEP_SUMMARY
        run: |
          echo "|Properties|Value|" >> $GITHUB_STEP_SUMMARY
          echo "|---|---|" >> $GITHUB_STEP_SUMMARY
          echo "|GitHub Ref|\`${{ github.ref }}\`|" >> $GITHUB_STEP_SUMMARY
          echo "|Commit Hash|\`${{ github.sha }}\`|" >> $GITHUB_STEP_SUMMARY

参考文献

https://qiita.com/hasht/items/e900fcf35d4804da7758
https://buildersbox.corp-sansan.com/entry/2021/02/18/110000
https://qiita.com/nanakenashi/items/1797bedfa343833173f2
https://vlike-vlife.netlify.app/posts/github_actions_annotation

関連記事

Github ～ 入門編 ～
https://dk521123.hatenablog.com/entry/2019/07/18/234652
Github Actions ～ 基礎知識編 ～
https://dk521123.hatenablog.com/entry/2021/11/04/142835
Github Actions ～ 入門編 ～
https://dk521123.hatenablog.com/entry/2022/06/16/151443
Github Actions ～ 基本編 ～
https://dk521123.hatenablog.com/entry/2023/12/22/195715
Github Actions ～ プロパティ ～
https://dk521123.hatenablog.com/entry/2023/12/23/231250