github-upload-image-to-pr

Upload Image to PR

There are two ways to get a local image into a PR, and they differ enormously in cost and reliability:

• Path A — gh --attach (GitHub CLI 2.99.0+, released 2026-09): one shell command. No browser, no MCP server, no snapshots, no polling. Use this whenever it's available.
• Path B — browser upload (fallback): drive a real browser to GitHub's comment box, which is the only public way to reach GitHub's image host on older gh. Many steps, many failure modes, lots of tokens.

Path B exists because GitHub's REST API still has no image-upload endpoint. Path A works because gh itself now talks to the internal upload endpoint for you — so treat Path B as legacy, not as an equal alternative.

Step 1: Pick the path

GH_VER=$(gh --version 2>/dev/null | head -1 | awk '{print $3}')
echo "gh: ${GH_VER:-not installed}"
# Path A requires >= 2.99.0
[ -n "$GH_VER" ] && [ "$(printf '%s\n2.99.0\n' "$GH_VER" | sort -V | head -1)" = "2.99.0" ] \
  && echo "=> Path A (gh --attach)" || echo "=> Path B (browser fallback)"

Use Path B when any of these hold:

Condition	Why Path A can't work
gh older than 2.99.0, or not installed	The --attach flag doesn't exist yet
Host is GitHub Enterprise Server	Attachments ship on GitHub.com and Enterprise Cloud only
No push access to the repo (e.g. someone else's fork)	--attach uploads require push access
gh --attach fails for an unclear reason	Don't sink time into it — note the error and fall back

gh is needed in both paths (Path B still embeds via gh pr edit), so if it isn't installed at all, ask the user to install it first: brew install gh (macOS) or see https://cli.github.com/.

If you land on Path B because gh is old, say so loudly

The user is about to pay for a slow, flaky browser session that a one-liner would have handled. That's worth interrupting for — but not worth blocking on, so surface the notice, then get on with Path B and deliver the images. Lead your reply with something like this (match the user's language):

⚠️ gh を更新すると、この作業はコマンド1発になります 現在: gh 2.86.0 / 必要: 2.99.0 以上 更新後は gh pr comment 123 --attach ./shot.png だけで完了します（ブラウザ操作なし・高速・安定）。 更新コマンド: brew upgrade gh 今回はブラウザ自動化で続行します。

If the user asks you to upgrade, run the upgrade, re-check the version, and switch to Path A for the current request too.

---

Path A — gh --attach (preferred)

--attach takes <file> or <file>#<alt text>, is repeatable (up to 50 files per command, and the same file can't be attached twice), and is available on gh pr create / pr edit / pr comment and the three matching gh issue commands.

Append to the PR description

gh pr edit {PR_NUMBER} --attach './screenshot.png#Login error state'

Leaving --body off keeps the existing description and appends the attachment — no need to read the body and stitch it back together.

Attach while creating the PR

If the PR doesn't exist yet, don't create it and then edit it — attach in the same call:

gh pr create --title '...' --body '...' --attach './screenshot.png#Login error state'

Control where the images land

If the body references a local path, gh rewrites that reference in place instead of appending, so you can lay images out however you like (alt text then comes from the markdown, not from the flag):

gh pr edit {PR_NUMBER} --body "$(gh pr view {PR_NUMBER} --json body -q .body)

## Screenshots

| Before | After |
| --- | --- |
| ![before](./before.png) | ![after](./after.png) |" \
  --attach ./before.png --attach ./after.png

Two things to keep straight here: --body replaces the description, which is why the existing body is read back in first; and the path string in the body must match the one passed to --attach for the rewrite to fire.

Post as a comment instead

gh pr comment {PR_NUMBER} --attach './result.png#Test run summary'

Same rewrite rule applies with --body, so a comment can carry a layout too.

Videos

mp4 / mov attach the same way and render as a player. Video has no alt text, so don't add a #... suffix for one.

Verify

No browser needed — read the body back and count the attachments:

gh pr view {PR_NUMBER} --json body -q .body | grep -c 'user-attachments/assets'

Path A の注意点

