GitHub CLI で画像・動画を添付できるようになった｜v2.99.0 の --attach の使い方と制限

スクリーンショットを貼るためだけにブラウザを開かなくてよくなりました

GitHub CLI v2.99.0 で --attach フラグが追加されました。2026 年 9 月 1 日のリリースです。ローカルにある画像や動画をアップロードし、issue・pull request・コメントの本文へそのまま埋め込めます。

これまで gh から渡せたのはテキストだけでした。バグの再現画面を 1 枚貼りたいだけでも、ブラウザで対象の issue を開き、コメント欄へファイルをドラッグ & ドロップして user-attachments の URL を発行し、その URL を本文に書く、という手順を踏む必要がありました。ターミナルで issue を立てる習慣がある人ほど、画像のところだけブラウザへ寄り道することになっていたはずです。

この記事では --attach が使えるコマンド、書き方、対応形式とサイズの上限、そして AI コーディングエージェントの作業で何が変わるかを扱います。gh の導入やログインから始める場合は、先に GitHub CLI (gh) の基本操作を読んでから戻ってきてください。

--attach が使える 6 つのコマンド

--attach に対応したのは、issue 側と pull request 側にそれぞれ 3 つずつ、合わせて 6 つのコマンドです。

作成・編集・コメントがすべて揃っているため、「作るときに貼り忘れたので後から足す」も「レビュー中に画面を貼る」も、どちらもターミナルで完結します。

使い方

1. issue を作りながら画像を添付する

いちばん短い形は、パスを 1 つ渡すだけです。

gh issue create \
  --title "ログイン後にヘッダーが二重に描画される" \
  --body "再現手順と実際の表示を添付します。" \
  --attach ./screenshots/header-duplicated.png

本文が添付ファイルを参照していない場合、画像への参照は本文の末尾に追記されます。上の例なら、説明文の下に画像が続く形になります。

2. 本文の中の好きな位置に画像を置く

本文が、--attach に渡すのと同じローカルパスを既に参照していれば、追記ではなく、その場所の参照がアップロード後の URL に書き換わります。公式ドキュメントは「rewrites the reference in place」と説明しています。位置を自分で決めたいときはこちらを使います。

gh issue create \
  --title "ログイン後にヘッダーが二重に描画される" \
  --body "$(cat <<'EOF'
## 再現手順
 
1. ログインする
2. トップページへ遷移する
 
## 実際の表示
 
![](./screenshots/header-duplicated.png)
 
## 期待する表示
 
ヘッダーは 1 つだけ描画される。
EOF
)" \
  --attach ./screenshots/header-duplicated.png

この書き方の利点は、投稿する前に手元で本文を確認できることです。ローカルの Markdown プレビューでそのまま画像が見えるため、貼る位置を決めてから gh に渡せます。

3. 代替テキストを付ける

パスの後ろに # を付けて続けると、その文字列が代替テキストになります。

gh issue create \
  --title "ログイン後にヘッダーが二重に描画される" \
  --body "再現画面を添付します。" \
  --attach './screenshots/header-duplicated.png#ヘッダーが 2 段に重なった状態'

指定しなかった場合はファイル名がそのまま代替テキストになります。IMG_0421.png のような名前のまま貼ると読み手には何も伝わらないため、他人が読む issue では書いておいたほうが親切です。

本文が ![ヘッダーが 2 段に重なった状態](./screenshots/header-duplicated.png) のように代替テキストごと参照している場合は、本文に書いた側が使われます。gh issue create --help (v2.100.0) は「A reference already in the body keeps the alt text written there.」と説明しています。本文で書き終えているなら、--attach には # を付けずパスだけ渡せば済みます。

動画には代替テキストを付けられません。プレイヤーとして描画される都合で、代替テキストを持たない形になるためです (gh issue create --help の記述)。# を付けて渡す先は画像だけだと考えてください。

4. 複数のファイルを添付する

フラグを繰り返します。同じファイルを 2 回添付することはできません。

gh pr comment 128 \
  --body "$(cat <<'EOF'
配色の変更前と変更後です。
 
![変更前の配色](./shots/before.png)
 
![変更後の配色](./shots/after.png)
EOF
)" \
  --attach ./shots/before.png \
  --attach ./shots/after.png

本文の側に代替テキストを書いているため、--attach には # を付けずパスだけ渡しています。前の節のとおり、本文が代替テキストごと参照している場合は本文側が使われるので、# を付けても無視されます。

5. 既存の issue に後から貼る

作成済みの issue にコメントとして足す場合も同じです。番号を渡します。

gh issue comment 42 \
  --body "同じ手順で再現しました。" \
  --attach ./screenshots/reproduced-again.png

本文そのものを直したいなら gh issue edit を使います。

6. 動画を貼る

動画も同じフラグで渡せます。ただし本文中に置くときの書き方に条件があります。

gh pr comment 128 \
  --body "$(cat <<'EOF'
