GitHub CLIの`--attach`で画像・動画を添付する方法【Issue・PR対応】

GitHubは2026年9月1日、GitHub CLIから画像・動画を添付する--attachフラグの一般提供を発表しました。v2.99.0で導入された機能で、IssueやPull Request（PR）、コメントにローカルファイルを添付できます。(The GitHub Blog)

対応するコマンドと利用条件

--attachは、gh issueとgh prそれぞれのcreate・edit・commentで使えます。新規作成時だけでなく、既存のIssueやPRにも画像や動画を追加できます。(GitHub Docs)

対象はGitHub.comとGitHub Enterprise Cloudです。今回のリリースでは、GitHub Enterprise Serverには対応していません。また、添付先リポジトリへの書き込み権限が必要です。認証方式としては、gh auth loginによるOAuthトークン、またはPersonal Access Token（classic）が案内されています。(The GitHub Blog)

まず、バージョンと認証状態を確認します。

gh --version
gh auth status

未認証の場合は、次のコマンドでログインします。gh auth loginは、標準ではブラウザを使って認証します。(GitHub CLI)

gh auth login --hostname github.com

以下のコードはBash形式の独立した使用例です。OWNER/REPO、PR番号、ブランチ名、ファイル名は実際の値に置き換えてください。投稿用のコマンドを実行すると、GitHub上にIssueやPR、コメントが作成・更新されます。

スクリーンショット付きのIssueを作成する

ログイン時の不具合を画像付きで報告する例です。

gh issue create \
  --repo OWNER/REPO \
  --title "ログイン後にエラー画面が表示される" \
  --body "ログインフォームを送信すると、添付画像の状態になります。" \
  --attach './login-error.png#ログイン後に表示されたエラー画面'

--attachには、ローカルファイルのパスを指定します。パスの後ろに#で説明を付けると、画像の代替テキストになります。省略した場合はファイル名が使われます。(GitHub CLI)

この例では、本文中に画像の配置場所を指定していないため、画像は本文の末尾に追加されます。(GitHub CLI)

修正前・修正後の画像を、本文の好きな位置に置く

「修正前」「修正後」の見出しの下に画像を置く場合は、Markdown本文にローカル画像のパスを書き、同じファイルを--attachでも指定します。GitHub CLIが本文中の参照をアップロード先URLに置き換えるため、画像の位置を保ったまま投稿できます。(GitHub Docs)

まず、次の内容をpr-body.mdとして保存します。

## 変更内容

画面幅が狭いときに、ログインボタンがはみ出す問題を修正しました。

### 修正前

![修正前：ボタンが画面からはみ出している状態](./before.png)

### 修正後

![修正後：ボタンが画面内に収まっている状態](./after.png)

pr-body.md、before.png、after.pngを同じディレクトリに用意し、そのディレクトリで次のコマンドを実行します。

ここでは、fix/login-layoutブランチを同じリポジトリにpush済みとします。--headには変更を含むブランチ、--baseにはマージ先のブランチを指定します。(GitHub CLI)

gh pr create \
  --repo OWNER/REPO \
  --base main \
  --head fix/login-layout \
  --title "ログイン画面の表示崩れを修正" \
  --body-file ./pr-body.md \
  --attach ./before.png \
  --attach ./after.png

Markdownにパスを書くだけではアップロードされません。 添付するファイルは--attachにも指定します。本文に代替テキストを書いている場合は、その内容が維持されます。(GitHub Docs)

既存のPRに動画付きコメントを投稿する

画面遷移や操作手順を伝える場合は、動画を添付できます。次は、PR番号456に操作動画付きのコメントを投稿する例です。(GitHub CLI)

gh pr comment 456 \
  --repo OWNER/REPO \
  --body "ログインから画面遷移までの操作動画を添付します。" \
  --attach ./login-demo.mp4

動画はプレーヤーとして表示されます。画像と異なり、動画には#による代替テキストを指定できません。何を確認するための動画なのかは、コメント本文に書きます。(GitHub CLI)

コメントではなく、PRの説明欄に画像を追加する場合は、gh pr editを使います。(GitHub CLI)

gh pr edit 456 \
  --repo OWNER/REPO \
  --attach './after.png#修正後のログイン画面'

--bodyや--body-fileで新しい本文を指定しなければ、既存の本文を残したまま添付を追加できます。(GitHub CLI)

対応形式とサイズ制限

公式発表に挙げられている対応形式は、PNG・JPEG・GIF・WebP・SVG・MP4・MOV・WebMです。(The GitHub Blog)

今回の--attachは画像・動画向けの機能です。ブラウザから添付できるPDFやZIPなどは、対象に含まれません。(GitHub Docs)

ファイルサイズの上限は、次のとおりです。動画の上限は、添付先リポジトリの所有者のプランによって変わります。(GitHub Docs)

種類	ファイルサイズ上限
画像・GIF	10MB
無料プランのユーザー・組織が所有するリポジトリへの動画	10MB
有料プランのユーザー・組織が所有するリポジトリへの動画	100MB

有料プランのリポジトリに10MBを超える動画をアップロードする場合は、投稿者が組織メンバーまたは外部コラボレーターであるか、投稿者自身が有料プランを利用している必要があります。(GitHub Docs)

また、1コマンドで添付できるのは最大50ファイルです。(GitHub CLI)

自動化では再実行による重複投稿に注意

複数の添付のうち一部だけアップロードに失敗した場合、成功した添付を含むIssueやPRが作成されることがあります。この場合、終了コードは非ゼロになりますが、作成されたIssueやPRのURLは標準出力に返されます。(GitHub CLI)

つまり、終了コードが非ゼロでも、投稿されていないとは限りません。 この仕様上、終了コードだけを見てgh issue createやgh pr createを再実行すると、重複投稿につながる可能性があります。(GitHub CLI)

スクリプトに組み込む際は、標準出力とエラー内容を保存し、投稿が作成済みか確認してから再試行します。作成済みなら、新しいIssueやPRを作るのではなく、失敗した添付だけを既存の投稿に追加する処理に分けます。

添付ファイルの内容にも注意が必要です。公開リポジトリにアップロードしたファイルは、認証なしで閲覧できます。スクリーンショットや動画に、メールアドレス、アクセストークン、顧客情報などが映り込んでいないか、投稿前に確認してください。(GitHub Docs)

出典

GitHub Changelog「GitHub CLI: Media in issues, pull requests, and comments」（2026年9月1日）。(The GitHub Blog)

GitHub Docs「Attaching files with GitHub CLI」「Attaching files」。(GitHub Docs)

GitHub CLI公式マニュアル：gh auth login、gh issue create、gh pr create、gh pr comment、gh pr edit。(GitHub CLI)