Github Upload Image To Pr

Upload Image to PR

Upload local images to a GitHub PR and embed them in the description or comments using browser automation tools.

How It Works

Since the GitHub API does not support direct image uploads, this skill uses the PR comment textarea as a staging area for GitHub's image hosting — uploading files there to obtain persistent user-attachments/assets/ URLs, then updating the PR description or posting a comment via the gh CLI.

Step 0: Resolve PR context

If the user didn't specify a PR number or URL, auto-detect it:

# Get PR number from the current branch
gh pr view --json number,url -q '"\(.number) \(.url)"'

If multiple repos or branches are involved, confirm with the user which PR to target.

Also, normalize the image paths to absolute paths and stage a clean copy inside the current working directory (the repo root) — not /tmp/:

# Stage inside the repo. The staged filename becomes the image's alt text on GitHub,
# so give it a meaningful name. Delete it after the upload completes.
cp /path/to/'CleanShot 2026-... .png' ./.upload-staging.png

Why stage inside the repo and not /tmp/? MCP browser tools (Playwright / Chrome DevTools) can only read files within their configured workspace root, which is normally the project directory the session launched from. A path under /tmp/ is outside that root, so the upload call fails with Access denied: path ... is not within any of the configured workspace roots. Staging the file in the repo works for every backend (agent-browser, a plain CLI, can read /tmp/ too — but in-repo is universally safe).

Staging also sidesteps paths with special characters (e.g. the Unicode narrow spaces CleanShot X puts in filenames), which otherwise break shell globbing and tool arguments. Remember to rm the staged file once you're done so it isn't accidentally committed.

Tool Detection and Selection

Priority Order

1. Playwright MCP (MCP connection, mcp__playwright__*) — connects to existing browser, login state preserved
2. Chrome DevTools MCP (MCP connection, mcp__chrome-devtools__*) — connects to existing browser, login state preserved
3. agent-browser (CLI via Bash — fallback, login state preserved with --profile)

MCP-based tools connect to an already-running browser instance, so GitHub login state is automatically preserved. agent-browser can persist login state using --profile ~/.agent-browser-github.

Detection

# 1. Search for MCP-based browser tools (preferred)
ToolSearch: "browser navigate upload"

# 2. Fall back to agent-browser only if no MCP tools found
Bash: agent-browser --version

Tool Compatibility Matrix

| Operation | Playwright MCP | Chrome DevTools MCP | agent-browser (CLI/Bash) | |-----------|----------------|---------------------|--------------------------| | Navigate | browser_navigate | navigate_page | agent-browser --headed open {url} | | Snapshot | browser_snapshot | take_snapshot | agent-browser snapshot | | Screenshot | browser_take_screenshot | take_screenshot | agent-browser screenshot {path} | | Click | browser_click (ref) | click (uid) | agent-browser click {ref} | | File Upload | browser_file_upload (paths) | upload_file (uid, filePath) | agent-browser upload {ref} {path} | | JS Eval | browser_evaluate (function) | evaluate_script (function) | agent-browser eval '{js}' | | Login State | Preserved | Preserved | Preserved with --profile |

Steps

Step 1: Navigate to PR page and check login state

Navigate to the PR page and immediately take a snapshot to verify login state.

// Playwright MCP
browser_navigate({ url: "https://github.com/{owner}/{repo}/pull/{number}" })

// Chrome DevTools MCP
navigate_page({ url: "https://github.com/{owner}/{repo}/pull/{number}", type: "url" })

// agent-browser (use --profile to persist login state)
agent-browser --headed --profile ~/.agent-browser-github open "https://github.com/{owner}/{repo}/pull/{number}"

If SSO authentication screen appears: Take a snapshot, locate the "Continue" button, and click it.

If NOT logged in (agent-browser only):

1. Navigate to https://github.com/login
2. Ask the user to log in manually in the headed browser window.
3. Wait for user confirmation, then navigate back to the PR page.

Step 2: Locate the upload target

Scroll to the comment form at the bottom of the PR and take a snapshot.

Key gotcha: GitHub's real ` (id fc-newcommentfield) is display:none`, so it does not appear in the accessibility snapshot — you can't get a uid/ref for it that way, and clicking it isn't possible. Instead, target the visible affordance that opens the file picker: the dropzone labeled "Paste, drop, or click to add files", or the toolbar "Attach files" button. The browser tool clicks it, intercepts the native file chooser, and hands over your file.

In a snapshot these show up as:

button "Attach files"
button "Paste, drop, or click to add files"   ← pass this uid/ref to the upload tool

The comment box itself is a ` web component wrapping a — that textarea is where the resulting image reference lands (Step 4). GitHub's UI shifts over time, so if newcommentfield isn't there, fall back to textarea[name="comment[body]"] or textarea[id*="comment"]; the PR-description editor instead uses textarea[name="pull_request[body]"] / textarea[id$="-body"]`.

Step 3: Upload the image(s)

Upload each file with the detected tool, passing the dropzone / attach-button uid from Step 2 (never the hidden input):

// Chrome DevTools MCP: upload_file({ uid: , filePath:  })
// Playwright MCP:      browser_file_upload({ paths: [] }) once the file chooser is open
// agent-browser:       agent-browser upload {ref} {absolute_path}    (any path, /tmp/ ok)

Use the in-repo staged path from Step 0 for the MCP backends (see the workspace-root note there). Wait 2–3 seconds between uploads. For multiple images, upload them all into the same comment box before extracting URLs — more efficient than navigating between uploads.

Step 4: Retrieve the uploaded image URL(s)

