Tracking: official gh CLI native image/video upload (github/roadmap#1324)

[drogers0]

Summary

The official CLI now has native image/video attachment.

• Roadmap: GitHub CLI: Image upload and attach for issues, PRs, and comments [GA]
• Feature request: cli/cli#13256 (gh-image is mentioned in that thread) — closed as completed 2026-08-25
• Implementation: cli/cli#14186 — 12 PRs, all merged 2026-08-25

Status as of 2026-09-08: released. --attach shipped in gh v2.99.0 on 2026-09-01, announced the same day as GitHub CLI: Media in issues, pull requests, and comments and described there as generally available on all plans. The roadmap item picked up a GA label on 2026-08-21 and is still open with no milestone. v2.100.0 (2026-09-03) added only attachment telemetry (cli/cli#14327).

This issue is tracking/awareness only. It exists so the overlap with gh-image is visible and scope, positioning, and README framing can be settled before the release lands.

What upstream --attach does

A repeatable --attach flag on six commands, wired in pkg/cmd/{issue,pr}/{create,edit,comment}:

gh issue create, gh issue edit, gh issue comment, gh pr create, gh pr edit, gh pr comment

--attach file   Attach an image or video file, in '<file>#<image alt text>' format

gh issue comment 87 --repo monalisa/monas-cafe --body "Menu error below:" --attach ./menu-error.png
gh issue comment 12 --attach './login.png#The login error state'

Placement: if the body contains a markdown reference to an attached local path, that reference is rewritten to the uploaded asset URL; otherwise the asset is appended to the end of the body. Images render as ![alt](url); videos render as a bare URL on its own line, or [name](url) when the reference sits inline.

Alt text handling: supplied after #, defaulting to the filename with its extension stripped and remaining dots replaced by spaces, mirroring the web uploader. Alt text is escaped, and refused outright when it cannot be rendered safely. Videos take no alt text.

Constraints as released (internal/attachments at v2.99.0, verified 2026-09-08 — unchanged from the merge)

	Upstream gh --attach
File types	9 extensions: .png .jpg .jpeg .gif .webp .svg .mp4 .mov .webm
Size	images ≤ 10 MiB, videos ≤ 100 MiB, checked client-side, inclusive
Auth	allowlist of gho_ (OAuth), ghp_ (classic PAT), github_pat_ (fine-grained). Everything else → unsupported authentication type, which covers ghs_ (Actions GITHUB_TOKEN, app installation) and ghu_ (user-to-server)
Permission	allowlist of ADMIN, MAINTAIN, WRITE, measured against their upload endpoint — the code notes READ and TRIAGE get a 404 there
Hosts	GitHub.com and GHEC data-residency tenants (.ghe.com). On-prem GHES is refused: attaching files is not supported on GitHub Enterprise Server
Standalone upload	none — the flag exists only inline on those six commands
Download	not implemented

Other validation, all client-side: an empty --attach value, stdin, directories, non-regular files, zero-byte files, and the same file attached twice are each rejected before any upload.

Non-image/video attachments are not in scope; that ask became cli/cli#14194, which is open, unassigned, and carries the standard backlog reply — "we are not committing to implementing this feature at this time."

Where gh-image still differs

Upstream now covers the common case: a user with write access on GitHub.com attaching a PNG or MP4 to an issue or PR they are creating or commenting on. The README should stop implying the official CLI cannot do this.

Confirmed gaps

• File types. Upstream accepts 9 extensions. We map PDF, zip, logs, source files, YAML, tarballs and more (Support uploading non-image files (PDF, zip, etc.) #23). The widest remaining gap.
• Read-only contributors. Upstream requires ADMIN/MAINTAIN/WRITE. Our browser-session path does not: Write-access requirement is overstated, and invalid sessions fall into the wrong error branch #41 records a successful end-to-end upload against a public repo where the account held pull only, which is why the write-access wording was removed from token.go and the README. The two tools use different endpoints — upstream posts to uploads.github.com/user-attachments/assets with a bearer token and a numeric repository id, while we obtain an uploadToken from the repo page and go through upload/policies/assets → S3 → finalize — so their permission floor does not apply to us. Scope of the test: public repo, read-only. Private-repo read-only and TRIAGE are untested.
• Standalone upload. We return a URL and markdown usable in any body, commit message, gist, or non-gh tool. There is no attachment command upstream, and the package documentation is explicit that the flag only exists inline and the caller must write the returned markdown to a resource. A standalone primitive was requested in #13256 and not built.
• Download. Ours shipped in Support downloading attachments from issues/PRs #42/feat: add download subcommand for user-attachments URLs (#42) #46. Upstream has none, and the long-standing request cli/cli#9046 is labeled blocked and extension-idea, with maintainers stating the platform lacks an attachments API and directing requests to GitHub support rather than the CLI repo. cli/cli#11584 was closed as not planned, with the same explanation: no public API exists for attachment upload or download. Demand there is the same agent-driven use case Support downloading attachments from issues/PRs #42 was opened for.

Mostly not a difference

• CI and automation tokens. Upstream rejects ghs_ and ghu_, so a workflow attaching a screenshot needs a PAT. This is a platform limit rather than a CLI decision, and it binds our bearer path too: cli/cli#14309 reports the endpoint returning 404 for an installation token with write access, where the same request with gho_ succeeds. What remains on our side is the session-cookie path driven by GH_SESSION_TOKEN, which does run in CI but ties automation to a human session.

No longer a difference

• Enterprise. Upstream refuses on-prem GHES but works on GHEC data-residency tenants. Our on-prem support is still an open request (Github Enterprise Support #37), so their host coverage is currently the broader of the two.
• Output formatting. Both emit plain markdown — ![name](url) for images, a bare URL for videos, [name](url) for other files. We have no width or HTML flags, and upstream additionally ships alt-text syntax with escaping.

Also worth noting: cli/cli#14261 documents attachment support in the gh Agent Skill. We ship a skill of our own, and it should be reviewed against theirs.

Related: bearer-token upload (#48)

#48 found that gh auth token works as a Bearer against https://uploads.github.com/user-attachments/assets, and that the token path accepts images and video but rejects other content types. The upstream implementation matches that from the other direction: same endpoint, same images/video scope, same requirement for elevated repository permission. The browser-session path remains the broader one for both file types and permissions.

Community datapoint from the #13256 thread (@labilio, Windows, 2026-08-11): released v1.2.0 failed because the browser user_session cookie could not be decrypted in that environment (#4), and a build from main@d59ac2bb with the token-first path uploaded successfully using the existing gh OAuth token. The token path is doing real work for the users the cookie path loses.

What to watch

• The PR stack merges — 2026-08-25
• Roadmap item marked GA — label applied 2026-08-21
• --attach appears in a stable gh release — v2.99.0, 2026-09-01
• A changelog post lands — 2026-09-01
• Roadmap #1324 closes
• Whether cli/cli#14194 (non-image types) or cli/cli#9046 (download) get picked up — together they are most of the remaining gap
• Whether on-prem GHES support ever appears upstream, and where that leaves Github Enterprise Support #37
• Test read-only upload against a private repo, to bound the Write-access requirement is overstated, and invalid sessions fall into the wrong error branch #41 result
• Rewrite README positioning: lead with file types, read-only access, standalone upload, and download (Reframe the README around the real differences from gh --attach #59, drafted in docs: reframe around gh --attach and document the -- passthrough #60)

[drogers0]

Proposal for integrating with the first-party flag rather than competing with it: #58 — a posting mode (--issue/--pr) that delegates to gh --attach when gh accepts the job and falls back to the session route when it does not, with no mirror of upstream's file-type, size, or permission rules in our code.

[drogers0]

README reframing tracked in #59 — sequenced to land after #58 and shortly after upstream releases, so the comparison is reproducible and the tool is described as it will then be.

[drogers0]

Resolved

This was opened to make the overlap with gh --attach visible so scope, positioning and README framing could be settled. All three are done.

• Upstream released. --attach shipped in gh v2.99.0 on 2026-09-01, with a changelog post the same day describing it as generally available on all plans.
• We wrap it rather than compete. Pass through to gh with a "--" separator, delegating to gh --attach when it can do the job #58 landed the -- passthrough: a gh command after -- is forwarded, eligible files go through gh --attach, everything else takes the existing routes with the body's references rewritten. Verified live against gh v2.100.0 and against v2.98.0 for the no---attach case.
• Positioning settled. Reframe the README around the real differences from gh --attach #59 reframed the README around the four confirmed gaps plus CI, and dropped the two claims that did not survive checking — enterprise coverage and output formatting.
• Both shipped in v1.4.0.

The constraint table above was verified against the released v2.99.0 and is accurate as of 2026-09-08.

Still worth watching, elsewhere

• github/roadmap#1324 is still open with no milestone, despite the feature having shipped.
• cli/cli#14194 (non-image types) and cli/cli#9046 (download) are the two that would close most of our remaining gap. Both open, neither committed to.
• cli/cli#14302 (read-only reporters) and cli/cli#14309 (installation tokens) track the two limits users have already hit; a maintainer has called the token exclusion intended for now.
• On-prem GHES remains unsupported by both, tracked here as Github Enterprise Support #37.
• Read-only upload against a private repo is still untested; Write-access requirement is overstated, and invalid sessions fall into the wrong error branch #41's evidence is a public repo with pull access.

Reopen if the picture changes.