PR screenshots

Show UI changes on the PR itself, in a way that keeps private screenshots private.

The rule

Upload with gh ... --attach and nothing else. Never put a screenshot in a gist, a new or existing public repo, a public bucket, a pastebin or an image host, even "temporarily", and even if the PR "just needs a link".

Why: GitHub stores --attach uploads as ordinary comment attachments. On a private repo, only signed-in users with access to that repo can open them. Before --attach existed, agents that couldn't attach images pushed them to public repos and gists instead, and thousands of internal screenshots leaked that way (The New Stack). A screenshot of a private app can show customer data, internal URLs and tokens, so a public upload is a data leak even when the code isn't secret.

Steps

1. Check gh. Run gh --version. You need 2.99.0 or later and push access to the repo. If either is missing, stop and tell the human. Don't fall back to another host.
2. Capture the images or videos (PNG, GIF, WebP, SVG, MP4, MOV or WebM) into a scratch directory outside the repo, for example SHOTS="$TMPDIR/shots". That way they don't get committed by accident.
3. Check what's in each image. Look at every screenshot before you upload it. Crop or redact visible secrets, tokens, personal data and production records. If you can't redact something, leave that image out and say so in the PR. Deleting the comment doesn't delete the upload; only a GitHub Support ticket removes it. When in doubt, leave the image out.

4. Write the body as $SHOTS/body.md, next to the images. Put local references where the images should go. gh resolves paths in a --body-file relative to that file's directory, and replaces each reference to an attached file with the uploaded URL:

   ## Screenshots
   | Before | After |
   |---|---|
   | ![Login before](./before.png) | ![Login after](./after.png) |

5. Attach every file that the body references. Pass absolute paths, and run gh from the repo:

   gh pr create --title "..." --body-file "$SHOTS/body.md" \
     --attach "$SHOTS/before.png" --attach "$SHOTS/after.png"
   gh pr edit 42 --body-file "$SHOTS/body.md" \
     --attach "$SHOTS/before.png" --attach "$SHOTS/after.png"
   gh pr comment 42 --body "Error after retry:" \
     --attach "$SHOTS/error.png#Checkout error after retry"

   The text after # is alt text (images only). Repeat --attach for each file, up to 50 per command. A file the body doesn't reference is appended at the end. The same flag works on gh issue create|edit|comment.

6. Verify. For a PR body, run gh pr view 42 --json body. For a comment, run gh pr view 42 --json comments (for an issue, use gh issue view N --json body,comments). Check that every image URL is a github.com/user-attachments/... link, not a local path.
7. Clean up. Once the upload is verified, run rm -rf "$SHOTS". gh doesn't delete local files, and the temp directory is usually cleared only on reboot, so the screenshots would otherwise stay on disk.

When --attach can't be used

Some setups only use a token with the REST or GraphQL API, such as a GitHub App or an Action that doesn't have gh. The API has no upload endpoint. Pick one of these, in order:

1. Install gh in that environment and call it.
2. Otherwise, write in the PR that screenshots are missing and why, and tell the human. Missing screenshots are better than leaked ones. Committing images to the repo (even on a throwaway branch) keeps them in git history for every clone and fork, so do that only if the human approves it for this task.