github-upload-image-to-pr

name	github-upload-image-to-pr
description	Embed a local image file into an existing GitHub PR — either in the PR body or as a comment. Trigger when a request pairs a local image (screenshot, .png/.jpg, CleanShot capture, before/after) with an existing PR (by #number, URL, branch name, or "the open PR"), regardless of verb — attach, embed, add, put, post, drop, show, document. Also covers visually documenting test runs, bug repros, UI states, or CI failures on an existing PR. The `gh` CLI cannot upload images; this skill drives a real browser to GitHub's user-attachments uploader.
allowed-tools	Bash(gh:*), Bash(cp:*), ToolSearch, Read

Upload Image to PR

Browser-driven workflow for embedding local images in a GitHub PR — the GitHub API does not support image uploads, so this drives Playwright MCP to GitHub's user-attachments uploader instead.

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 1: 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. If a path contains special characters (e.g., Unicode narrow spaces from CleanShot X), copy the file to /tmp/ first:

# e.g., to handle glob-matched paths with special chars
cp /path/to/CleanShot*keyword*.png /tmp/screenshot.png

Step 2: Verify Playwright MCP is available

Use ToolSearch with a query like "browser navigate upload" to confirm mcp__playwright__* tools are registered.

Playwright MCP runs isolated (--isolated --storage-state=…/mcp-auth.json), loading github.com cookies from that shared storage-state file at startup — so the session persists across sessions once the file is populated. It's load-only: the MCP never writes it back, so login can't be refreshed through the MCP browser. If GitHub logs the user out and you hit a 404 / login screen mid-task, see references/headless-relogin.md — full login can't be driven headlessly.

If Playwright MCP is not registered

The project ships a .mcp.json registering Playwright MCP (isolated, shared storage-state file, headless). Claude Code prompts to approve project MCP servers on first entry — if the mcp__playwright__* tools aren't registered, approve the playwright server there and restart the session (or /mcp → playwright → reconnect). On first use mcp-auth.json won't exist yet — populate it via the login helper in the re-login guide.

Step 3: Navigate to PR page and check login state

Navigate and immediately take a snapshot to verify login state:

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

If an SSO authentication screen appears: locate the "Continue" button in the snapshot and click it.

Step 4: Locate the file upload input

Take a snapshot and scroll to the bottom to find the comment area. GitHub renders a file upload input in the comment form. Either find the ref directly from the snapshot, or run JS to detect it (GitHub's UI can change — try selectors in order):

() => {
  const selectors = [
    'input[type="file"][id*="comment"]',
    'input[type="file"][id="fc-new_comment_field"]',
    '#new_comment_field',
    'input[type="file"]'
  ];
  for (const sel of selectors) {
    const el = document.querySelector(sel);
    if (el) return { found: true, id: el.id, selector: sel };
  }
  return { found: false };
}

Step 5: Upload images one by one

The <input type="file"> from step 4 is CSS-hidden — calling browser_file_upload against its ref directly fails with "can only be used when there is related modal state present." First click the visible "Paste, drop, or click to add files" button (or "Attach files" toolbar icon) on the comment form to open the native file chooser, then browser_file_upload will satisfy that chooser.

Upload each image with browser_file_upload (takes the element ref and a file paths array). Wait 2–3 seconds between uploads so GitHub can process each file, then 3–5 seconds after the last upload before reading URLs in step 6 — GitHub injects the image markup asynchronously after each file finishes processing.

For multiple images, upload them all to the same comment textarea before extracting URLs — this is more efficient than navigating between uploads.

Important: Always use absolute file paths.

Step 6: Retrieve uploaded image URLs

Read the textarea value via browser_evaluate — GitHub injects either markdown or HTML referencing the upload after each file finishes processing.

The standard textarea selector (referenced again in step 7) prefers the known ID and falls back to a substring match in case GitHub renames it:

() => {
  const ta = document.getElementById('new_comment_field')
          || document.querySelector('textarea[id*="comment"]');
  return ta ? ta.value : 'textarea not found';
}

GitHub may inject either form depending on image dimensions / file type:

![image](https://github.com/user-attachments/assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
<img width="..." height="..." alt="..." src="https://github.com/user-attachments/assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" />

Both render the image in the PR — preserve whichever form GitHub used. If you need to extract just the URL (e.g., to rewrap), match the asset path with a regex that ignores wrapper syntax: https://github\.com/user-attachments/assets/[0-9a-f-]+.

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

Submitting via the UI's "Comment" button would post a public comment as a side effect of the upload. The only thing that should determine where the image lands (PR body vs. a new comment) is step 8 — so the textarea here is purely an upload-staging surface, never a submission surface. Clear it, then let gh pr edit / gh pr comment decide the destination.

Use the standard textarea selector from step 6, then assign ta.value = "":

() => {
  const ta = document.getElementById('new_comment_field')
           || document.querySelector('textarea[id*="comment"]');
  if (ta) { ta.value = ""; return "cleared"; }
  return "textarea not found";
}

Step 8: Embed images in the PR

Substitute whichever form (markdown ![](...) or HTML <img ...>) GitHub returned in step 6 — preserve it verbatim instead of rewrapping.

Post as a comment (the default). A comment keeps the description tight and skimmable, and avoids re-editing the body (and its notification noise) on every recapture.

If a screenshots comment already exists (one authored by you whose body starts with ## Screenshots), edit it in place instead of posting a new one:

SCREENSHOT_COMMENT_ID=$(gh api "repos/{owner}/{repo}/issues/$PR_NUMBER/comments" \
  --jq '.[] | select(.body | startswith("## Screenshots")) | .id' | head -1)

Write the comment body to a temp file:

## Screenshots

<image markup from step 6>

• If $SCREENSHOT_COMMENT_ID is empty: gh pr comment {PR_NUMBER} --body-file <tmp-comment-file>.
• Otherwise: gh api -X PATCH repos/{owner}/{repo}/issues/comments/$SCREENSHOT_COMMENT_ID -f body="$(cat <tmp-comment-file>)" --jq .html_url. Don't use -f body=@<file> — gh api's -f stores the literal string @<file> rather than reading it, so the comment gets clobbered with the filename.

Only edit the PR description instead when the user explicitly asks for it:

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" "<image markup from step 6>")"

If $EXISTING_BODY already contains a ## Screenshots heading (e.g., on re-runs), this will create a duplicate section. Check first with grep -q "^## Screenshots" <<< "$EXISTING_BODY" and either replace the existing section or post as a comment instead.

Step 9: Verify the result

Reload the page in the Playwright browser and take a screenshot to confirm the images render correctly. Do not verify with curl — user-attachments/assets/ URLs return HTTP 302 to a session-signed S3 URL that 403s for unauthenticated clients. The 302 alone confirms the asset exists; the browser-rendered check is the only authoritative "did it display" signal.

Tips

• Image sizing: Control display size via HTML <img> tags: <img width="800" alt="description" src="..." />
• Multiple images: Upload all images in one session to the same textarea; extract all URLs before clearing

Troubleshooting

Issue	Solution
Not logged in	SSO screen may appear — take snapshot, find "Continue" button, click it. Full GitHub login can't be done headless — see references/headless-relogin.md
File path with special characters (e.g., Unicode narrow spaces from CleanShot)	Copy file to /tmp/ with a simple name: cp /path/CleanShot*keyword*.png /tmp/screenshot.png
File upload fails	Ensure the file path is absolute
Textarea doesn't contain URLs yet	Wait 3–5 seconds after upload before running JS eval; retry once if needed
Textarea selector not found	GitHub UI changes occasionally — use the multi-selector JS in Step 4 to find the current element
Playwright MCP not registered	Approve the playwright server from the project .mcp.json (Claude Code prompts on project entry), then restart the session or /mcp → reconnect
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
• 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
• Playwright MCP preserves cookies/login state across calls within a session; across sessions the login comes from the shared --storage-state file (mcp-auth.json), loaded at startup