github-image-upload

Attach images and videos on GitHub

--attach uploads a local image or video on the same command that writes an issue, pull request, or comment: gh issue create, gh issue edit, gh issue comment, gh pr create, gh pr edit, and gh pr comment.

--attach is for images and videos. Inline text in the body as a fenced code block with a language tag.

Prerequisites

1. gh auth status: if it fails, tell the user to run gh auth login.
2. gh --version: needs 2.99.0+. If older, stop and tell the user to upgrade

(brew upgrade gh, or the install they use). Do not upgrade gh yourself.

Attach

State the image and video files and the destination, then attach. Quote --attach values. --attach accepts png, jpg, jpeg, gif, webp, svg, mp4, mov, and webm.

If you are writing the body, put a Markdown image whose destination is the same path you pass to --attach. gh rewrites that path to a user-attachments URL and keeps the alt text from the Markdown:

gh pr comment 13 --body "$(cat <<'EOF'
The error state:

![Error state](/abs/path/error.png)
EOF
)" --attach '/abs/path/error.png'

A video renders as a player only when its image reference is the whole paragraph, with empty alt: ![](/abs/path/walkthrough.mp4).

If you are not rewriting the body, --attach alone appends:

gh pr comment 13 --attach '/abs/path/shot.png#The login error state'
gh pr edit 13 --attach '/abs/path/shot.png#The login error state'

# alt on the flag applies only when the body does not already reference the file. Repeat --attach for each file.

If attach fails, stop and tell the user. Partial success still creates or updates the item and prints its URL, then exits non-zero: treat that as failure until every intended file is present.

Do not commit the attached files.

Text

Inline a transcript, log, or other text in the body as a fenced code block. Set the language to match the content: console for a shell transcript, json for JSON, diff for a diff, text when nothing else fits. Do not pass text files to --attach.

$ pnpm test PASS src/foo.test.ts

Verify

After --attach, count matches instead of printing the body. Expect at least 1 (use gh issue view <n> for issues):

gh pr view <pr> --repo owner/repo --json body,comments \
  -q '[.body] + [.comments[].body] | join("\n")' | grep -c 'user-attachments'

0 means the attach failed. Re-run the attach command. On a private repo the URL renders only for authorized viewers; an anonymous 404/403 is expected.

When the proof is only inlined text, confirm the language-tagged fence is in the body. A missing user-attachments URL is not a failure if you did not attach media.