こんにちは。今日もコードを書いていますか？
CI/CDの世界へようこそ。私はこれまで数え切れないほどのパイプラインを設計し、数百万回ものビルドを見守ってきました。
そんな私が、モダンな開発現場において「これを知っているだけでチームの生産性が劇的に変わる」と断言できる技術があります。それが、GitHub Actionsの「Checks API」の高度な活用です。
多くのエンジニアは、CIを「成功（緑）」か「失敗（赤）」の二択で考えてしまいがちです。しかし、実際の開発現場はもっと曖昧で、もっと豊かですよね？
「テストは通ったけれど、少しコードの肥大化が気になる」「マージは許可するけれど、パフォーマンスの微減を警告しておきたい」……。
今回は、そんな「白黒つけられない大切な情報」をGitHubのUI上に美しく、かつ動的に表示する方法を、基礎から丁寧に解説します。これをマスターすれば、あなたのCIはただの自動化ツールから、チームに寄り添う「賢いパートナー」へと進化しますよ。
—
1. Checks APIとは？ 「ただのステータス」との違い
GitHub Actionsを使い始めると、プルリクエスト（PR）の画面に「All checks have passed」と表示されるのを目にするはずです。
通常、これは`.github/workflows/.yml`が完走したかどうかをGitHubが自動で判断しています。しかし、Checks APIを直接叩くと、以下のような「一歩先の制御」が可能になります。
- 動的な判定: 実行中に計算したスコア（例：テストカバレッジやLighthouseのスコア）に応じて、ステータスを「成功」「中立（Neutral）」「失敗」とリアルタイムに書き換える。
- リッチなレポート: PRの画面に、マークダウン形式で詳細なサマリー（表やリンク）を直接埋め込む。
- アノテーション: ソースコードの特定の行に対して、CIの結果から直接コメント（警告）を出す。
「失敗させてマージを止めるほどではないけれど、開発者に気づいてほしい」というWarning（警告）の文化を、CIに組み込めるのが最大の魅力です。
—
2. 準備：権限（Permissions）のセットアップ
GitHub ActionsからChecks APIを操作するには、ワークフローに「書き込み権限」を与える必要があります。
まずは、`.github/workflows/main.yml`（ファイル名は任意です）の冒頭に、以下の魔法の数行を書き加えましょう。
permissions:
contents: read
checks: write # ここが最も重要！Checks APIを操作する許可を与えます
pull-requests: write
これだけで、あなたのワークフローはGitHubのステータス画面を自由自在に操る「指揮官」の権利を得たことになります。
—
3. 実践：独自の「品質メトリクス・チェッカー」を作ってみよう
今回は、初心者の方でもすぐに試せるように、「独自の計算ロジックに基づいて、WarningやSuccessを出し分ける」という実践的なHelloWorldを作ってみましょう。
以下のコードをコピーして、リポジトリに配置してみてください。
name: “Dynamic Quality Gate”
on:
pull_request:
branches: [ main ]
jobs:
check-quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: “Run Custom Logic”
id: custom_logic
run: |
# ここで独自の検証（例：カバレッジ計測やファイルサイズチェック）を行うと想定します。
# 今回はデモとして、ランダムなスコアを生成してみましょう。
SCORE=$(( ( RANDOM % 100 ) + 1 ))
echo “score=$SCORE” >> $GITHUB_OUTPUT
echo “計測されたスコア: $SCORE”
- name: “Update GitHub Check Status”
if: always() # 前のステップが失敗しても実行するようにします
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SCORE: ${{ steps.custom_logic.outputs.score }}
run: |
# GitHub CLI (gh) を使って、Checks APIをスマートに叩きます。
# 1. 判定ロジックの定義
CONCLUSION=”success”
SUMMARY=”素晴らしい品質です！”
if [ $SCORE -lt 30 ]; then
CONCLUSION=”failure”
SUMMARY=”品質スコアが低すぎます。修正が必要です。”
elif [ $SCORE -lt 70 ]; then
CONCLUSION=”neutral” # これが「Warning」に近い挙動になります
SUMMARY=”合格点ですが、改善の余地があります（Warning）。”
fi
# 2. Checks APIの呼び出し
# endpoint: /repos/{owner}/{repo}/check-runs
gh api –method POST /repos/${{ github.repository }}/check-runs \
-f name=”Quality Gate Monitor” \
-f head_sha=”${{ github.event.pull_request.head.sha }}” \
-f status=”completed” \
-f conclusion=”$CONCLUSION” \
-f output[title]=”カスタム品質チェック結果” \
-f output[summary]=”
現在のスコア: $SCORE \n $SUMMARY”
—
4. このコードの「ここ」が凄い！
ただのサンプルコードに見えるかもしれませんが、ここには現場で役立つエッセンスが詰まっています。
① `conclusion: “neutral”` の活用
GitHub Actionsの標準的な「成功/失敗」に加えて、`neutral`（中立）というステータスを使っています。これはPR上では「黄色いアイコン（またはグレイのチェック）」として表示され、「ビルドは成功したけれど、注意が必要だよ」というニュアンスを伝えるのに最適です。
② `output[summary]` によるリッチな表現
単に成否を伝えるだけでなく、`summary`フィールドにマークダウンを書くことで、開発者はわざわざCIのログ（黒い画面）を見に行かなくても、PRのトップ画面で何が起きたか一目で理解できます。
③ GitHub CLI (`gh`コマンド) の利用
複雑な`curl`コマンドや外部ライブラリを使わず、GitHub Actionsに標準搭載されている`gh`コマンドを使っています。これが最もセキュアで、かつメンテナンスしやすい現代のデファクトスタンダードです。
—
5. 最後に：CI/CDは「対話」である
いかがでしたか？「CI＝テストを回すもの」という固定観念が、少しだけ崩れたのではないでしょうか。
Checks APIを使いこなせるようになると、以下のようなことが実現できます。
- デザイン崩れチェック: 差分を画像で比較し、微差があればWarningを出す。
- 依存関係の脆弱性: 深刻ならFailure、軽微ならNeutralでPRに表を表示。
- パフォーマンス計測: 以前の計測値より5%以上遅くなっていたら、警告を表示。
こうした「気遣い」を自動化に組み込むことで、レビューの時間は短縮され、チームの心理的安全性が高まります。
「これをマスターすれば、毎日の作業が劇的に楽になりますよ」という言葉に嘘はありません。まずはこの小さなHelloWorldから、あなたのリポジトリに「意思を持ったCI」を宿してみてください。
もし設定で迷うことがあったら、いつでも聞いてくださいね。あなたのパイプラインが、今日も美しい緑（時々、有益な黄色）に輝くことを願っています。