• 添付は追加のみで、置き換えは行われません。 同じコマンドを再実行すると画像が重複します。画像を差し替えるには、新しい画像を添付するコマンドと同時に、古い URL を含まない本文を書き直してください（gh pr edit {PR} --body "$(...)"）。
• ファイル名に # が含まれていると、<file>#<alt> の分割に失敗します。 まず通常の ASCII 名でコピーを作成し（cp './weird #name.png' ./shot.png）、作業後に rm してください。同じ方法で、CleanShot X がファイル名に含める Unicode の細いスペースにも対処できます。
• 一部の処理が失敗しても、成功した分は反映されます。 一部のファイルだけアップロードに失敗した場合、成功したファイルで PR が更新され、PR の URL も出力されますが、終了ステータスはゼロ以外になります。すべて成功するかすべて失敗するかのどちらかだと考えず、出力を確認して失敗したファイルを報告してください。
• 受け付けられるのは画像およびメディアファイルのみです。.zip や .log などの任意の添付ファイルは受け付けられません。

---

Path B — ブラウザーからのアップロード（gh < 2.99.0 の場合の代替手段）

以下はすべて旧方式です。Step 1 でここに案内された場合にのみ使用してください。

古い gh は GitHub の画像ホストにアクセスできないため、この方法では PR のコメント欄をそのホスト用のステージング領域として使用し、そこにファイルをアップロードして永続的な user-attachments/assets/ URL を取得してから、gh CLI で PR の説明を更新するか、コメントを投稿します。

Step B0: PR のコンテキストを解決してファイルをステージングする

ユーザーが PR 番号または URL を指定していない場合は、自動検出します。

# Get PR number from the current branch
gh pr view --json number,url -q '"\(.number) \(.url)"'

複数のリポジトリまたはブランチが関係する場合は、対象とする PR をユーザーに確認してください。

また、画像のパスを絶対パスに正規化し、/tmp/ ではなく、現在の作業ディレクトリ（リポジトリのルート）内にクリーンなコピーをステージングしてください。

# Stage inside the repo. The staged filename becomes the image's alt text on GitHub,
# so give it a meaningful name. Delete it after the upload completes.
cp /path/to/'CleanShot 2026-... .png' ./.upload-staging.png

なぜ /tmp/ ではなくリポジトリ内にステージングするのでしょうか？ MCP ブラウザーツール（Playwright / Chrome DevTools）が読み取れるのは、設定済みのワークスペースルート内のファイルのみです。通常は、セッションの起動元となったプロジェクトディレクトリです。/tmp/ 内のパスはそのルートの外部にあるため、アップロード呼び出しは Access denied: path ... is not within any of the configured workspace roots というエラーで失敗します。リポジトリ内にステージングすれば、どのバックエンドでも動作します（agent-browser や通常の CLI は /tmp/ も読み取れますが、リポジトリ内ならどの環境でも安全です）。

ステージングすることで、特殊文字を含むパス（例：CleanShot X がファイル名に含める Unicode の細いスペース）も回避できます。これらの文字は、シェルのグロブやツールの引数で問題を起こすことがあります。誤ってコミットされないよう、作業後にステージングしたファイルを rm することを忘れないでください。

ツールの検出と選択

優先順位

1. Chrome DevTools MCP（MCP 接続、mcp__chrome-devtools__*）— 推奨：既存のブラウザーに接続し、ログイン状態が保持されます。3 つのバックエンドの中で最も安定しています。
2. Playwright MCP（MCP 接続、mcp__playwright__*）— Chrome DevTools MCP が利用できない場合のみ使用してください。既存のブラウザーに接続し、ログイン状態が保持されます。
3. agent-browser（Bash 経由の CLI — 最後の代替手段。ログイン状態は --profile で保持されます）

MCP ベースのツールはすでに起動しているブラウザーインスタンスに接続するため、GitHub のログイン状態は自動的に保持されます。agent-browser は --profile ~/.agent-browser-github を使ってログイン状態を保持できます。

検出

