github-screenshots

GitHub の PR と issue にスクリーンショットや録画を添付する

これが必要な理由

GitHub のネイティブ画像ホスティング（github.com/user-attachments/…）にはブラウザーからアクセスできます。また、GitHub CLI 2.99（2026 年 9 月）以降は、gh issue|pr create|edit|comment --attach <file> からも利用できます。ただし、現在も公開 REST エンドポイントはなく（CLI はドキュメント化されていないアップロードホストを使用します）、アップロードには push アクセスが必要で、ホストされたファイルは GitHub 内でのみ公開されます。gh … --body-file で記述した PR／issue の本文にほかの画像 URL を含める場合は、すでに公開ホスティングされている URL を指定する必要があります。uploads CLI と https://agents.uploads.sh/mcp のホスト型 MCP は、どちらも uploads.sh にファイルをホストし、安定した公開 URL と、そのまま貼り付けられる Markdown を返します。

gh --attach で十分な場合

次の条件をすべて満たす場合は、gh pr comment --attach ./shot.png（または create／edit）をそのまま使用します。

• gh --version が 2.99 以降で、リポジトリへの push アクセスがある。
• PR または issue がすでに存在するか、同じコマンドで作成する。
• ファイルが 10 MB 未満の画像または動画である（有料プランでは動画は最大 100 MB）。 gh --attach で添付できるのはメディアのみです。
• GitHub の外部でリンクを使う必要がない。user-attachments の URL は Slack、ドキュメント、その他のツールでは表示されず、ほかのエージェントも取得できません。

代わりに、次のいずれかに該当する場合は uploads.sh を使用します。

• 成果物がメディアではない。Lighthouse やテストのレポート、ログ、JSON、PDF、zip などです。gh --attach では添付できませんが、uploads put では添付でき、管理対象のコメントからリンクされます。
• PR がまだ存在しない。ブランチで uploads put を使って準備すると、PR が開かれたときに添付ファイルのコメントが表示されます。
• スクリーンショットを撮り直す予定がある。同じファイル名なら URL も同じになり、管理対象のコメントがその場で更新されるため、コメントが積み重なりません。
• キャプチャにメタデータ（--meta）、後からの取得（uploads find）、またはプロジェクト横断の Screenshots ビューが必要である。
• URL を GitHub の外部でも機能させる必要がある。
• シェルを使えないホスト型 MCP を利用している、push アクセスがない、またはリポジトリが GitHub Enterprise Server 上にある。

コメント履歴を読みやすく保つため、1 つの PR で両方を併用しないでください。どちらか一方を選んでください。 gh で添付したメディアも引き続きインデックスに登録されます。GitHub App は、PR と issue の本文から添付ファイルをワークスペースにインポートします。同じ Webhook が、その本文に含まれる公開 Cursor の cursor.com/artifacts/c/art-* リライト URL もインポートします。既存の user-attachments 画像または art-* URL を手動でミラーするには、uploads ingest を使用します。

使用するインターフェース

トランスポートを1つ選び、途中で切り替えないでください。このスキルではワークフローを扱います。フラグとMCPツールの契約については、uploads-cliスキルを参照してください。

使用環境	使用するもの
シェルを利用できない（ChatGPT、またはチェックアウトのないホスト）	ホスト型MCPのputに（contentBase64 + filename、またはcontentUrl）+ repo + (prまたはbranch)を指定します。URLのパスに末尾のファイル名が含まれていれば、contentUrlでのファイル名は省略できます。返されたmarkdown / embedUrlを埋め込んでください。uploads attach ./shot.pngを実行できると示唆してはいけません。
シェルとホスト型MCPは利用できるが、uploadsバイナリはない（クラウドサンドボックス）	ホスト型MCPのsign_upload_urlにfiles: [{ filename }] + repo + (prまたはbranch)を指定し、その後、返された各curl行を実行します。各レスポンスにはmarkdownが含まれます。prを指定した場合は、すべてのアップロード後にcommentを1回呼び出してください。プロキシで403が返された場合は、agents.uploads.shを許可するよう依頼するか、putを使用してください。
チェックアウトとuploadsバイナリがある	以下のCLIの例を使用します。Gitでrepo / branchを取得できます。
localhostのページ、またはセレクターの注釈付け	CLIのみ（uploads screenshot --via local）です。リモートレンダラーからはお使いのマシンにアクセスできません。
MCPもCLIも利用できない	そこで中止し、その旨を伝えてください。npm install -gをChatGPTでの利用方法として扱ってはいけません。

