github-upload-image-to-pr
Upload local images or videos to a GitHub PR and embed them in the description or comments. Use when asked to "attach screenshots to PR", "add images to PR", "upload test results to PR", "embed screenshots in PR description", "add before/after images to PR", "attach UI screenshots", "show test results in PR", "add visual evidence to PR", or any request involving images and PRs. Always use this skill when the user wants to visually document changes in a pull request, even if they don't use the word "upload" — phrases like "put the screenshot in the PR" or "show the image in the PR" should trigger this skill. Prefers GitHub CLI's native `--attach` flag (gh 2.99.0+), which needs no browser at all, and falls back to browser automation (Chrome DevTools MCP, then Playwright MCP, then agent-browser) only when `gh --attach` is unavailable.
tonkotsuboy · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add tonkotsuboy/github-upload-image-to-pr --skill github-upload-image-to-prAbout this skill
name: github-upload-image-to-pr
description: >-
Upload local images or videos to a GitHub PR and embed them in the description or comments.
Use when asked to "attach screenshots to PR", "add images to PR", "upload test results to PR",
"embed screenshots in PR description", "add before/after images to PR", "attach UI screenshots",
"show test results in PR", "add visual evidence to PR", or any request involving images and PRs.
Always use this skill when the user wants to visually document changes in a pull request,
even if they don't use the word "upload" — phrases like "put the screenshot in the PR" or
"show the image in the PR" should trigger this skill.
Prefers GitHub CLI's native --attach flag (gh 2.99.0+), which needs no browser at all, and
falls back to browser automation (Chrome DevTools MCP, then Playwright MCP, then agent-browser)
only when gh --attach is unavailable.
allowed-tools: Bash(agent-browser:), Bash(gh:), Bash(brew:), Bash(npx:), Bash(cp:), Bash(rm:), Bash(sleep:*), mcp__chrome-devtools, mcp__playwright, ToolSearch, Read, Glob, Write
license: MIT
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 |
| --- | --- |
|  |  |" \
--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 gotchas
- Attaching only appends; it never replaces. Re-running the same command duplicates the images. To swap an image out, rewrite the body without the stale URL (
gh pr edit {PR} --body "$(...)") in the same command that attaches the new one. - A
#in the filename breaks the<file>#<alt>split. Stage a copy with a plain ASCII name first (cp './weird #name.png' ./shot.png) andrmit afterwards. The same trick handles the Unicode