feat: composite action として VRT Action を実装

[yupix]

概要

README で先に定めた入出力設計に沿って、action を実装する。これまでこのリポジトリは README 1 ファイルのみで、uses: に指定しても動作しなかった。

実装方針

composite action として実装した（TypeScript ではない）。理由は、bundle した dist/ をコミットする運用を避け、変更がそのままレビューできる状態を保つため。GitHub のランナーには curl / jq / git / tar があるのでシェルで完結する。

ファイル	役割
action.yml	inputs / outputs / composite step
scripts/main.sh	オーケストレーター（解決 → 検証 → 振り分け → outputs → exit）
scripts/lib.sh	共通ヘルパー（認証・状態→終了コード・build-url・outputs）
scripts/validate.sh	入力の解決と検証
scripts/collect-pngs.sh	PNG 走査と名前導出
scripts/screenshots.sh	CI REST API を直接叩く
scripts/storybook.sh	vrt CLI へ委譲

• screenshots: REST を直接叩く（ビルド作成 → PNG を 1 枚ずつ → finalize → ポーリング）。PNG 以外の混入・25 MiB 超・空ディレクトリはアップロード開始前に全件チェックして落とす。中途半端なビルドを作らないため
• storybook: koyori-app/vrt の Release から CLI を取得（SHA256 チェックサム検証あり）して委譲する

README からの意図的な変更（2 点）

1. commit の既定値

README は GITHUB_SHA としていたが、github.event.pull_request.head.sha を優先する実装にした。pull_request イベントの GITHUB_SHA は main へのマージコミットで、GitHub 上に永続しない。VRT に記録された commit SHA は GitHub App がコミットステータスを貼る先になるため、PR ブランチに実在する head SHA でなければ貼れない。README の該当行も理由付きで更新した。

2. input を 2 つ追加

• cli-version（既定 latest）— storybook モードで使う CLI のリリースタグ
• app-url（既定は空）— build-url 組み立て用の Web UI ベース URL。空のときは url から末尾の /api を除いた値を使う。リバースプロキシ構成では API のベースが https://example.com/api、UI のベースが https://example.com になり得るため

セキュリティ上の扱い

• トークンは使用前に ::add-mask:: でマスク
• curl には --config（mode 600 の一時ファイル）でヘッダーを渡し、ps から見える argv にトークンを置かない。終了時に trap で削除
• set -x は使わない

レビューで見てほしい点

実装後の検証で終了コードのバグを 1 件見つけて直した（2 コミット目）。

die が終了コードを : "${CODE:=2}" で決めていたが、main.sh が dispatch 前に CODE=0 を初期化しているため代入が発火せず、ビルド作成後の致命的エラーでも exit 0 で終了していた。outputs には result=failed / exit-code=0 という矛盾した値が書かれ、アップロード失敗や HTTP エラーでもワークフローが緑のまま通る状態だった。

終了コードを明示的に代入する形へ修正し、3 経路すべてを実際に実行して確認した。

経路	終了コード
ビルド作成後の失敗	2（result=failed / exit-code=2）
ビルド作成前の失敗（PNG 検証など）	1
入力検証エラー	1

確認したこと

• shellcheck 警告ゼロ（Docker の koalaman/shellcheck:stable で実行）。SC2034 の誤検知は、main.sh が全スクリプトを source して変数を共有する構造によるものなので、理由コメント付きのディレクティブで抑制した
• bash -n 全 6 スクリプト構文エラーなし、action.yml の YAML パース OK（inputs 12 / outputs 4）
• 入力検証を実行して確認: mode 不正 / only-changed + screenshots / stats-json 単独 / project の形式 4 種 / token 空 / url 空 → すべて exit 1
• PNG 走査を実行して確認: 名前導出が mobile/home.png → mobile/home（階層保持・拡張子除去）、PNG 以外の混入・空ディレクトリ・欠損ディレクトリ・25 MiB 超 → すべてアップロード前にエラー
• storybook モードは偽 CLI を使って --json 最終行のパース、wait: true での CLI 終了コード採用、wait: false での 0 固定、--json 非対応の旧 CLI に対するエラーメッセージを確認

未検証: 実 API を叩く経路（認証情報が無いため）。実際のリリースからの CLI ダウンロードも未検証。

依存

storybook モードには cli-v0.1.0 以降の vrt CLI が必要（--json フラグを使うため）。これは koyori-app/vrt#7 で実装済みで、マージ後にタグを切ると Release が作られる。screenshots モードはこの依存なしで動く。

[qodo-code-review]

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

