GitHub Action セットアップ

PR へのコメント投稿(1 PR = 1 コメント)と、PR クローズ時の失効は、あなたのリポジトリに置く GitHub Action(naoto24kawa/miseru/apps/action@v1)が担います。このページでその両方を設定します。

Action は実行環境の GITHUB_REPOSITORY から owner/repo を取得するため、利用者の workflow に repo 用の入力を追加する必要はありません。

事前準備

1. ダッシュボードで対象リポジトリのプロジェクトを作成し、Upload Token を発行する(→ ダッシュボードの使い方)
2. リポジトリの Settings → Secrets and variables → Actions に MISERU_TOKEN としてトークンを登録する

1. スクリーンショットをコメントする

CI でスクリーンショットを撮ったあとに Action を呼び出します。

name: screenshots
on: pull_request

permissions:
  pull-requests: write

jobs:
  shots:
    runs-on: ubuntu-latest
    steps:
      # ... スクショを ./shot.png に生成するステップ ...
      - uses: naoto24kawa/miseru/apps/action@v1
        with:
          miseru-token: ${{ secrets.MISERU_TOKEN }}
          file: ./shot.png
          name: home
          viewport: 1280x800

• permissions: pull-requests: write が必須です(コメントは github-actions[bot] 名義で投稿されます)
• file を省略すると、アップロードは行わず既存画像の集約コメントの更新だけを行います(エージェントが CLI/MCP で先にアップロードしている場合はこの形)

PR を reopen したとき

command: comment は reopened イベントで GitHub API により現在の PR が open であることを確かめ、アップロード前にコンテキストを開き直します。既に PR が閉じられていればエラーで停止し、コンテキストがまだ無い場合はそのまま続行します。

クローズ時に on_close で失効した画像は戻りません。必要な画像は再アップロードしてください。コメント用ワークフローで pull_request.types を絞っている場合は、reopened を含めてください(例: types: [opened, synchronize, reopened])。

2. PR クローズで失効させる

失効ポリシーが「PR クローズで失効」のプロジェクトでは、クローズ時に必ずこのワークフローを動かしてください。

name: miseru-expire
on:
  pull_request:
    types: [closed]

jobs:
  close:
    runs-on: ubuntu-latest
    steps:
      - uses: naoto24kawa/miseru/apps/action@v1
        with:
          command: close
          miseru-token: ${{ secrets.MISERU_TOKEN }}

types: [closed] はマージされた PR にも発火します。使い方 (b) に相当するこの close を置くと、merged で PR のベースライン（Kurabe）が共有へ上がり、マージせず closed で閉じた場合は捨てられます。画像の失効ポリシーが retain_days / forever でもベースラインはこの規則に従い、配信用の画像自体は失効しません。

Action の close を置かない場合は、マージ後に miseru close --pr <n> --reason merged を実行してください。comment のワークフローだけでは共有へ反映されません。CLI・MCP の既定の manual で閉じると PR のベースラインは捨てられます。

PR の closed イベントで実行されたとき、GitHub API で PR が再び open になっていると確認できれば close をスキップします。GITHUB_TOKEN が無い場合や状態取得に失敗した場合は、警告をログに残して従来どおりコンテキストを閉じます。

3. 未承認の変化で CI を止める

name: kurabe-check
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: naoto24kawa/miseru/apps/action@v1
        with:
          command: check
          miseru-token: ${{ secrets.MISERU_TOKEN }}
          wait: "60"

比較つきで push した画像を判定し、未承認の変化などがあれば job を失敗させます。画像ごとの状態と全体の判定をログと Job Summary に出します。承認した後は job を再実行してください。後から画像を push した場合も、再実行まで判定は変わりません。

wait は計算を待つ秒数で、0〜600 の整数、既定 60。5 秒ごとに取得し直し、0 なら 1 回だけ取得します。待ち切れない計算中も失敗します。404 で本文の message がちょうど context not found（この PR のコンテキストが無い）の場合だけ、判定なしで通します。route が無い・message が違う・本文が JSON でない等のそれ以外の 404、401・422・通信エラーは失敗します。

fork の PR では MISERU_TOKEN が渡らないため失敗します。必須の check にするなら、fork の PR を受けないリポジトリで使ってください。pull_request_target による権限昇格は行いません。アップロードするエージェントには承認の権限の無いトークンを使い、意図した変化は人が承認します。

入力一覧

input	必須	デフォルト	説明
command	—	comment	comment(アップロード + コメント更新) / close(コンテキストを閉じて失効ポリシーを適用) / check(比較の判定で job の成否を決める)
wait	—	60	check の待ち時間（秒）。0〜600 の整数
miseru-token	✅	—	Upload Token(secrets.MISERU_TOKEN 推奨)
github-token	—	${{ github.token }}	コメント投稿用トークン
api-url	—	https://api.miseru.dev	Miseru API のベース URL
pr-number	—	イベントから自動解決	PR 番号の明示指定
file	—	—	アップロードするスクリーンショットのパス(png/jpg/webp、5MB 未満)
name	—	—	スクリーンショットの論理名。file 指定時は必須。同じコンテキストで name と viewport が同じ画像は、古い画像を失効させて置き換えます
commit-sha	—	イベントから自動解決	コミット SHA の明示指定
viewport	—	—	例: 1280x800

• pr-number は pull_request 系イベントの payload から自動解決されます。workflow_dispatch など PR 文脈のないイベントで使う場合は明示指定してください(解決できないとエラーで失敗します)
• Action の失敗はジョブの失敗(exit 1)になります

コメントの仕組み(1 PR = 1 コメント)

• コメント本文の先頭にはマーカー <!-- miseru:pr-<PR番号> --> が埋め込まれます
• Action は PR のコメントを走査してこのマーカーを探し、見つかれば更新・なければ新規投稿します
• コメント本文はサーバー側で PR 単位に再生成されるため、スクリーンショットが増えても常に全画像が1コメントに集約されます

マーカーを含むコメントを手動で削除した場合は、次回実行時に新規投稿されます。

fork からの PR について

fork からの PR では github.token が読み取り専用のため、Action はコメント投稿をスキップし、markdown をログに出力するだけになります。Miseru はこの場合に権限を昇格する pull_request_target を意図的に使いません(セキュリティ上の定石として)。fork PR でもコメントが必要な場合は、リポジトリ管理者が別途安全な仕組みを検討してください。