GitHub CLIで画像・動画を添付できた。gh 2.99.0の「--attach」を試す

GitHub CLIのghでは、IssueやPull Requestへ画像・動画を添付できない。ずっとそう思っていました。自分用のpr-media-attachというスキルにも、Chromeを操作して動画を貼る長い手順を書いていました。

2026年9月7日にその手順を見直したところ、公式の--attachが増えていました。手元のPR本文へ変更前・変更後のMP4を2本送る作業は、次の1コマンドで終わりました。

gh pr edit 10577 --body-file /tmp/pr-body.md \
  --attach /tmp/recordings/before.mp4 \
  --attach /tmp/recordings/after.mp4

これは以前からあった機能を見落としていたわけではありません。GitHubの公式発表は2026年9月1日で、必要なGitHub CLIはv2.99.0以降。見つけた時点で公開からまだ1週間も経っていない新機能でした。

いちばん短い使い方

画像や動画のパスを--attachへ渡します。本文を書かなくても、添付したファイルが末尾へ追加されます。

# Issueへスクリーンショットをコメント
gh issue comment 123 --attach ./screenshot.png

# PR本文へ動画を追加
gh pr edit 456 --attach ./demo.mp4

# 複数ファイルはオプションを繰り返す
gh pr comment 456 \
  --body "変更前と変更後です" \
  --attach ./before.png \
  --attach ./after.png

使えるのは、IssueとPRの「作成」「編集」「コメント」に対応する6コマンドです。

GitHub CLIを更新しても見当たらないときは、まずバージョンを確認します。

gh --version
gh pr edit --help | grep attach

今回作業した端末の一つにはv2.91.0が残っており、当然そこでは使えませんでした。OSのパッケージ管理やGitHub CLI v2.99.0のリリースから更新が必要です。

本文中のローカルパスを、アップロード後のURLへ置き換えてくれる

--attachは、単にファイルを末尾へ足すだけではありません。本文のMarkdownが同じローカルファイルを参照していれば、その場所をアップロード後のURLへ自動で書き換えます。

たとえばPR本文を次のようにローカルで用意します。

## 変更前

![](/tmp/recordings/before.mp4)

## 変更後

![](/tmp/recordings/after.mp4)

このファイルを--body-fileで渡し、同じ2ファイルを--attachにも指定すると、見出しの位置はそのままでローカルパスだけがgithub.com/user-attachments/...のURLへ変わります。動画はURLが段落に単独で置かれ、その場で再生できるプレーヤーになります。

画像の代替テキストは、パスの後ろに#で続けても指定できます。

gh issue comment 123 \
  --attach './login-error.png#ログイン画面に表示されたエラー'

省略時はファイル名が代替テキストになります。動画プレーヤーには代替テキストの仕組みがないため、動画へ#説明を付けることはできません。動画の内容は前後の本文で説明するのがよさそうです。詳しい置換規則はGitHub CLIの添付ファイル公式ドキュメントにまとまっています。

リポジトリ／アカウントの総容量は「非公表」

GitHubのプラン別の利用量表には、Actions、Codespaces、Packages、Git LFSのストレージ枠が数値で載っています。しかし、Issue・PRの添付ファイル（user-attachments）は項目自体がありません。課金APIの製品／SKU一覧にも該当するメーターは見当たりませんでした。

つまり、FreeとProで確認できる差は動画1ファイルあたりの上限です。添付全体でFreeは何GB、Proは何GBという説明ではありません。GitHub内部に不正利用防止や運用上の制限が存在しない、とも断言できません。

リポジトリ容量やGit LFSとは別物

添付はコミットされるGitオブジェクトではないため、少なくともリポジトリの.git容量やcloneサイズを膨らませるものではありません。一方で、残量メーターや総容量の保証も公式には案内されていません。PRの動作証拠には便利ですが、バックアップ先や動画置き場として容量を当てにする使い方は避けたほうが安全です。

1ファイルと1コマンドの制限

gh --attachの対応形式は、画像がPNG、JPG、JPEG、GIF、WebP、SVG、動画がMP4、MOV、WebMです。1回のコマンドで指定できるのは最大50ファイルで、同じファイルを重複して添付することはできません。画像は10MB、動画は100MBを超えるとCLI側で拒否し、Freeプランの動画はサーバー側の10MB制限を受けます。

一般的なZIP、PDF、ログファイルなどは、Web画面の添付では扱えても今回のgh --attachの対象ではありません。名前の印象より範囲は狭く、画像と動画専用です。

使えないケースもある

• •リポジトリへの書き込み権限が必要。ブラウザからIssueを投稿できる外部ユーザーでも、READやTRIAGE権限だけではCLI添付を使えません
• •GitHub Enterprise Serverはv2.99.0時点で非対応。GitHub.comとGitHub Enterprise Cloudが対象です
• •標準入力は添付できない。画像生成コマンドなどの出力も、いったん通常ファイルとして保存してパスを渡します

認証は普段のgh auth loginで使うOAuthトークンやPersonal Access Tokenに対応します。権限が足りない場合は、ファイルだけが送られて本文に反映されない状態を避けるため、CLIがアップロード前に止めます。

Chrome操作の長い手順が、1コマンドになった

以前はGitHubのWeb画面を開き、ログイン済みブラウザでファイル入力を探し、アップロード後のURLを本文へ戻す必要がありました。特にコーディングエージェントから使うと、ブラウザ接続の有無だけで作業が止まります。

今回、実際のPRへ2本のMP4を貼ってから、自分のdotfilesにある添付スキルを更新しました。Chrome拡張を前提にしていた長い手順は、画像・動画の用意、Markdownの組み立て、gh pr edit --attach、表示確認という短い流れになりました。

UI変更のPRでは「直しました」と書くより、変更前と変更後の動画を並べたほうがレビューが速くなります。Issueの再現手順も同じです。人がブラウザで行っていた最後の添付作業まで、CLIだけで完了できるようになったのが、この機能のいちばん大きな価値でした。

参照元

• ▸GitHub Changelog - GitHub CLI: Media in issues, pull requests, and comments（2026年9月1日）
• ▸GitHub Docs - Attaching files with GitHub CLI
• ▸GitHub Docs - Attaching files（Web／CLI共通の1ファイル上限）
• ▸GitHub Docs - Product usage included with each plan
• ▸GitHub Docs - GitHub Product and SKU names
• ▸GitHub Docs - Repository limits
• ▸cli/cli - GitHub CLI 2.99.0 release notes
• ▸cli/cli Issue #14186 - --attach stack map