PR Image Embedding
gaia is a private repo. That single fact drives every rule below, because
GitHub renders inline images through camo, its image proxy, and camo fetches
image URLs unauthenticated. Anything that needs a session or a token to fetch
will not render — it degrades to alt text that links to the source.
The flow
Generate the image locally. Write it somewhere outside the repo first
(the session scratchpad), so a rejected chart never lands in git history.
Look at it before you ship it. Read the PNG back with the Read tool.
Labels overlap, axes collide, and text clips constantly — a chart nobody
verified is worse than no chart, because reviewers trust it.
Commit the images to the single shared assets branch, pr-assets, under a
per-PR folder:
There is exactly one assets branch — pr-assets — and it is never
duplicated. Do not create a custom branch per PR. Every PR's images live
on pr-assets, each under its own folder named for the PR
(<pr-number>-<topic>/, e.g. 890-anydoc-parsing/). The branch already
exists and is cut from master; update it in place:
git fetch origin pr-assets
git checkout -B pr-assets origin/pr-assets
mkdir -p <pr-number>-<topic>
cp -f /path/to/charts/*.png <pr-number>-<topic>/
git add <pr-number>-<topic>/ && git commit -m "Assets for PR #<pr-number> (<topic>)"
git push -u origin pr-assets
Keep them off the code branch. Binaries in a code diff are noise a
reviewer has to scroll past, and they make the PR's real change harder to see.
A per-PR assets branch is also noise — it forks the history for a handful of
images, and the single pr-assets branch is the one place reviewers (and
camo) can find them. Say "not intended to be merged" in the commit message.
Reference them by raw URL in the PR body, always on pr-assets under the
PR's folder:

Use , never <img src> — GitHub sanitizes HTML in some contexts,
and markdown is what the rest of the description uses anyway.
Always include the numbers in text too — a table or bullet list beside
the charts. If camo fails, or someone reads the PR in email/on mobile/in a
terminal, the evidence still survives. This is the cheapest insurance there is.
If images still don't render
The symptom is specific: alt text that is clickable and opens the image fine.
That means the URL is good and camo could not proxy it. Diagnose in this order:
# 1. Is it actually served as an image?
curl -sS -D - -o /dev/null "<url>" | grep -iE "^HTTP|content-type|content-length"
# 2. Does the host block camo's user-agent?
curl -sS -o /dev/null -w "%{http_code}\n" -A "github-camo (b2d0ea9c)" "<url>"
Known blockers, in rough order of likelihood:
| Cause |
Fix |
Private-repo URL needing auth (raw.githubusercontent.com on a private repo, or a GitHub UI URL) |
Use GitHub's own attachment upload (below) |
Missing Content-Length header on the host |
Not fixable from our side — change hosts |
| Host blocks or challenges camo's UA (Cloudflare bot protection) |
Change hosts |
| Camo cached an earlier failure for that exact URL |
Re-upload under a new URL |
The guaranteed fallback
GitHub's own attachment upload always renders, in private repos included,
because GitHub serves it to the authenticated viewer. It produces a
https://github.com/user-attachments/assets/<uuid> URL.
There is no API for it — it only exists in the browser. So an agent cannot
do this step. Hand the files to the user (SendUserFile) and have them drag the
images into the PR description box. Ten seconds of their time, guaranteed result.
Third-party image hosts
Workable, but treat with care and never as the default:
- It publishes the content publicly — it may be cached or indexed even
after deletion. Never upload anything containing internal code, hostnames,
credentials, customer data, or unreleased product detail. Benchmark charts and
generic diagrams are fine; a screenshot of the app with real data is not.
- Confirm the host is one the user actually trusts before sending anything.
- Verify what came back: fetch the returned URL and look at the image.
Hosts recompress (a changed byte count/checksum is normal and not evidence of
tampering — check the pixels, not the hash).
- Many such hosts still won't render inline for the reasons in the table above,
so you can do everything right here and still end up back at the fallback.
Rules of thumb
- Never claim images render until the user confirms it — you cannot see the
rendered PR, and a private repo means you cannot fetch it to check.
- Never let the PR sit with broken image markup. Either fix it or strip the tags
and leave the numbers in text.
- The charts are a convenience; the text is the record. Write the description so
it stands on its own with every image stripped out.
1---2name: pr-image-embedding3description: Embed images (benchmark charts, screenshots, diagrams) inline in a GitHub PR or issue description from an agent session, without bloating the code diff. Use when a PR needs visual evidence and you cannot drag-and-drop into the browser.4metadata:5 source: https://skillmd.com/skills/theexperiencecompany/pr-image-embedding6---78## PR Image Embedding910`gaia` is a **private** repo. That single fact drives every rule below, because11GitHub renders inline images through **camo**, its image proxy, and camo fetches12image URLs **unauthenticated**. Anything that needs a session or a token to fetch13will not render — it degrades to alt text that links to the source.1415### The flow16171. **Generate the image locally.** Write it somewhere outside the repo first18 (the session scratchpad), so a rejected chart never lands in git history.19202. **Look at it before you ship it.** Read the PNG back with the Read tool.21 Labels overlap, axes collide, and text clips constantly — a chart nobody22 verified is worse than no chart, because reviewers trust it.23243. **Commit the images to the single shared assets branch, `pr-assets`, under a25 per-PR folder:**2627 There is exactly **one** assets branch — `pr-assets` — and it is never28 duplicated. **Do not create a custom branch per PR.** Every PR's images live29 on `pr-assets`, each under its own folder named for the PR30 (`<pr-number>-<topic>/`, e.g. `890-anydoc-parsing/`). The branch already31 exists and is cut from `master`; update it in place:3233 ```bash34 git fetch origin pr-assets35 git checkout -B pr-assets origin/pr-assets36 mkdir -p <pr-number>-<topic>37 cp -f /path/to/charts/*.png <pr-number>-<topic>/38 git add <pr-number>-<topic>/ && git commit -m "Assets for PR #<pr-number> (<topic>)"39 git push -u origin pr-assets40 ```4142 Keep them **off the code branch**. Binaries in a code diff are noise a43 reviewer has to scroll past, and they make the PR's real change harder to see.44 A per-PR assets branch is also noise — it forks the history for a handful of45 images, and the single `pr-assets` branch is the one place reviewers (and46 camo) can find them. Say "not intended to be merged" in the commit message.47484. **Reference them by raw URL** in the PR body, always on `pr-assets` under the49 PR's folder:5051 ```markdown52 53 ```5455 Use ``, never `<img src>` — GitHub sanitizes HTML in some contexts,56 and markdown is what the rest of the description uses anyway.57585. **Always include the numbers in text too** — a table or bullet list beside59 the charts. If camo fails, or someone reads the PR in email/on mobile/in a60 terminal, the evidence still survives. This is the cheapest insurance there is.6162### If images still don't render6364The symptom is specific: **alt text that is clickable and opens the image fine**.65That means the URL is good and camo could not proxy it. Diagnose in this order:6667```bash68# 1. Is it actually served as an image?69curl -sS -D - -o /dev/null "<url>" | grep -iE "^HTTP|content-type|content-length"7071# 2. Does the host block camo's user-agent?72curl -sS -o /dev/null -w "%{http_code}\n" -A "github-camo (b2d0ea9c)" "<url>"73```7475Known blockers, in rough order of likelihood:7677| Cause | Fix |78|---|---|79| Private-repo URL needing auth (`raw.githubusercontent.com` on a private repo, or a GitHub UI URL) | Use GitHub's own attachment upload (below) |80| Missing `Content-Length` header on the host | Not fixable from our side — change hosts |81| Host blocks or challenges camo's UA (Cloudflare bot protection) | Change hosts |82| Camo cached an earlier failure for that exact URL | Re-upload under a new URL |8384### The guaranteed fallback8586GitHub's own attachment upload always renders, in private repos included,87because GitHub serves it to the authenticated viewer. It produces a88`https://github.com/user-attachments/assets/<uuid>` URL.8990**There is no API for it** — it only exists in the browser. So an agent cannot91do this step. Hand the files to the user (`SendUserFile`) and have them drag the92images into the PR description box. Ten seconds of their time, guaranteed result.9394### Third-party image hosts9596Workable, but treat with care and never as the default:9798- It **publishes the content publicly** — it may be cached or indexed even99 after deletion. Never upload anything containing internal code, hostnames,100 credentials, customer data, or unreleased product detail. Benchmark charts and101 generic diagrams are fine; a screenshot of the app with real data is not.102- Confirm the host is one the user actually trusts before sending anything.103- Verify what came back: fetch the returned URL and **look at the image**.104 Hosts recompress (a changed byte count/checksum is normal and not evidence of105 tampering — check the pixels, not the hash).106- Many such hosts still won't render inline for the reasons in the table above,107 so you can do everything right here and still end up back at the fallback.108109### Rules of thumb110111- Never claim images render until the user confirms it — you cannot see the112 rendered PR, and a private repo means you cannot fetch it to check.113- Never let the PR sit with broken image markup. Either fix it or strip the tags114 and leave the numbers in text.115- The charts are a convenience; the text is the record. Write the description so116 it stands on its own with every image stripped out.