自作CLIツールの役目が終わる日 — gh-attachをplaywright-cliが代替した話

はじめに
gh-attachが解決していた問題
gh-attachが動かなくなった
playwright-CLIのファイルチューザーで解決できた
振り返り
gh-attachのアーカイブ
リンク

はじめに

以前、GitHub Issue/PRに画像をアップロードするCLIツール gh-attach を作りました。

GitHubにはIssueコメントに画像をアップロードするAPIがありません。Web UIではドラッグ＆ドロップで貼れるのに、CLIやCIからは画像を添付できない。この制限を補うためにPlaywrightでブラウザ自動操作するツールを作り、3つのアップロードモードまで育てました。

そのgh-attachを、アーカイブしました。playwright-cliでやりたかったことが実現できるようになったからです。

gh-attachが解決していた問題

GitHubのIssueコメントAPIは body パラメータにMarkdownテキストを受け取るだけです。画像のアップロード先 uploads.github.com はOAuthトークンでの認証を受け付けず、ブラウザのセッションCookieが必要です。

gh-attachはこの制限に対して3つのアプローチを取っていました。

モード	方法	特徴
Browser	Playwrightでブラウザを操作して画像をアップロード	デフォルト
Release	GitHub Releasesに画像をアップロードしてURLを取得	ブラウザ不要だがrevertで画像が消える
Direct	ブラウザからupload policyを取得しcurlでアップロード	GitHub Enterprise（GHE）向け

どのモードも「GitHubにAPIがないから仕方なくブラウザを使う」という前提の上に成り立っていました。

gh-attachが動かなくなった

きっかけはGHE 3.19へのアップデートでした。gh-attachのDirect modeはupload policy APIを取得してcurlでファイルをアップロードする仕組みですが、GHE 3.19でAPIの取得が失敗するようになりました。

Browser modeも内部でPlaywrightスクリプトを動かしている関係で、GHEのUI変更に追従し続ける必要があります。自作ツールでGitHubの内部APIをハックし続けるのは限界がありました。

playwright-CLIのファイルチューザーで解決できた

代わりに使えたのが、Microsoftが公開したplaywright-cliです。ブラウザ操作をCLIコマンドとして提供するツールで、gh-attachが内部でやっていたことをコマンドの組み合わせで直接実行できます。

手順は以下の通りです。

# 1. IssueページをPlaywrightで開く
playwright-cli open "https://github.com/owner/repo/issues/123"

# 2. ページ構造を取得して要素のref番号を確認
playwright-cli snapshot

# 3. 「Paste, drop, or click to add files」ボタンをクリック
playwright-cli click <ref>

# 4. ファイルチューザーが開くので画像を指定
#    → アップロード完了後、テキストエリアに
#      ![image](https://github.com/.../user-attachments/assets/xxx)
#      が自動挿入される

# 5. テキストエリアからURLを抽出
playwright-cli snapshot

ポイントは、コメントの投稿自体はplaywright-CLIでは行わないことです。テキストエリアに自動挿入された user-attachments のURLだけを取得し、実際のコメント投稿は gh api で行います。こうすることでブラウザ操作を最小限に抑えられます。

gh-attachが独自に実装していたupload policyの取得やfetchインターセプトは不要になりました。GitHubのUIが提供するファイル添付機能をそのまま使うだけなので、GHEのバージョンアップにも追従しやすくなります。

振り返り

gh-attachを作り始めた時点で、playwright-CLIは存在していませんでした。だからgh-attachは必要なツールでした。

ただ振り返ると、gh-attachがやっていたことの本質は「ブラウザのファイル添付UIを自動操作して画像URLを取得する」です。playwright-CLIが最初からあれば、シェルスクリプトで数行書くだけで済んだはずです。

自作ツールを育てる過程での学びは無駄になっていません。Browser modeの実装、Release modeのrevert問題とDirect modeへの発展、fetchインターセプトの技術。ただ、GitHubの内部APIに依存したアプローチは、結局アップデートのたびに壊れるリスクを抱えていました。公式UIをそのまま自動操作するplaywright-CLIのアプローチのほうがシンプルで堅牢です。