GitHub CLI v2.99.0 adds a repeatable --attach flag that uploads a local image or video and embeds it directly in the Markdown of an issue, pull request, or comment. For engineers who already work from the terminal, this removes the need to switch to the web UI to add visual context, speeding up debugging, review, and automated reporting.
GitHub CLI media attachment workflow
The flag can be used with any command that writes Markdown: gh issue create, gh issue edit, gh issue comment, gh pr create, gh pr edit, and gh pr comment. It is repeatable, so multiple files can be attached in a single invocation. When a path appears in the body, the CLI rewrites the reference to the uploaded asset while preserving the original alt text, e.g.  becomes a link to the hosted image. If a file is attached but not referenced, the CLI appends a Markdown block at the end of the body.
Alt text can be supplied inline using a hash, for example --attach './login.png#Login error state'. If omitted, the filename is used as the fallback description. Supported formats include PNG, JPEG, GIF, WebP, SVG for images and MP4, MOV, WebM for video. Size limits follow the web upload flow: 10 MB for images and GIFs, 10 MB for video on free plans, and 100 MB for video on paid plans.
Operational considerations
Uploads authenticate with the same token that gh auth login or a classic personal access token provides. The token must have write access to the target repository; otherwise the upload fails. GitHub Enterprise Server does not support this flag, so scripts that run against self‑hosted instances need a fallback. Because the flag is repeatable, CI pipelines can batch screenshots or test‑run videos, but they must respect the size caps and ensure the token used in CI has the required scope.
Security implications
The feature does not introduce a new authentication mechanism; it reuses existing OAuth or PAT credentials. Practitioners should verify that the token used by the CLI has only the permissions required for the automation, avoiding broader scopes that could be abused if the token is exposed. Since the uploaded assets become part of the repository’s public or private storage, consider the sensitivity of the media before attaching it, especially in public repositories.
Related CloudNinjas coverage: DevOps.
What This Means For Practitioners
Upgrade gh to v2.99.0 and incorporate --attach into issue‑creation and PR‑creation scripts to capture screenshots or video output without leaving the terminal. Validate token scopes and repository write permissions in your CI/CD configuration. Monitor the size of attached media to stay within plan limits, and plan for an alternative workflow when operating against GitHub Enterprise Server, which currently lacks support for this flag.