# 1. Search specifically for Chrome DevTools MCP first (preferred, most stable)
ToolSearch: "select:mcp__chrome-devtools__navigate_page,mcp__chrome-devtools__take_snapshot,mcp__chrome-devtools__upload_file,mcp__chrome-devtools__evaluate_script,mcp__chrome-devtools__click"

# 2. Only if Chrome DevTools MCP tools aren't found, search for Playwright MCP
ToolSearch: "browser navigate upload"

# 3. Fall back to agent-browser only if no MCP tools found at all
Bash: agent-browser --version

ツールの互換性マトリックス

操作	Chrome DevTools MCP（推奨）	Playwright MCP（フォールバック）	agent-browser（CLI/Bash）
移動	navigate_page	browser_navigate	agent-browser --headed open {url}
スナップショット	take_snapshot	browser_snapshot	agent-browser snapshot
スクリーンショット	take_screenshot	browser_take_screenshot	agent-browser screenshot {path}
クリック	click (uid)	browser_click (ref)	agent-browser click {ref}
ファイルのアップロード	upload_file (uid, filePath)	browser_file_upload (paths)	agent-browser upload {ref} {path}
JS の評価	evaluate_script (function)	browser_evaluate (function)	agent-browser eval '{js}'
ログイン状態	維持されます	維持されます	--profile を指定すると維持されます

ステップ B1：PR ページに移動してログイン状態を確認する

PR ページに移動し、すぐにスナップショットを取得してログイン状態を確認します。

// Chrome DevTools MCP (preferred)
navigate_page({ url: "https://github.com/{owner}/{repo}/pull/{number}", type: "url" })

// Playwright MCP (fallback if Chrome DevTools MCP is unavailable)
browser_navigate({ url: "https://github.com/{owner}/{repo}/pull/{number}" })

// agent-browser (last-resort fallback; use --profile to persist login state)
agent-browser --headed --profile ~/.agent-browser-github open "https://github.com/{owner}/{repo}/pull/{number}"

SSO 認証画面が表示された場合： スナップショットを取得し、「Continue」ボタンを見つけてクリックします。

ログインしていない場合（agent-browser のみ）：

1. https://github.com/login に移動します
2. ユーザーに、ヘッド付きブラウザーウィンドウで手動でログインするよう依頼します。
3. ユーザーの確認を待ってから、PR ページに戻ります。

ステップ B2：アップロード先を見つける

PR の一番下にあるコメントフォームまでスクロールし、スナップショットを取得します。

スナップショットはインラインで返すのではなく、ファイルに保存してください。 PR ページのスナップショットは（説明とすべてのレビューコメントを含めると）数百行にもなりやすく、必要なのはその中の uid ひとつだけです。Chrome DevTools MCP の take_snapshot は filePath を受け取れるため、スナップショットをファイルに書き出し、grep でドロップゾーンを探してください。

// Chrome DevTools MCP — write the snapshot out, then grep for the uid
take_snapshot({ filePath: "./.upload-snapshot.txt" })

grep -n "Paste, drop, or click to add files" ./.upload-snapshot.txt
#   549:      uid=3_529 button "Paste, drop, or click to add files"

作業が終わったらスナップショットファイルを削除してください。そうしないと、スナップショットのコストが高すぎるように感じられ、upload_file を使わずに、さらに悪い回避策（画像を base64 として evaluate_script の本文にインラインで埋め込む方法。何千文字もバイト単位で正確に転記する必要があります）を選んでしまうかもしれません。

重要な注意点： GitHub の実際の <input type="file">（id は fc-new_comment_field）は display:none なので、アクセシビリティスナップショットには表示されません。そのため、この方法では uid/ref を取得できず、クリックもできません。代わりに、ファイル選択画面を開く表示されている操作箇所を対象にします。ドロップゾーンの 「Paste, drop, or click to add files」 またはツールバーの 「Attach files」 ボタンです。ブラウザツールでクリックすると、ネイティブのファイル選択画面を捕捉し、ファイルを渡します。

スナップショットでは、次のように表示されます。

button "Attach files"
button "Paste, drop, or click to add files"   ← pass this uid/ref to the upload tool

