Github Image Upload

Upload images and files to GitHub (gh-image)

GitHub has no public API for attachment uploads — the web UI uses an internal endpoint that mints user-attachments URLs scoped to the repo's visibility. gh-image (MIT, © drogers0) replicates that flow as a gh CLI extension, so you can upload images or other files (PDF, zip, log, …) from the terminal and get a ready-to-paste reference back — an ![name](url) embed for images, a bare URL for videos (GitHub renders it as an inline player), or a [name](url) download link for other files.

This skill drives gh-image and then embeds the result into a PR/issue/comment.

Prerequisites — verify these before uploading

Run these checks; only act on the ones that fail.

1. gh CLI installed & authenticated

   gh auth status
   

   If it fails, tell the user to run gh auth login (do not attempt it unattended).

2. The gh-image extension installed (idempotent — skip if already present)

   gh extension list | grep -q 'drogers0/gh-image' || gh extension install drogers0/gh-image
   

3. A GitHub session for the upload. gh-image does NOT use the gh token for the upload (that endpoint rejects tokens); it needs the browser user_session cookie. Resolution order (first match wins):

   • --token <value> flag, or
   • GH_SESSION_TOKEN env var (use this in CI / headless), or
   • the cookie store of a logged-in browser (Chrome/Brave/Chromium/Edge/Firefox/ Opera/Safari) — the default for local use. On macOS the first read may show a Keychain prompt; the user should click Always Allow.

   ⚠️ A user_session cookie grants full account access (it is not scoped like a PAT). Treat it like a password; in CI use a dedicated bot account.

   💡 The user may hand you the session token directly (e.g. "you can use the user session token … to call it"). Do not echo it, print it, write it to a file, or commit it. When they do, export GH_SESSION_TOKEN for the current shell session so subsequent uploads work without re-passing the token:

   export GH_SESSION_TOKEN="<session-token>"
   

   Note the export only persists for that shell session — it is lost when a new terminal/session starts, so re-export or pass --token on later runs. (Do not append it to ~/.bashrc or similar; storing session cookies there is discouraged.) It expires, so if an upload fails later, ask the user for a fresh one.

Step 1 — Normalize the file path

Use an absolute path. If a glob is given, resolve it first. Paths with spaces or Unicode (e.g. CleanShot's narrow spaces) work, but quote them.

Step 2 — Upload

# One or more files (images or PDF/zip/log/…); --repo is optional inside a repo
# working dir (inferred from the remote).
gh image "/abs/path/screenshot.png" --repo <owner>/<repo>

# With a user-provided session token (see note in Prerequisites). If you already
# exported GH_SESSION_TOKEN for the session, no --token/--repo is needed here:
export GH_SESSION_TOKEN="<session-token>"
gh image "/abs/path/screenshot.png" --repo <owner>/<repo>

gh image prints the reference to stdout — an image embed for images, a bare URL for videos (GitHub renders it as an inline player), and a download link for other files, e.g.:

![screenshot.png](https://github.com/user-attachments/assets/<uuid>)
https://github.com/user-attachments/assets/<uuid>
[report.pdf](https://github.com/user-attachments/files/<id>/report.pdf)

Capture that output — it is the embeddable reference. For multiple files it prints one line per file.

Step 3 — Embed into the PR / issue / comment

gh-image only prints the markdown; you embed it. Pick the target the user asked for.

Append to a PR description (preserves the existing body):

MD="$(gh image "/abs/path/shot.png" --repo owner/repo)"
BODY="$(gh pr view <pr> --repo owner/repo --json body -q .body)"
printf '%s\n\n## Screenshots\n\n%s\n' "$BODY" "$MD" \
  | gh pr edit <pr> --repo owner/repo --body-file -

Post as a new PR comment:

MD="$(gh image "/abs/path/shot.png" --repo owner/repo)"
printf '## Screenshots\n\n%s\n' "$MD" | gh pr comment <pr> --repo owner/repo --body-file -

Add to an issue body / comment: same pattern with gh issue edit <n> --body-file - or gh issue comment <n> --body-file -.

Always use --body-file - (not inline --body) so multi-line bodies and special characters can't break shell quoting.

Step 4 — Verify

gh pr view <pr> --repo owner/repo --json body -q .body   # confirm the URL is present

The user-attachments URL inherits the repo's visibility, so on a private repo it renders only for authorized viewers (an anonymous fetch returns 404/403 — that is expected, not a failure).

Sizing (optional)

To control display size, embed an HTML tag instead of the bare markdown:

<img width="800" alt="screenshot" src="https://github.com/user-attachments/assets/<uuid>" />

Troubleshooting