[sousuke0422]

コードレビュー

総合判定: APPROVE with Comments

シェルで書かれた composite action としては、危険な箇所がよく押さえられています。特に inputs を env: で渡して run: に ${{ }} を展開していない点は、composite action で最も踏まれやすいスクリプトインジェクションを構造的に防いでいます。トークンの扱い（::add-mask:: → curl --config の 600 ファイル → trap 削除）も一貫しており、JSON 組み立ても jq -cn --arg で手書き連結を避けています。

指摘は 3 件です。うち 2 件は「想定外の入力・外部要因を黙って通してしまう」型で、いずれも回帰検知ゲートとしての信頼性に関わります。

---

🟡 Low-Medium: wait の値を検証しておらず、true 以外を黙って「待たない」に倒すため回帰があっても緑になる

scripts/validate.sh:resolve_inputs と各モードの分岐:

WAIT="${INPUT_WAIT:-true}"      # validate_inputs では一切検査されない

# screenshots.sh / storybook.sh 共通
if [ "$WAIT" = "true" ]; then
    ...                          # 結果を待って CODE に反映
else
    CODE=0                       # ← "true" 以外は全部ここ
fi

mode は screenshots | storybook 以外を die で弾き、project も形式を厳密に検査しているのに、wait と only-changed だけ検査がありません。wait: "yes" や wait: 1 のような値を書くと入力エラーにならず、静かに wait: false として扱われ、アクションは常に終了コード 0 で成功します。

wait は「VRT の結果を CI の合否へ反映する」というこのアクションの中心的な機能なので、ここが黙って無効化されると、視覚的回帰が出ているのにワークフローが緑のまま通ります。しかも result には processing などの途中状態が入るだけなので、ログを見ても異常に見えません。

対処: mode と同じ形で真偽値を検査する。validate_inputs に追加してください。

# 真偽値の入力は mode と同様に弾く。誤記を黙って false に倒すと、
# wait の場合は回帰があってもワークフローが緑で通ってしまう。
for pair in "wait:$WAIT" "only-changed:$ONLY_CHANGED"; do
  case "${pair#*:}" in
    true | false) ;;
    *) die "input '${pair%%:*}' must be 'true' or 'false', got '${pair#*:}'." ;;
  esac
done

---

🟡 Low-Medium: cli-version: latest（既定値）が未認証の api.github.com に依存し、レート制限時に原因不明のエラーで落ちる

scripts/storybook.sh:resolve_cli_tag:

tag="$(curl -sSL "https://api.github.com/repos/${VRT_REPO}/releases" |
  jq -r 'map(select(.tag_name | startswith("cli-v"))) | .[0].tag_name // empty')"
[ -n "$tag" ] || die "could not resolve the latest 'cli-v*' release tag from ${VRT_REPO}. Pin one with cli-version, e.g. cli-version: cli-v0.1.0."

問題が 3 つ重なっています。

1. 認証なし: api.github.com への未認証リクエストは IP あたり 60 回/時です。GitHub ホストランナーは egress IP を共有するため、他所の消費で枯れます。既定値が latest なので、何も設定しなかった利用者が最初に踏みます
2. --fail が無い: download_cli 側の curl には --fail が付いているのに、ここだけ付いていません。403 が返ってもレート制限の JSON 本文がそのまま jq に流れ、該当タグが無いだけの結果になります
3. エラーメッセージが原因を指さない: 実際はレート制限なのに「リリースが見つからない。タグを固定せよ」と出るため、利用者は存在するリリースを探し続けることになります

加えて /releases の .[0] は prerelease も含みます（GitHub の /releases/latest は prerelease と draft を除外する別エンドポイントです）。cli-v0.2.0-rc1 を公開した時点で latest がそれを掴みます。

対処: トークンを渡せるようにし、prerelease を除外するエンドポイントへ切り替える。action.yml に入力を追加してください。

  github-token:
    description: Token used to resolve the latest cli-v* release. Defaults to the workflow token.
    required: false
    default: ${{ github.token }}

        INPUT_GITHUB_TOKEN: ${{ inputs.github-token }}

resolve_cli_tag を差し替え:

  local tag
  # 未認証だと IP あたり 60 回/時で枯れ、prerelease も混ざる。
  tag="$(curl -sSL --fail -H "Authorization: Bearer ${GITHUB_TOKEN_INPUT}" \
    "https://api.github.com/repos/${VRT_REPO}/releases/latest" |
    jq -r '.tag_name // empty')" ||
    die "could not reach the GitHub releases API for ${VRT_REPO} (rate limit or network). Pin a tag with cli-version, e.g. cli-version: cli-v0.1.0."