While uploading, GitHub shows a placeholder (`) in the textarea, then swaps it for the final reference once the file lands. So **poll the textarea until a user-attachments/assets/` URL appears** instead of trusting a fixed sleep — it usually takes 1–5 seconds.

**GitHub inserts the reference as an HTML ` tag** (with auto-detected width/height`), e.g.:

Don't assume the `` markdown form — match the asset URL itself so extraction stays robust to either form:

// MCP-based tools — returns every asset URL plus the raw value for sanity-checking
() => {
  const ta = document.getElementById('new_comment_field')
          || document.querySelector('textarea[name="comment[body]"], textarea[id*="comment"]');
  if (!ta) return { error: 'textarea not found' };
  const urls = [...ta.value.matchAll(/https:\/\/github\.com\/user-attachments\/assets\/[0-9a-fA-F-]+/g)].map(m => m[0]);
  return { raw: ta.value, urls };
}

# agent-browser
agent-browser eval 'const ta=document.getElementById("new_comment_field")||document.querySelector("textarea[id*=comment]");JSON.stringify([...(ta?.value||"").matchAll(/https:\/\/github\.com\/user-attachments\/assets\/[0-9a-fA-F-]+/g)].map(m=>m[0]))'

Keep the whole ` tag if you want to preserve GitHub's auto-detected width/height; otherwise take just the URL and wrap it yourself ( or your own `).

Step 5: Clear the textarea (do not submit the comment)

Dispatch an input event after clearing so GitHub's comment-draft autosave also clears — otherwise the staged content can reappear on the next page load.

// MCP-based tools
() => {
  const ta = document.getElementById('new_comment_field')
           || document.querySelector('textarea[name="comment[body]"], textarea[id*="comment"]');
  if (!ta) return "textarea not found";
  ta.value = "";
  ta.dispatchEvent(new Event('input', { bubbles: true }));
  return "cleared";
}

# agent-browser
agent-browser eval 'const ta=document.getElementById("new_comment_field")||document.querySelector("textarea[id*=comment]"); if(ta){ta.value="";ta.dispatchEvent(new Event("input",{bubbles:true}))} "cleared"'

Step 6: Embed images in the PR

Embed using either the full ` tag GitHub gave you (keeps the auto-detected size) or plain markdown `.

Option A — Update PR description (append images to existing body):

EXISTING_BODY=$(gh pr view {PR_NUMBER} --json body -q .body)

gh pr edit {PR_NUMBER} --body "$(printf '%s\n\n## Screenshots\n\n%s' "$EXISTING_BODY" '')"

Option B — Post as a new comment:

gh pr comment {PR_NUMBER} --body '## Screenshots

'

Use Option A by default unless the user explicitly asks for a comment, or if the PR description is already long and a comment would be cleaner.

Step 7: Verify the result

Reload the page and take a screenshot to confirm the images are displayed correctly.

Tips

• Image sizing: Control display size via HTML ` tags: `
• Multiple images: Upload all images in one session to the same textarea; extract all URLs before clearing
• Prefer MCP tools: Always prefer Playwright or Chrome DevTools MCP over agent-browser for simpler setup
• agent-browser login persistence: Use --profile ~/.agent-browser-github to persist GitHub login across sessions

Troubleshooting

| Issue | Solution | |-------|----------| | Not logged in (MCP tools) | SSO screen may appear — take snapshot, find "Continue" button, click it | | Not logged in (agent-browser) | Use --headed mode, navigate to login page, ask user to log in manually | | Browser window not visible | For agent-browser, ensure --headed flag is used | | File path with special characters (e.g., Unicode narrow spaces from CleanShot) | Stage a copy with a simple name inside the repo: cp /path/'CleanShot ... .png' ./.upload-staging.png (in-repo so MCP tools can read it — see Step 0) | | Access denied: path ... not within any of the configured workspace roots | MCP browser tools only read files inside their workspace root. Stage the image inside the repo (Step 0), not /tmp/ | | Can't find a uid/ref for the file input | The ` is display:none and absent from the snapshot — target the visible *"Paste, drop, or click to add files"* dropzone or *"Attach files"* button instead (Step 2) | | Textarea has the file but no markdown | GitHub inserts an HTML tag for images, not Markdown. Extract the user-attachments/assets/ URL with the regex in Step 4, which matches both forms | | Textarea doesn't contain URLs yet | GitHub shows an placeholder first — poll the textarea until a user-attachments/assets/ URL appears (1–5s) instead of a fixed wait | | Textarea selector not found | GitHub UI changes occasionally — fall back through newcommentfield → textarea[name="comment[body]"] → textarea[id*="comment"] (Step 2) | | Chrome DevTools MCP disconnected | Reconnect via /mcp command | | agent-browser not found | npm install -g agent-browser && agent-browser install | | No browser tools found | Use ToolSearch` to search for available browser tools | | PR not found / 404 | Private repos return 404 for unauthenticated users — check login state |

Notes

• GitHub user-attachments/assets/ URLs are persistent — images remain accessible even without submitting the comment. When rendered, GitHub rewrites them to private-user-images.githubusercontent.com CDN URLs; the user-attachments/assets/... form is the stable one to embed
• On upload, GitHub injects an ` tag (alt is derived from the filename) — not ` markdown. Extract by the asset URL, not the wrapper
• MCP browser tools can only read upload files inside their workspace root, so stage images in the repo, not /tmp/
• Editing the description directly in the browser UI is fragile due to GitHub UI structure changes — updating via gh pr edit is strongly preferred
• Multiple images can be uploaded in a single session before extracting URLs
• MCP-based tools connect to existing browser instances, preserving cookies and login sessions

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tonkotsuboy
• Source: tonkotsuboy/github-upload-image-to-pr
• License: MIT

Install and usage instructions live in the source repository linked above.