コメントボックス自体は、<textarea id="new_comment_field"> を内包する <file-attachment> ウェブコンポーネントです。アップロードした画像の参照先は、この textarea に挿入されます（ステップ B4）。GitHub の UI は随時変更されるため、new_comment_field が見つからない場合は、textarea[name="comment[body]"] または textarea[id*="comment"] を使用してください。PR の説明欄のエディターでは、代わりに textarea[name="pull_request[body]"] / textarea[id$="-body"] が使われます。

ステップ B3：画像をアップロードする

検出したツールを使い、ステップ B2 で取得したドロップゾーン／添付ボタンの uidを渡して各ファイルをアップロードします（非表示の input は使用しないでください）。

// Chrome DevTools MCP (preferred): upload_file({ uid: <dropzone uid>, filePath: <path inside the workspace root> })
// Playwright MCP (fallback):       browser_file_upload({ paths: [<path inside the workspace root>] }) once the file chooser is open
// agent-browser (last resort):     agent-browser upload {ref} {absolute_path}    (any path, /tmp/ ok)

MCP バックエンドでは、ステップ B0 で用意したリポジトリー内のパスを使います（ワークスペースのルートに関する注記を参照）。アップロードの間隔は2～3 秒空けてください。画像が複数ある場合は、アップロードのたびに移動するよりも、同じコメントボックスにすべてアップロードしてから URL を抽出するほうが効率的です。

ステップ B4：アップロードした画像の URL を取得する

アップロード中、GitHub はテキストエリアにプレースホルダー（![Uploading file.png…]()）を表示し、ファイルが配置されると最終的な参照に置き換えます。そのため、固定時間待つのではなく、user-attachments/assets/ の URL が現れるまでテキストエリアをポーリングしてください。通常は 1〜5 秒かかります。

GitHub は参照を HTML の <img> タグとして挿入します（width／height は自動検出されます）。例：

<img width="342" height="354" alt="filename" src="https://github.com/user-attachments/assets/8fc1b84a-..." />

![alt](url) 形式の Markdown だと決めつけないでください。どちらの形式でも確実に抽出できるよう、アセット URL 自体に一致させます。

// MCP-based tools — returns every asset URL plus the raw value for sanity-checking
() => {
  const ta = document.getElementById('new_comment_field')
          || document.querySelector('textarea[name="comment[body]"], textarea[id*="comment"]');
  if (!ta) return { error: 'textarea not found' };
  const urls = [...ta.value.matchAll(/https:\/\/github\.com\/user-attachments\/assets\/[0-9a-fA-F-]+/g)].map(m => m[0]);
  return { raw: ta.value, urls };
}

# agent-browser
agent-browser eval 'const ta=document.getElementById("new_comment_field")||document.querySelector("textarea[id*=comment]");JSON.stringify([...(ta?.value||"").matchAll(/https:\/\/github\.com\/user-attachments\/assets\/[0-9a-fA-F-]+/g)].map(m=>m[0]))'

GitHub が自動検出した width／height を保持したい場合は <img …> タグ全体を使います。そうでなければ URL だけを取り出して、自分で ![alt](url) または独自の <img> で囲みます。

ステップ B5：テキストエリアをクリアする（コメントは送信しない）

クリア後に input イベントを発火させて、GitHub のコメント下書きの自動保存もクリアします。そうしないと、次回のページ読み込み時にステージングした内容が再表示されることがあります。

// MCP-based tools
() => {
  const ta = document.getElementById('new_comment_field')
           || document.querySelector('textarea[name="comment[body]"], textarea[id*="comment"]');
  if (!ta) return "textarea not found";
  ta.value = "";
  ta.dispatchEvent(new Event('input', { bubbles: true }));
  return "cleared";
}

# agent-browser
agent-browser eval 'const ta=document.getElementById("new_comment_field")||document.querySelector("textarea[id*=comment]"); if(ta){ta.value="";ta.dispatchEvent(new Event("input",{bubbles:true}))} "cleared"'

ステップ B6：PR に画像を埋め込む

GitHub が提供した <img …> タグ全体（自動検出されたサイズを保持）または通常の Markdown ![alt](url) のどちらかを使って埋め込みます。