ホスト型MCPにはattachツールがなく、サーバーにGitはありません。チェックアウトがある場合は、repo（git remote get-url origin）とbranch （git branch --show-current）を確認し、すべての呼び出しで両方を渡してください。branchと repoを指定すると、リポジトリがワークスペースにリンクされていて、オープン中のPRがちょうど1件ある場合、サーバーはそのブランチのPRに添付します。それ以外の場合はステージングします。PRの作成後は、repo + pr + branchを指定してpromoteするか、pr + repoを指定してputしてください（branchも任意で指定するとプロモートします）。repoを指定しない場合、ファイルはGitHubへのリンクなしでmisc/に保存されます。管理対象のコメントを投稿できるのは、そのサーバー上のボットのみです。

ステップ 1 — ビジュアルをキャプチャする

ビジュアルがすでにコンテキスト内にある場合（ChatGPT の添付ファイル、ホストがすでに保持しているファイル）は、このステップをスキップしてください。そのままホスト MCP の put に進みます。

uploads screenshot <url|file.html> を優先してください — キャプチャとホストを 1 ステップで行います（ローカルの Chrome を操作するか、サーバー側のレンダリングにフォールバックします）。そのため、別途ホストを呼び出す必要がありません。--viewport WxH@Nx、--wait、--selector、--full-page、--out <file>（PNG も保存する場合）を指定できます。

自分の開発サーバーをキャプチャする場合でも、DOM を手動で操作する必要はありません。

• 既知のフレームワーク開発ツールバー（Astro/Next/Nuxt/Vite）は自動的に非表示になります — 無効にするには --no-hide-dev-tools を指定します。
• --reduced-motion でアニメーションが落ち着きます。
• --hide <selector> でその他のオーバーレイを非表示にできます（繰り返し指定可能）。
• --eval <js> / --init-script <file>（ローカルバックエンド）は、バナーを閉じたり特定のアニメーションを停止したりするための手段です。

React/Next（またはその他のハイドレーションを行う）アプリのクリック／選択状態をキャプチャする場合はどうでしょうか？ --eval 内の合成 el.click() は、フレームワークのハイドレーションが完了する前に実行されます — 要素は SSR HTML にありますが、まだハンドラーがアタッチされていないため、何も起こらずに終わります。アプリ独自の「インタラクティブ」シグナルを --wait-for <js>（ローカルバックエンド）で待機します。これは、--eval が実行される前に、その式が真になるまでポーリングします。

uploads screenshot http://localhost:3000 --via local \
  --wait-for 'document.querySelector("[data-hydrated]")' \
  --eval 'document.querySelector(".tab-settings").click()' --out settings.png

uploads screenshot http://localhost:4321 --viewport 1520x960@1x --out home.png --reduced-motion
uploads screenshot https://uploads.sh --selector main --dark

--out は PNG の隣に <file>.uploads.json サイドカーファイルも作成します — これは後で put/attach する際にメタデータを取り込むための作業用ファイルであり、コミットするものではありません。そのため、.gitignore に追加する（*.uploads.json）か、添付が済んだら削除してください。

uploads screenshot で対象にアクセスできない場合（たとえば、先に認証や操作が必要なフロー）に限り、ハーネスのブラウザツール／Playwright／既存のファイルを使用してください。GIF と動画は、任意のツールでキャプチャしてそのままアップロードします — オプティマイザーが書き換えるのは静止画像（PNG/JPEG → WebP）だけです。

ステップ 2 — ホストして埋め込む

PR がすでにあるかどうかで、2 つの方法から選びます。