cli-v* 以外のタグ（バックエンド本体のリリース）も同じリポジトリに並ぶ場合は、取得後に startswith("cli-v") を検査して合わなければ die してください。

---

🔵 Low: ビルド作成前に失敗すると outputs が 1 つも書かれず、README の記述と食い違う

scripts/lib.sh:die:

die() {
  echo "::error::$*" >&2
  local code=1
  if [ -n "${BUILD_ID:-}" ]; then   # ← ビルド未作成なら write_outputs を通らない
    RESULT="failed"; CODE=2; code=2
    write_outputs
  fi
  exit "$code"
}

README は次のように書いています。

build-url を含む outputs は、終了コードにかかわらず（差分検出や失敗時も）書き出します。

しかし入力検証エラー・PNG 検証エラー・CLI ダウンロード失敗はいずれも BUILD_ID が空の状態で die するため、write_outputs を通りません。main.sh 末尾の write_outputs にも到達しないので、宣言している 4 つの output がすべて空文字になります。build-url は元々存在しないので妥当ですが、result と exit-code まで空になるため、continue-on-error: true を付けた利用者は「早期に失敗した」ことを output から判別できません。

CLI ダウンロード失敗は、cli-v0.1.0 の Release がまだ無い現状では最初に踏まれる経路です。

対処: die で常に outputs を書き出す。

die() {
  echo "::error::$*" >&2
  local code=1
  if [ -n "${BUILD_ID:-}" ]; then
    # ビルドが存在する = 実行時の失敗。作成前の失敗（使い方の誤り）と終了コードで区別する。
    code=2
  fi
  RESULT="failed"
  CODE="$code"
  write_outputs
  exit "$code"
}

---

✅ 良い点

• inputs を env: 経由でスクリプトへ渡し、run: に ${{ }} を一切展開していない。composite action で最も踏まれやすいスクリプトインジェクション（project や branch に細工した文字列を入れて任意コマンドを実行させる経路）が構造的に成立しない
• トークンの取り扱いが一貫している。使用前に ::add-mask::、curl --config の 600 パーミッション一時ファイルで argv に載せない、trap ... EXIT で確実に削除、set -x を使わない
• JSON ボディを jq -cn --arg で組み立てている。コミットメッセージに引用符や改行が含まれてもボディが壊れず、値が構造として注入される余地もない。pull_request_number も test("^[0-9]+$") で数値検証してから tonumber している
• screenshots モードで PNG の全件検証をアップロード開始前に済ませてからビルドを作る設計。中途半端なビルドを残さない
• CLI アーカイブの SHA256 検証があり、チェックサムファイルが空のケースも弾き、展開後に vrt バイナリの存在も確認している
• project の形式検証が厳密。スラッシュ 0 個・2 個以上・テナント空・プロジェクト空をすべて 1 つの条件で正しく弾いている
• ファイル名の扱いが堅牢。find -print0 と while IFS= read -r -d '' の組み合わせで、空白・改行・グロブ文字を含むファイル名でも壊れない
• commit の既定値を github.event.pull_request.head.sha 優先にした判断と、その理由（pull_request の GITHUB_SHA は永続しないマージコミットなのでコミットステータスを貼れない）が README とコードコメントの両方に残っている
• ビルド作成直後に CODE=2 を置いて write_outputs を呼び、build-id / build-url を早期に確定させている
• 実装後の検証で die の : "${CODE:=2}" バグを自力で発見し、修正した上で 3 経路すべてを実行確認している
• 各スクリプトが [ "${BASH_SOURCE[0]}" = "${0}" ] で直接実行にも対応しており、collect-pngs.sh と validate.sh を API に触れずに単体検証できる
• composite action を選び、bundle した dist/ をコミットする運用を避けた判断

---

📝 仕様による意図的設計（指摘ではありません）

• チェックサムをアーカイブと同じ Release から取得している点は、改ざんではなく転送時の破損を検出する仕組みとして妥当です。HTTPS + --fail が実質的な信頼の根拠で、公開されている多くの action と同じ形です
• wait: false のとき result に途中状態が入ることは README に明記済みで、終了コード 0 は「作成・アップロード・finalize が受理された」ことのみを表します
• 非 PNG ファイルが 1 つでもあると失敗する厳格さは、README に記載のある意図的な設計です
• download_cli の一時ディレクトリを削除していない点は、ランナーが実行ごとに破棄されることと、AUTH_CONFIG の trap を上書きしない利点があります