オプション A — PR の説明を更新する（既存の本文に画像を追加）：

EXISTING_BODY=$(gh pr view {PR_NUMBER} --json body -q .body)

gh pr edit {PR_NUMBER} --body "$(printf '%s\n\n## Screenshots\n\n%s' "$EXISTING_BODY" '<img width="800" alt="screenshot" src="https://github.com/user-attachments/assets/..." />')"

オプション B — 新しいコメントとして投稿する：

gh pr comment {PR_NUMBER} --body '## Screenshots

<img width="800" alt="screenshot" src="https://github.com/user-attachments/assets/..." />'

ユーザーがコメントを明示的に求めている場合、または PR の説明がすでに長く、コメントにしたほうがすっきりする場合を除き、既定ではオプション A を使います。

ステップ B7：結果を確認する

ページを再読み込みし、スクリーンショットを撮って画像が正しく表示されることを確認します。

画像が実際に読み込まれたことも、プログラムから確認してください。両方の URL 形式に一致させます。表示時に GitHub は user-attachments/assets/... を署名付きの private-user-images.githubusercontent.com URL に書き換えるため、埋め込み時の形式だけを検索すると画像が 0 件と判定され、何も添付されていないように見えてしまいます。

// MCP-based tools — every embedded image plus whether the browser decoded it
() => {
  const imgs = [...document.querySelectorAll('img')]
    .filter((el) => /user-attachments|private-user-images/.test(el.src));
  return imgs.map((el) => ({ alt: el.alt, loaded: el.naturalWidth > 0 }));
}

すべての項目で loaded: true なら、埋め込みは成功しています。配列が空の場合は、<img> タグが本文に追加されていません。ステップ B6 を再確認してください。

ヒント

• 毎回、まずパス A を試してください：gh pr edit --attach／gh pr comment --attach を 1 回実行するだけで、以下のブラウザーセッション全体を置き換えられます。ステップ 1 の条件に該当する場合に限り、パス B を使います。
• 画像サイズ：--attach を使うと、GitHub がサイズを決定します。パス B（またはマークアップを手書きする場合）では、<img width="800" alt="description" src="..." /> でサイズを指定できます。
• 複数の画像：パス A では 1 つのコマンドで --attach を繰り返します。パス B では、すべての画像を同じテキストエリアにアップロードしてから、クリアする前にすべての URL を抽出します。
• パス B では Chrome DevTools MCP を優先してください：最も安定したバックエンドです。まずは ToolSearch から必ず試してください。Chrome DevTools MCP ツールが見つからない場合のみ Playwright MCP に切り替え、MCP ツールがまったく利用できない場合に限り agent-browser に切り替えます。
• agent-browser のログイン状態の保持：セッションをまたいで GitHub へのログイン状態を保持するには、--profile ~/.agent-browser-github を使います。

トラブルシューティング

パス A（gh --attach）

問題	解決策
unknown flag: --attach	gh が 2.99.0 より古い状態です。ユーザーにアップグレードを促し（ステップ 1）、パス B に進みます。
再実行後に画像が重複する	--attach は追加のみを行います。同じ gh pr edit --body ... --attach ... の呼び出しで、古い URL を除いた本文に書き換えます。
アップロードが拒否される／権限エラー	--attach には push アクセスが必要で、GitHub.com と Enterprise Cloud でのみ動作します。パス B に切り替えます。
代替テキストにファイル名が取り込まれる、またはファイルが見つからない	パス内の # は代替テキストの区切りとして解析されます。ASCII 文字のみの名前でコピーを用意し、ステージングします。
一部のファイルはアップロードされたが、コマンドがゼロ以外で終了した	部分的な失敗では想定された動作です。PR には成功したファイルが残ります。失敗したファイルを報告し、それらだけを再試行します。
本文の参照が書き換えられず、代わりに画像が末尾に追加された	本文内のパスは --attach のパス文字列と完全に一致している必要があります。

Path B（ブラウザーでのアップロード）