• シンプル — PR／issue がすでにある場合。 uploads put shot.png --pr 123（または、現在のブランチから PR を推測する uploads attach shot.png）を実行します — 1 回の呼び出しで、PR ごとに安定したキーを使い、埋め込み URL がすぐに返されます。また、管理コメントには副次的な処理としてその PR のメディアがまとめられます。
• 高度 — PR ができる前にステージングする場合。 ブランチで uploads put shot.png を実行します（下記参照） — まだ対象となる PR／issue は不要です。PR が開かれるとプロモーションとコメントが自動で行われますが、これはワークスペースにすでにバインドされているリポジトリに限ります（下記の注意事項を参照）。長めのブランチで意図的にファイルをまとめてステージングする場合を除き、PR ができたらシンプルな方法を使ってください。

既定の流れ：最初のビジュアルの節目から、進捗に合わせてステージングします。 PR ができるのを待たないでください — ブランチで作業中でも、キャプチャする価値のあるものができたら、その時点で添付します。

追加のフラグなしで、自動的にステージングするコマンドが 2 つあります。

• git リポジトリ内で、--pr/--issue/--key/--ref/--prefix を指定せず、既定以外のブランチにいるときの 引数なしの uploads put。attach --branch が生成するものと同じ、ブランチをキーにしたパスにステージングします。
• --pr/--issue/--branch の対象を指定しない uploads screenshot。URL から直接キャプチャすると、導出されたすべての情報 — パス、URL、環境、ビューポート、および --state — が、PR が開かれたときに引き継がれます。

attach --branch は、複数のファイルを共通のフラグで一度にアップロードする場合や、副次的な処理としてプロモーション／コメントの同期を実行する場合に限って、明示的に使用してください。

ステージングキーにはブランチ名が含まれます。ブランチ名を変更した場合、次にそのブランチで uploads のステージングまたはプロモートコマンドを実行すると、自動的に追従します — その前に PR が開かれた場合は、uploads attach --pr <n> --from-branch <old-branch-name> で取り残されたファイルを復元してください（uploads-cli を参照）。

uploads screenshot http://localhost:4321/settings --out step1-before.png --state before
uploads screenshot http://localhost:4321/settings --out step2-after.png --state after

# or, capturing an existing local file instead of a live URL:
uploads put ./step1-before.png --meta path=/settings --state before

# or, explicitly, e.g. to upload several at once:
uploads attach ./step1-before.png ./step2-after.png --branch --state after

安定したブランチ別のパスにアップロードされます（PR／issue のターゲットは不要で、PR が存在するまではコメントする対象がありません）。作業中は、意味のあるビジュアル上のマイルストーンごとにこれを行ってください。最後にすべてを1回の呼び出しにまとめないでください。デフォルトブランチ上（または Git リポジトリ外、あるいは --no-git を指定した場合）は、put／screenshot は通常の日付ベースのレイアウトに戻ります。これがオプトアウトの方法です。明示的な --key／--ref／--prefix／--destination の指定も同様です。

ステージングからの自動昇格は、バインド済みリポジトリでのみ行われます。確認せずに約束しないでください。 PR が開かれたときの自動昇格（下記の Webhook または CLI によるトリガー）には、リポジトリがすでにワークスペースにバインドされている必要があります。バインドには次の2つの方法があります。

• そのリポジトリに対する過去の attach／comment／promote 呼び出しが成功したときに、暗黙的に行われます。
• uploads github link を使って明示的に行われます。

一度もバインドされておらず、--branch でステージングしたことしかないリポジトリでは、PR が開かれてもエラーもコメントも表示されません。何も起こらないままです。リポジトリがバインド済みだと確認できない場合（uploads github link --status）、スクリーンショットが「自動的に表示される」とユーザーに伝えないでください。バインド履歴に関係なく確実に動作する方法は、PR 作成後に uploads attach --promote（または、その PR を対象に uploads attach）を実行して、明示的に昇格して投稿することです。

習慣として、毎回 --state before／--state after と --meta path=/route の両方を渡してください。 これらは検索可能なタグの中でも特に価値が高く、後からツールで復元できない2つの情報です。