操作の記録です。
 
![](./recordings/checkout-flow.mp4)
EOF
)" \
  --attach ./recordings/checkout-flow.mp4

GitHub Docs は、動画への参照がプレイヤーとして表示されるには、その参照が段落の中で唯一の内容である必要があると説明しています。文章と同じ行に混ぜると、プレイヤーではなくリンクとして表示されます。上の例のように、動画の参照だけを 1 段落として空行で挟んでください。

対応形式・サイズ・件数の制限

制限は次のとおりです。

自社が GitHub Enterprise Server を運用している場合、gh を最新にしても --attach は使えません。Changelog には「GitHub Enterprise Server is not supported in this release」と書かれています。

サイズの上限に引っかかりやすいのは動画です。画面収録は数十秒でも 10MB を超えることがあり、無料プランのアカウントでは弾かれます。長さを切り詰めるか、解像度とフレームレートを落として再エンコードするかの判断が要ります。GIF へ変換する手は使えません。GIF の上限も同じ 10MB なうえ、同じ尺・同じ解像度なら MP4 より大きくなるためです。

一部の添付が失敗しても issue は作られます

添付を複数渡したとき、全部そろわなければ投稿されない、という動きにはなりません。gh issue create --help (v2.100.0) は次のように説明しています。

If some attachments upload and others fail, the issue is still created with the ones that succeeded. The command then exits with a non-zero status, but the new issue's URL is still printed to stdout.

成功した添付だけを含む issue が作られ、コマンドの終了ステータスは非ゼロになり、作られた issue の URL は stdout に出力されます。3 つが同時に起きる点が扱いにくくなっています。

スクリプトや CI から呼ぶなら、ここで処理を決めておいてください。終了ステータスだけを見て失敗と判断し、そのままリトライすると issue が 2 つできます。逆に stdout の URL だけを見て成功と判断すると、貼ったつもりの画像が欠けたまま次へ進みます。終了ステータスと URL の両方を受け取り、非ゼロなら「issue は作られているが添付が欠けている」と読むのが安全です。

この記事の PR で実際に試した結果

書いた内容を、この記事を追加する Pull Request そのもので確かめました。使ったのは gh 2.100.0 です。検証は 2 回に分けており、1 回目が gh pr create --attach で記事のキービジュアル 2 枚を PR 本文へ、2 回目が gh pr comment --attach で同じ PR のコメントへ貼る形です。

1 回目で確認できたのは、本文のローカルパスが URL に置き換わることです。本文に ![説明](./content/tips/covers/github-cli-gh-basics.webp) と書いた状態で、--attach に同じパスを渡しました。投稿後に gh pr view --json body で読み直すと、参照先が https://github.com/user-attachments/assets/ で始まる URL に変わっていました。末尾に画像が重複して追記されることもありませんでした。

2 回目のコメントでは、代替テキストの扱いを 2 つ確かめました。1 つ目は、代替テキストは本文側が勝つという点です。本文に ![本文側に書いた代替テキスト](./path.webp) と書き、フラグには --attach './path.webp#フラグ側に書いた代替テキスト' と別の文字列を渡しました。投稿後に残ったのは本文側の文字列で、フラグに渡した文字列は捨てられています。help の記述どおりの動きです。

2 つ目は、本文が参照していない添付が末尾に足されるという点です。同じコマンドでもう 1 枚、本文からいっさい参照していないファイルを渡したところ、コメントの末尾に独立した段落として ![フラグに渡した代替テキスト](URL) の形で追加されました。本文に参照が無いので、こちらはフラグ側の代替テキストが使われます。

3 つの確認とは別に、副産物の発見が 1 つありました。同じファイルでも、コマンドを分けて渡すと別の URL が発行されます。同一の画像を PR 本文とコメントで 1 回ずつ添付したところ、割り当てられた識別子は異なりました。アップロード済みのファイルを使い回す動作は確認できなかったため、同じ画像を複数箇所で使うなら、1 度貼って得た URL を自分で控えておくほうが無駄がありません。

AI コーディングエージェントが画面つきで報告できるようになります

この変更が意味を持つのは、人間が手でスクリーンショットを貼る場面だけではありません。Claude Code や Codex のようなコーディングエージェントが、自分の作業結果を画像つきで報告できるようになります。

エージェントはこれまでも、ブラウザ操作や E2E テストの過程でスクリーンショットを撮っていました。ただし撮ったファイルはローカルに残るだけで、エージェント自身が pull request へ載せる手段はありませんでした。載せるには人がブラウザを開いてドラッグ & ドロップするか、画像を置く先を別に用意する必要があり、そこで作業がターミナルの外へ出ていました。

gh pr comment --attach が使えると、この流れがコマンドだけで完結します。

flowchart LR
  A["エージェントが UI を変更"] --> B["ブラウザ検証・E2E で<br/>スクリーンショットを取得"]
  B --> C["gh pr comment --attach<br/>で PR へ投稿"]
  C --> D["レビュー担当が<br/>差分と画面を同時に見る"]

