GitHub’s September 1, 2026 announcement introduced --attach in GitHub CLI 2.99.0, letting developers and coding agents upload local images or videos into issues, pull requests and comments. The feature is generally available across GitHub plans. This guide covers its access limits and recovery behavior, with sources checked on October 2.
Attach reviewed screenshots to an explicit issue or pull request, then inspect what GitHub saved before retrying. A failed command does not necessarily mean that nothing was posted: GitHub’s PR creation manual explicitly documents a created PR with successful attachments even when another upload fails and the command returns a nonzero exit status.
Check the CLI version, host and repository access
Start with gh --version and the target command’s --help. Version 2.99.0 is the feature floor, not a recommendation to install an old release. On October 2, GitHub’s latest-release API identified 2.102.0, published September 30, as the current stable release.
Attachments work on GitHub.com and GitHub Enterprise Cloud, including GHE.com tenants. GitHub Enterprise Server remains unsupported in 2.102.0. The tagged attachment client requires WRITE, MAINTAIN or ADMIN repository permission. Being able to leave a text comment does not establish permission to upload media.
OAuth and personal access tokens: The 2.99.0 client allowlist includes OAuth, classic PATs and fine-grained PATs. The launch post’s shorter token list is not an exhaustive compatibility matrix.
GitHub App user tokens: Version 2.102.0 adds client acceptance of user-to-server tokens, but the change description says server-side restrictions still apply. This is not blanket support for App installation tokens or the built-in GitHub Actions token.
Exact least-privilege token scopes and every enterprise policy combination were not established by this research. Check the credentials and repository policy used by the actual runner; success with another gh command is not an attachment test.
Check the media and its audience
Review the actual screenshot or recording before upload, including visible credentials, notifications and unrelated customer data. GitHub documents that public-repository attachments can be accessed without signing in; private and internal attachments require repository access.
The 2.102.0 file validator accepts PNG, JPG/JPEG, GIF, WebP, SVG, MP4, MOV and WebM. Do not apply the browser uploader’s wider document-and-archive support to the CLI. GitHub’s documented size limits are:
Media and destination | Maximum per file |
|---|---|
Images and GIFs | 10 MB |
Video in a repository owned by a free-plan user or organization | 10 MB |
Video in a repository owned by a paid-plan user or organization | 100 MB, subject to uploader eligibility |
For videos above 10 MB in paid-owned repositories, the uploader must be an organization member, an outside collaborator, or on a paid plan. GitHub recommends H.264 for browser compatibility. These qualifications come from its upload documentation.
Practical implication: a 30 MB recording can pass the CLI’s local size check yet exceed a free-owned repository’s allowance. The client uses a 100 MiB video precheck; the server applies the plan-dependent limit. Local validation is not confirmation of upload eligibility.
Repeat --attach for multiple files, up to 50 per command. Issue edit can attach to only one issue per invocation. That file-count cap is not a throughput guarantee.
Post a reviewed capture to an existing issue or PR
The flag works with gh issue create, gh issue edit, gh issue comment, gh pr create, gh pr edit and gh pr comment, as listed in GitHub’s announcement. For an existing review thread, select its repository and issue or PR number explicitly.
Prepare review.md with what the capture shows, the relevant commit or run, and any limitations. The following example is illustrative and unrun. Replace HOST/OWNER/REPO, 123, the local paths and the alt description with the authorized destination and reviewed content; executing it uploads the file and posts a comment.
gh issue comment 123 \
--repo HOST/OWNER/REPO \
--body-file ./review.md \
--attach './capture.png#Describe the visible state'For a PR, replace gh issue comment 123 with gh pr comment 456 and use the intended PR number. The issue-comment and PR-comment manuals document these destination and body flags.
If the body contains  and the same file is attached, gh substitutes the uploaded URL and retains the Markdown alt text. Otherwise it appends the attachment; the quoted #description supplies alt text for an appended image. Without a description, the filename is used. The same file cannot be attached twice in one invocation. See GitHub’s placement rules.
Resolve attachment paths and local Markdown paths from the directory where gh runs, as specified in the versioned CLI reference. Keep that working directory consistent when preparing and posting the body.
Videos do not accept alt text. Put a local video image reference such as  alone in a paragraph to get a player after rewriting; inside a sentence it becomes a link. Describe the recording in surrounding prose. These are documented video rules, not a guarantee that every codec renders everywhere.
Preview the local media and body before posting. The versioned reference excludes --attach with --web, with comment --delete-last, and with PR creation --dry-run. Separately, the PR manual warns that dry-run may still push Git changes; it is not an upload rehearsal.
Inspect partial success before deciding what to repeat
Treat media upload and destination write as separate outcomes. Both issue creation and PR creation can save successful attachments, print the new item URL and still exit nonzero. In the 2.102.0 comment implementation, a partial comment can also be written before the upload error is returned. Conversely, uploaded files can remain after a comment write fails.
The tagged upload routine processes files in order and stops at the first failure. Illustrative example, not a test: if A uploads and B fails, C has not been attempted. After inspecting the destination, recovery must account for B and C, while preserving A’s successful URL.
Retain the result. Keep the intended repository and target, returned URL, stdout, stderr and exit status together, without logging credentials.
Inspect the destination. After nonzero status, timeout or an uncertain connection outcome, read the item and its comments. An absent URL is not proof that no write occurred.
Recover only what is missing. If an issue or PR was created, do not replay create. Reconcile its current body and successful media, then make an intentional edit or clearly identified follow-up. Preserve unrelated text and existing uploaded URLs.
Verify the rendered result. Open the saved item and check that the intended media appears with the right explanation. If the outcome remains unclear, hold that operation for review instead of blindly retrying.
For the example issue, this read-only inspection command is also unrun:
gh issue view 123 --repo HOST/OWNER/REPO --json url,body,commentsUse gh pr view 456 for a PR. The issue-view and PR-view manuals list these JSON fields. JSON inspection finds saved text and references; it does not replace checking image or video rendering.
For description recovery, PR edit preserves the existing body when no new body is supplied. Supplying a replacement body requires carrying forward successful URLs and unrelated content. For comments, --edit-last selects the current user’s last comment. Our concurrency inference: several jobs sharing an account cannot treat that selector, even with --create-if-none, as a stable identity for one job’s comment.
Respect any server retry delay. The attachment error handler reports Retry-After for rate limits when provided. Reconcile the destination first, then use bounded retries; the feature does not establish a universal idempotency key or a general-purpose public media-upload API contract.
Use artifacts when inline media is the wrong fit
For workflow-produced bundles, unsupported file types or recordings above the inline limits, consider Actions artifacts or approved storage. GitHub’s artifact documentation requires signed-in readers with repository read access and describes a default 90-day retention period, configurable by repository type. Check audience access, retention and storage cost. Leave enough explanation in the issue for it to remain useful after a temporary download expires.
Uploading an already-reviewed file through gh is separate from granting an agent desktop control. For that earlier capture-and-control decision, see GitHub Copilot Computer Use: Desktop Permissions and When to Enable It.
Methodology: AI-assisted reporting and analysis based on GitHub’s announcement, living documentation, release metadata and tagged CLI source, checked October 2, 2026. No uploads, token combinations, induced failures or rendering tests were run. Commands and recovery recommendations are documentation-derived, not hands-on results.