• 多くの PR スクリーンショットでは --state の before／after が重要ですが、画像から推測することはできません。
• path も同様に忘れやすい情報です。ただし uploads screenshot はキャプチャした URL から導出します。既存ファイルを指定する put／attach には、導出元となる URL がありません。

どちらも今フラグを1つ渡すだけで済み、数か月後にファイル名だけでは分からなくなっても、uploads find state=after や uploads find path=/settings で検索できます。

同じ URL の before／after ペアには、uploads screenshot を使うのが簡単です。 オブジェクト名はキャプチャした URL から導出され、--state がその名前に反映されます。たとえば localhost-docs-mcp.webp は -before.webp／-after.webp になります。そのため、同じ URL を異なる状態で2回キャプチャすると、片方がもう片方を上書きせず、別々のオブジェクトとして保存されます。特定のオブジェクト名が必要な場合は、明示的な --key を渡してください。既存ファイルを指定する put には、拡張子なしの名前の導出元となる URL がありません。そのため、別々のファイル名か --key を使って before／after を区別してください。

uploads screenshot https://app.example/settings --pr 123 --state before
uploads screenshot https://app.example/settings --pr 123 --state after
uploads put ./after.png --pr 123 --meta path=/settings --state after
uploads put ./chat.png --pr 123 --app ios --screen "Chat" --state after   # app screen, no route

（--state には empty、error、loading も指定できます。）画像が path メタデータなしで保存されると、attach／put --pr／put --issue は stderr に tip: add --meta path=/route so this shot is findable by page と出力し、JSON の hint フィールドにも同じ情報を表示します。これを無視しないでください。ルートのないモバイルアプリ画面またはデスクトップアプリ画面の場合は、代わりに --screen <name> を渡してください。PR コメントでは画像の下に表示されます。ビューポートは screenshot が自動的に導出します。正式な語彙の一覧は uploads-cli スキルを参照してください。

PR コメントは自動で作成されます。その手順を手動で行う必要はありません。 PR が開かれると（gh pr create でも GitHub の UI でも）、ブランチにステージングされた各ファイルがその PR の添付ファイルに昇格され、管理対象のコメントが自動的に作成されます。説明文で触れていないファイルも、すべて表示されます。コメントの識別には、先頭にある非表示の HTML コメントを使います。 ``. Bot からの投稿には uploads-sh[bot] が使われます。ローカルの gh によるフォールバックでも同じマーカーが使われます。

• リポジトリに uploads-sh GitHub App がインストールされている場合、Webhook によって PR が開かれたとき、再オープンされたとき、または新しいコミットが追加されたときに、この処理が行われます。CLI 呼び出しは一切不要です。
• App がインストールされていない場合、その PR を対象に次に実行する uploads attach が、副作用として同じ昇格とコメントの更新をトリガーします。PR を開いた直後に追加するものがない場合は、uploads attach --promote（ファイル引数なし）を実行して、明示的に昇格と更新を行ってください。ステージング済みのファイルがなくても終了コードは 0 です。特定の呼び出しで自動昇格をスキップするには、--no-promote を指定します。 「PR がすでに存在する」場合も、同じコマンドの単純なケースです — 同じ uploads attach を、ブランチではなく PR／issue 番号に指定するだけです。コメントする対象がすでにあるため、 コメントはすぐに更新されます。

uploads attach ./before.png ./after.png
uploads attach ./flow.gif --issue 45 --repo myorg/myapp
uploads attach ./shot.png --no-comment      # stable URLs only, no comment

PR／issue の 本文 にハードコードする URL の場合です（再アップロードすると同じ場所に上書きされ、URL は変わりません）。説明に画像を入れても問題ありません — 説明文の内容に沿ったビジュアル（「どのように見えるか」のビフォーアフターなど）を載せるのに適した場所です。必須ではありません。PR が作成されるまで待って --pr を使えば、最初から安定した pull/<n>/ キーが本文に設定されます。ブランチ用にステージされた URL を説明に貼り付け、後から「修正」するためだけに pull/<n>/ に書き換える必要はありません。

uploads put ./after.png --pr 123 --alt "Dashboard after" --width 700