具体的な形としては、変更前と変更後の 2 枚を並べたコメントを PR に残す使い方が分かりやすいところです。実装の差分を読むだけでは「見た目がどう変わったか」は分かりませんが、画面が並んでいれば一目で判断できます。代替テキストにそれぞれ「変更前」「変更後」と書いておけば、順番の取り違えも防げます。

見落としやすいのは権限です。エージェントに gh を使わせる場合、そのトークンには添付先リポジトリへの push 権限が必要になります。issue への書き込みだけを許可し、リポジトリの内容を読み取りのみにしたトークンで運用していると、コメントは投稿できても添付だけが失敗します。エージェントに与える権限の設計そのものは Claude Code を CI に組み込むでも扱っています。

あわせて、一部の添付が失敗したときの終了ステータスの扱いも、エージェントに渡す手順へ書いておいてください。エージェントは非ゼロで終了したコマンドを失敗とみなして同じコマンドを組み直すことがあり、そのまま作り直すと同じ内容の issue や PR が並びます。非ゼロなら投稿は済んでいるものとして扱い、gh issue edit --attach や gh pr edit --attach で足りない添付だけを補う、という順番を先に決めておくと余計な重複が出ません。

画像をやり取りする向きが両方そろった点も押さえておきたい変化です。人がエージェントへ画面を見せる側は Copilot Vision の正式提供などで既に整っていました。今回そこに、エージェントが人へ画面を見せる経路が加わりました。レビューの往復で「言葉だけで画面を説明する」場面が減ります。

FIXIT

エージェントが自分でスクショを貼れるって、そんなに大きい話なの？

Tsumiki

大きいです。手元で試すと、PR に貼るところまで手が離れませんでした。

FIXIT

でも、見せちゃいけない画面まで貼られたら困らない？

Tsumiki

公開リポジトリだと誰でも見られます。撮る対象を先に絞っておくのが早いです。

同じ時期に入ったほかのアップデート

v2.99.0 と、その 1 つ前の v2.98.0 には、エージェントと並行作業に関わる変更も入っています。--attach を目当てに更新すると、あわせて使えるようになります。

worktree 系の 2 つは、複数のエージェントを同時に走らせている環境で意味を持ちます。同じ作業ディレクトリを取り合わずに、issue や PR ごとに独立した作業場所を切り出せます。

FIXIT の運用 — レビューでは差分と画面の両方を見ます

FIXIT では、UI に手が入った pull request について、コードの差分だけで可否を決めない運用にしています。実際に描画された画面を見て、意図した見え方になっているかを確かめてから通します。AI が書いたコードでもこの手順は変えません。差分の上では妥当に見える変更が、実際の画面ではレイアウトを崩していることがあるためです。

--attach が入ったことで、画面を PR まで運ぶ経路が短くなりました。これまで手順の中に混ざっていたブラウザでの貼り付け作業が、コマンド 1 本に置き換わります。作業が減ること自体より、経路が短くなったぶん「画面を貼らずに済ませる」判断が起きにくくなる点のほうが実務では大きいところです。

なお、公開リポジトリの添付が認証無しで見られる点は、社外へ出す前提の運用ルールとして先に共有しています。何を撮ってよいかを決めておかないと、貼れるようになった分だけ事故の機会も増えます。AI にレビューを任せる範囲の決め方は AI コードレビューの設計にまとめています。

まとめ

GitHub CLI v2.99.0 の --attach で、issue・pull request・コメントへローカルの画像や動画をコマンドラインから添付できるようになりました。対応するのは issue と pull request の作成・編集・コメントの 6 コマンドです。本文が既にローカルパスを参照していればその場所が書き換わり、参照が無ければ末尾に追記されます。代替テキストはパスの後ろに # を付けて指定します。

制限として押さえておくのは次の 4 点です。

• 画像と GIF は 10MB まで、動画は無料プランで 10MB まで・有料プランで 100MB まで
• 1 回の実行で添付できるのは 50 ファイルまで
• 添付先リポジトリへの push 権限が必要
• GitHub Enterprise Server はこのリリースでは対象外

スクリプトや CI から呼ぶなら、これに終了ステータスの扱いが加わります。添付の一部だけが失敗した場合、issue や PR 自体は、成功した添付を含む形で作られたうえで、終了ステータスが非ゼロになります。失敗とみなして作り直すと同じ内容が 2 つできるため、非ゼロなら添付を足し直す側へ倒してください。

まず gh --version でバージョンを確かめ、v2.99.0 に届いていなければ更新してください。そのうえで、次に立てる issue のスクリーンショットを 1 枚 --attach で貼ってみるのが手の速い試し方です。

AI コーディングエージェントを実務のレビューまで含めて組み込みたい場合は、AI 開発ツール導入支援で運用の設計から伴走しています。ご相談は お問い合わせからご連絡ください。