GitHub CLI –attach: Add Images and Videos to Issues and PRs

Quick answer: GitHub CLI 2.99.0 adds a repeatable --attach flag for uploading local images and videos directly to GitHub issues, pull requests, and comments. After updating, the shortest example is gh issue comment 123 --attach './screenshot.png#Login error after submit'.

Copy-paste commands

# Confirm you have GitHub CLI 2.99.0 or newer
gh version

# Add one screenshot to an existing issue
gh issue comment 123 \
  --body "This is the error state after clicking Sign in." \
  --attach './login-error.png#Login form showing an authentication error'

# Add two files to a pull request comment
gh pr comment 456 \
  --body "Before and after the layout fix:" \
  --attach './before.png#Layout before the fix' \
  --attach './after.png#Layout after the fix'

# Create a new issue with a video
# Replace OWNER/REPO with the target repository
gh issue create -R OWNER/REPO \
  --title "Checkout button becomes unresponsive" \
  --body "The attached recording shows the complete reproduction." \
  --attach './checkout-bug.webm'

# Create a PR whose Markdown already references local images
gh pr create \
  --title "Fix mobile navigation overlap" \
  --body-file './pull-request.md' \
  --attach './before.png' \
  --attach './after.png'

GitHub announced the feature on September 1, 2026. It is generally available on GitHub.com across all plans, but requires GitHub CLI 2.99.0 or newer. The supported commands are gh issue create, gh issue edit, gh issue comment, gh pr create, gh pr edit, and gh pr comment. GitHub’s launch announcement lists the availability, commands, file types, limits, and access requirements.

How to update and verify GitHub CLI

1. Run gh version.
2. If the reported version is older than 2.99.0, update gh using the same package manager or installer you originally used.
3. Run gh auth status to confirm that you are signed in to the correct GitHub host and account.
4. Test the flag without creating a new issue by running gh issue comment --help or gh pr comment --help and looking for --attach.

If your package repository has not received 2.99.0 yet, use the current installer or release asset linked from the official GitHub CLI 2.99.0 release. Do not replace a managed company installation without checking your organization’s software policy.

Attach an image with useful alt text

Add image alt text after a # in the attachment argument. Quote the entire argument so the shell does not treat the hash as the start of a comment:

gh issue comment 123 \
  --body "The validation message appears below the hidden field." \
  --attach './validation-error.png#Form showing the email validation error'

If you omit alt text, GitHub CLI uses the filename. Videos do not support alt text. Use a short sentence in the body to explain what a video demonstrates, especially when the important event is not obvious from its first frame. GitHub’s attachment documentation explains the alt-text syntax and video behavior.

Control where an attachment appears

You have two placement options:

• Append automatically: pass a file with --attach without mentioning it in the body. GitHub CLI appends the uploaded media after the text.
• Place it inside your Markdown: reference the same local path in the body. GitHub CLI replaces that local path with the uploaded URL while preserving the surrounding Markdown and image alt text.

For example, save this as pull-request.md:

## Visual check

### Before
![Navigation covering the page title](./before.png)

### After
![Navigation positioned above the page title](./after.png)

## Test notes
- Checked at 320px, 375px, and 768px widths.
- Keyboard focus remains visible.

Then create the pull request:

gh pr create \
  --title "Fix mobile navigation overlap" \
  --body-file './pull-request.md' \
  --attach './before.png' \
  --attach './after.png'

The local image references are rewritten to GitHub-hosted asset URLs. This is particularly useful for reusable bug-report templates, visual regression reports, and coding agents that generate screenshots as evidence.

Supported formats and upload limits

Media	Supported formats	Limit stated by GitHub
Images	PNG, JPEG, GIF, WebP, SVG	10 MB
Video on GitHub Free	MP4, MOV, WebM	10 MB
Video on paid GitHub plans	MP4, MOV, WebM	100 MB

The --attach flag is repeatable, so each file gets its own flag. GitHub’s documentation says you cannot attach the same file twice in one command.

Permissions and security checklist

• Repository access: GitHub says you need push access to the target repository to upload attachments.
• Authentication: uploads use the account authenticated through gh auth login or a compatible classic personal access token.
• Check the file before uploading: screenshots and recordings can expose API keys, email addresses, customer data, browser tabs, internal URLs, terminal history, or notifications.
• Assume persistence: removing a Markdown link later is not the same as proving that every copy of sensitive media has been removed.
• Automation: give a bot only the repository access it needs, and do not place tokens directly in scripts or command history.

Common errors and fixes

Problem	Likely cause	Fix
unknown flag: --attach	GitHub CLI is older than 2.99.0.	Update gh, open a new shell if needed, and confirm with gh version.
Authentication or authorization failure	Wrong account, expired authentication, or insufficient repository access.	Run gh auth status; then confirm you have push access to the target repository.
File is appended instead of placed in the body	The path in Markdown does not exactly match the path passed to --attach.	Use the same relative or absolute path in both places.
Alt text disappears	The shell interpreted an unquoted #, or the Markdown reference supplied different text.	Quote './image.png#Description'. If the body references the file, set alt text in the Markdown.
Video shows as a link rather than a player	The video reference is embedded inside a sentence.	Put the video reference alone in its own paragraph.
Upload rejected	Unsupported format, file too large, or unsupported host.	Check the format and plan limit. GitHub Enterprise Server is not supported in this release.

A safe bug-report template for automation

gh issue create -R OWNER/REPO \
  --title "UI: checkout total overlaps payment button" \
  --label bug \
  --body "$(cat <<'MARKDOWN'
## Summary
The order total overlaps the payment button at 320px width.

## Steps to reproduce
1. Open the checkout page at 320px width.
2. Add two items.
3. Expand the order summary.

## Expected
The total and payment button remain readable and clickable.

## Actual
The total overlaps the payment button.

## Evidence
The screenshot is attached below. It was checked for secrets and customer data before upload.
MARKDOWN
)" \
  --attach './checkout-320.png#Checkout at 320px showing the total over the payment button'

For CI or agent workflows, generate the body in a file and use --body-file instead of building a large shell string. Keep a human approval step before uploading any screenshot captured from an authenticated application.

Frequently asked questions

Which GitHub CLI version adds --attach?

GitHub CLI 2.99.0 adds the media attachment feature. Confirm your installed version with gh version.

Can I attach several images in one command?

Yes. Repeat --attach once for every file. GitHub’s documentation says the same file cannot be attached twice in one command.

Does --attach work with private repositories?

It can work when the authenticated account has the required repository access. GitHub specifically requires push access for attachment uploads.

Does it work on GitHub Enterprise Server?

No. GitHub’s launch announcement says GitHub Enterprise Server is not supported in this release. GitHub.com and GitHub Enterprise Cloud are the supported hosted environments described for version 2.99.0.

Official sources

• GitHub Changelog: Media in issues, pull requests, and comments
• GitHub Docs: Attaching files with GitHub CLI
• GitHub CLI 2.99.0 release