問題	解決策
ログインしていない（MCP ツール）	SSO 画面が表示される場合があります。スナップショットを取得し、「Continue」ボタンを見つけてクリックしてください
ログインしていない（agent-browser）	--headed モードを使用し、ログインページに移動して、ユーザーに手動でログインしてもらってください
ブラウザーウィンドウが表示されない	agent-browser の場合、--headed フラグが使われていることを確認してください
特殊文字を含むファイルパス（例：CleanShot 由来の Unicode の狭いスペース）	リポジトリ内にわかりやすい名前でコピーを用意してください：cp /path/'CleanShot ... .png' ./.upload-staging.png（MCP ツールが読み取れるよう、リポジトリ内に置いてください。Step B0 を参照）
Access denied: path ... not within any of the configured workspace roots	MCP ブラウザーツールは、ワークスペースルート内のファイルのみ読み取れます。画像は /tmp/ ではなく、リポジトリ内に用意してください（Step B0）
ファイル入力欄の uid/ref が見つからない	<input type="file"> は display:none で、スナップショットに含まれていません。代わりに、表示されている 「Paste, drop, or click to add files」 ドロップゾーンまたは 「Attach files」 ボタンを指定してください（Step B2）
PR ページのスナップショットが非常に大きい／取得コストが高そう	filePath を take_snapshot に渡し、ファイル内でドロップゾーンの uid を grep してください（Step B2）。スナップショットのサイズを理由に、evaluate_script に base64 を直接埋め込まないでください
画像が表示されているのに、検証で画像が 0 件と判定される	GitHub は表示時にアセット URL を private-user-images.githubusercontent.com に書き換えます。これと user-attachments の両方に一致させてから、naturalWidth > 0 を確認してください（Step B7）
テキストエリアにファイルはあるが、 の Markdown がない	GitHub は画像に Markdown ではなく <img …> HTML タグを挿入します。両方の形式に一致する Step B4 の正規表現で user-attachments/assets/ の URL を抽出してください
テキストエリアに URL がまだない	GitHub は最初に ![Uploading…]() プレースホルダーを表示します。固定時間待つのではなく、user-attachments/assets/ の URL が現れるまでテキストエリアをポーリングしてください（1～5 秒）
テキストエリアのセレクターが見つからない	GitHub UI は時折変更されます。new_comment_field → textarea[name="comment[body]"] → textarea[id*="comment"] の順にフォールバックしてください（Step B2）
Chrome DevTools MCP の接続が切断された	/mcp コマンドで再接続してください
agent-browser が見つからない	npm install -g agent-browser && agent-browser install
ブラウザーツールが見つからない	ToolSearch を使って、利用可能なブラウザーツールを検索してください
PR が見つからない／404	非公開リポジトリは、認証されていないユーザーに対して 404 を返します。ログイン状態を確認してください

注意事項

• gh --attach は GitHub CLI 2.99.0（2026-09）で、gh pr create／pr edit／pr comment および対応する gh issue create／issue edit／issue comment に追加されました。1 コマンドにつき最大 50 ファイルを添付でき、同じファイルを 2 回添付することはできません
• gh pr edit --attach を --body なしで実行すると、既存の説明は維持され、添付が追加されます。配置を制御したい場合にのみ、読み取り・変更・書き込みの手順が必要です
• GitHub の user-attachments/assets/ URL は永続的です。コメントを送信しなくても、画像には引き続きアクセスできます。表示時に GitHub は URL を private-user-images.githubusercontent.com CDN URL に書き換えますが、埋め込みには user-attachments/assets/... 形式の安定した URL を使用してください
• Path B でアップロードすると、GitHub は ![](…) Markdown ではなく、<img width=… height=… alt=… src=… /> タグを挿入します（alt はファイル名から生成されます）。ラッパーではなく、アセット URL を使って抽出してください
• MCP ブラウザーツールはワークスペースルート内のアップロードファイルしか読み取れないため、画像は /tmp/ ではなくリポジトリ内に用意してください
• GitHub UI の構造変更により、ブラウザー UI から説明を直接編集する方法は不安定です。gh pr edit による更新を強く推奨します
• MCP ベースのツールは既存のブラウザーインスタンスに接続するため、Cookie とログインセッションが維持されます