problem

there is no way to attach images or files to issues or comments via gh. this has been requested multiple times (#1895, #3348, #4228, #4465) and closed as blocked on the platform api. but the world has changed — ai coding agents (claude code, codex, gemini cli, etc.) now create and manage github issues programmatically via gh, and they cannot attach screenshots, logs, or any binary content.

this is the single biggest gap in gh's agentic usability. an agent can write a perfect issue body but can't attach the screenshot that makes it actionable.

proposed ux

flag: --attach

# attach image to a new issue
gh issue create --title "ui bug" --body "see screenshot below" \
  --attach screenshot.png

# attach multiple files
gh issue create --title "crash report" --body "details attached" \
  --attach screenshot.png --attach crash.log

# attach image to a comment
gh issue comment 42 --body "here's the fix result" \
  --attach after.png

# attach to pr body
gh pr create --title "fix layout" --body "before/after comparison" \
  --attach before.png --attach after.png

the cli would:

1. upload the file (mechanism below)
2. append ![filename](uploaded-url) (for images) or [filename](uploaded-url) (for other files) to the bottom of the body
3. create the issue/comment with the final markdown

flag: --attach-inline

for users who want to control placement:

gh issue create --title "bug" \
  --body "before: ![](attach:before.png) after: ![](attach:after.png)" \
  --attach before.png --attach after.png

the cli replaces attach:filename references in the body with the uploaded urls.

implementation options

the api gap is real, but there are viable paths:

option 1: release asset piggyback (works today)

upload files as assets on a hidden/dedicated release, then embed the download urls in the issue body. gh release upload already works — this just chains two existing capabilities.

gh release create _attachments --repo owner/repo --notes "" 2>/dev/null
gh release upload _attachments screenshot.png --repo owner/repo
# → returns download url, embed in issue body

pros: uses public api only, no browser automation
cons: clutters releases (could use a dedicated _gh-attachments tag)

option 2: repo content upload

push files to an orphan gh-attachments branch, reference raw.githubusercontent.com urls.

pros: public api, files live in the repo
cons: bloats repo history, may hit size limits

option 3: platform api advocacy

github's internal upload endpoint (uploads.github.com/upload/policies/assets) works in the web ui via session auth. this could be exposed as a first-party api with pat/oauth support. gh is the official cli — if any tool should drive this api addition, it's this one.

option 4: hybrid (recommended)

implement option 1 as the default (works immediately), while advocating for a proper platform api (option 3) as the long-term solution. when the api lands, swap the implementation transparently — the --attach flag ux stays the same.

why now

the previous requests (#1895 in 2020, #4465 in 2021) were closed when gh was primarily a human-facing cli. today:

• ai agents create issues via gh — claude code, codex, and other coding agents use gh issue create and gh pr create as their primary github interface. they frequently need to attach screenshots, error logs, or generated diagrams.
• gh is the agentic interface to github — as more development workflows become agent-driven, gh is becoming the programmatic bridge. attachments are table-stakes for this use case.
• workarounds exist but aren't discoverable — gh-attach extension uses playwright browser automation, which is brittle and heavy. a first-party solution would be far more reliable.

existing context

all closed as "blocked on platform api" — but option 1 (release asset piggyback) doesn't need a new api. it works today with existing gh capabilities, just needs to be wired together behind a --attach flag.