どこでも共有できる、長期間有効な公開リンクが必要な場合（Slack、ドキュメント、チームメイトとの共有など）：

uploads put ./demo.gif --format url

埋め込む場合は、返された markdown（または embedUrl）を使ってください — 上書きが反映される、キャッシュされないホストです。ストレージ URL を手動で組み立てないでください。

変更フィード（ギャラリーではなく、ライブページ）

フィードは、GitHub リポジトリまたは単一のプルリクエストのタグが付いたスクリーンショットを、新しい順に表示するライブページです。同じ製品で、--pr は追加のフィルターです。厳選したギャラリーではありません（ギャラリーは引き続き uploads gallery create を使います）。

• リポジトリフィード — 「このリポジトリで最近取り込まれたもの」を共有します。
• PR フィード — レビュアーや Slack 向けに、「このプルリクエストに関するすべて」を共有します。

uploads feed create owner/repo
uploads feed create --repo owner/repo
uploads feed create --repo owner/repo --pr 123
uploads feed create --github owner/repo#123

MCP：repo、repo + pr、または github のみを指定して feed_create を実行します。フラグについては uploads-cli を参照してください。同じスコープで再度作成すると、既存の URL が返されます。

管理対象の PR コメントの末尾には、「View on uploads.sh」ボタン（フッターに件数を表示）があり、PR のフィードにリンクします（Web UI では「ライブリンク」と呼ばれます）。画像をクリックすると、単独の /f/ ページではなく、/c/<id>/<item> が開きます（その PR のファイルを新しい順／古い順に表示します）。次のコメント同期では、まだフィードが存在しない場合に作成します。ボット経由でも、ローカルの gh フォールバック経由でも同様です。<img src> は埋め込み URL のままです。

コメントが一時的に消えましたか？慌てて再投稿しないでください。 App がインストールされ、issue_comment イベントを購読している場合、削除された、または編集で消された管理対象コメントは、次の Webhook 配信時に自動で復元されます。コメントを戻すためだけに、再度 comment／attach を実行する必要はありません。

間違ったスクリーンショットを削除しましたか？ 対象のオブジェクトを delete してください。gh/ 添付ファイルを削除すると、可能な場合は管理対象コメントが更新され、そうでない場合は comment（またはホストされた comment ツール）の再実行を促すメッセージが表示されます。間違ったブランチをステージしましたか？uploads unstage --branch <name> を実行すると、ファイルは保持したまま、昇格対象から外せます。最後の添付ファイルがなくなると、コメントは中立的な空の状態に書き換えられます。コメントは PR に残ります（後からアップロードすると内容が再表示されます）。削除済みファイルを指す古い項目が残ることはありません。

uploads.sh のチェックが「UI files changed, no uploads attached」と中立的に表示されますか？ PR で UI ファイルが変更されていますが、何も添付されていません。このチェックによってマージがブロックされることはありません。変更前後の画像を添付すると、次の同期でチェックがグリーンになります。ワークスペース管理者は Settings → GitHub → UI file paths で対象ファイルを選択します。または、リポジトリで .uploads.yml の comment.uiPaths を設定します（[] にすると無効になります）。

ボットのコメントがまったく表示されませんか？ 管理対象コメントには、リポジトリとワークスペースのバインディングが必要です（通常は最初の comment/promote 呼び出し時、または GitHub App のインストール時に暗黙的に作成されます）。表示されるはずのコメントが見当たらない場合は、まずバインディングを確認してください。

uploads github link --status

これは読み取り専用で、現在のバインディング（またはリポジトリが未バインドであること）を表示し、何も取得しません。CLI が代わりに not_authorized を報告する場合、そのリポジトリはすでに_別の_ワークスペースにバインドされています。その場合、独自の gh 認証を使った投稿にはフォールバックしません。バインディングを解除するには、所有するワークスペースから uploads github unlink --repo owner/name を実行するか、担当者にバインディングの再割り当てを依頼してください。すでに所有しているワークスペースに切り替える方法もあります。

