gh-xz: PR/Issue のコメントをアンカー文字列で管理する gh 拡張

開発の動機

CI/CD パイプラインで PR にコメントを自動投稿したい場面は極めて多いです。テスト結果、カバレッジレポート、 lint の警告など、 bot がコメントで通知してくれると便利です。

しかし、何も考えずに実装すると CI が走るたびに同じ内容のコメントが増殖してしまいます。かといって毎回コメントを検索して ID を取得し、存在すれば更新、なければ新規作成…というロジックを書くのは面倒です。

そこで、コメントを「アンカー文字列」で一意に識別して管理できる gh 拡張を作りました。

概要

gh-xz は GitHub CLI (gh) の拡張機能で、PR や Issue のコメントをアンカー文字列で管理できます。

アンカー文字列とは、コメント末尾に付与される  形式の HTML コメントのことです。この文字列でコメントを特定し、同じアンカーを持つコメントが既にあれば更新、なければ新規作成します。

インストール

gh extension install https://github.com/hakadoriya/gh-xz

これで gh xz コマンドが使えるようになります。

使い方

コメントを投稿・更新する

# 直接文字列を指定
gh xz put-anchored-comment owner/repo 123 "my-anchor" "テスト結果: すべて成功しました"

# ファイルから読み込み
gh xz put-anchored-comment owner/repo 123 "my-anchor" @./report.md

# 標準入力から読み込み
cat ./report.md | gh xz put-anchored-comment owner/repo 123 "my-anchor" @-

初回実行時はコメントが新規作成され、2 回目以降は同じアンカーを持つコメントが更新されます。

コメントを取得する

gh xz get-anchored-comment owner/repo 123 "my-anchor"

指定したアンカーを持つコメントの本文を取得できます。

GitHub Actions での利用

hakadoriya-actions/setup-gh-xz を使うと GitHub Actions で簡単にセットアップできます。

name: post-comment

on:
  pull_request:

jobs:
  comment:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: hakadoriya-actions/setup-gh-xz@v0.0.1

      - name: Post coverage report
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh xz put-anchored-comment \
            ${{ github.repository }} \
            ${{ github.event.number }} \
            "coverage-report" \
            "カバレッジ: 87.5%"

CI が走るたびにコメントが増殖することなく、常に最新の結果で更新されます。

仕組み

内部では gh api を使って GitHub API を呼び出し、コメントを操作しています。

対象 PR/Issue のコメント一覧を取得
アンカー文字列を含むコメントを検索
見つからなければ POST で新規作成、見つかれば PATCH で更新

アンカー文字列は自動的に  で囲まれるため、ユーザーは単純な文字列を指定するだけで済みます。

依存関係は gh コマンドのみで、単一の Bash スクリプトとして動作します。