大量に載せるのではなく、厳選してください。 コメントにインライン表示される画像は最大 16 枚です。それを超える分は <details> の折りたたみリストにまとめられます。長いセッションで撮ったスクリーンショットを何でも添付するのではなく、意味のある名前を付けて選びましょう（capture-1～capture-40 ではなく、before.png／after.png など）。厳選した少数の節目の画像のほうが、フォルダーを丸ごと載せるより見やすくなります。

ステップ 3 — 適切に埋め込む

• 意味のある代替テキストを必ず指定します（--alt）。

• 大きな画像には --width で幅を制限します（サイズ指定付きの <img> が出力されます）。

• 変更前／変更後は横並びが最も見やすくなります。

  | Before                               | After                               |
  | ------------------------------------ | ----------------------------------- |
  | <img width="380" src="…/before.png"> | <img width="380" src="…/after.png"> |
  

• 動画： GitHub でインライン再生されるのは、ネイティブの user-attachments 動画だけです。 uploads put clip.mp4 --pr N を実行すると、管理対象コメントにポスター画像（静止画と再生ボタン）が追加されます。PR の本文では、GIF を使うか、動画にリンクする静止画を使ってください。

• 本文はファイルに書き込み、インラインの HEREDOC ではなく gh pr edit --body-file／gh issue comment --body-file を使ってください。

セットアップとエスカレーション

• シェルが使えない場合は、ホスト型 MCP を使用してください。CLI はインストールしないでください。
• シェルが使えるマシンに CLI がない場合：npm install --global @buildinternet/uploads
• CLI で認証されていない場合：uploads login（初回のみ。ブラウザーが開きます）を実行し、 次に uploads doctor で確認してください。ホスト型 MCP は初回のツール呼び出し時に OAuth を使用します。
• さらに詳しい情報（フラグ、キーの構成、MCP ツールのコントラクト、メタデータと 検索、ギャラリー、設定のデフォルト、出力形式、終了コード）はすべて、 uploads-cli スキルと uploads <command> --help に記載されています。

注意事項

• アップロードしたファイルは公開され、削除するまで実質的に恒久的です。 GitHub リポジトリの 公開範囲はアクセス制御ではなく、gh/<owner>/<repo>/pull/<num>/… キーは予測可能です。シークレット、トークン、顧客の個人情報は決してアップロードしないでください。 先に切り抜くか、情報をマスキングしてください。
• ファイルが保留されても、失敗ではありません。 管理対象のコメントに 🔒 N files are held for review と表示されている場合、uploads.sh がスクリーンショットにシークレットまたは個人情報が含まれていると判断し、 承認されるまでそのファイルはコメントと URL から除外されています。どのファイルが、なぜ保留されているのか確認するには、 uploads approve --pr <n> を実行してください。ファイルを確認してください。本物の認証情報が写っている場合は、ユーザーにローテーションするよう伝え、 その後マスキングして再アップロードしてください。そうでない場合は、uploads approve --pr <n> --all を実行してください。 確認せずにユーザーに代わって承認しないでください。
• プライベートリポジトリでは、推測できない URL が自動的に使われます。 uploads GitHub App が対象の リポジトリをプライベートと認識すると、添付ファイルのキーは代わりに gh/private/<id>/… になります。フラグは不要です。ステージング済みファイルのキーは gh/private/<id>/branch/<filename> です。id はブランチごとに割り当てられるため、キーには ブランチ名が含まれません。uploads staged --branch はその id のみを一覧表示します。 プルリクエストにすでに追加されているファイルは除外されます。id は永続的ですが、アクセス制御はありません。 URL を知った人は誰でも、ローテーションするまで読み取れます （uploads github rotate-prefix）。全体の仕組みについては docs/private-attachments.md を参照してください。

スクリーンショット内の何かを指し示す必要がありますか？

ボックス、矢印、ラベル、フリーハンドの線、マスキング（キャプチャで検出されたシークレットにはベタ塗りを使用してください。ぼかしたテキストは復元できる可能性があります）は、 uploads screenshot --annotate または uploads annotate でスクリーンショットに直接描き込まれます。仕様形式とワークフローについては annotate-screenshots スキルを参照してから、ここに戻って添付してください。