This article is a technical explanation and implementation example created using AI. Although the published code and procedures are based on primary sources, the author has not verified them on actual hardware. Behavior may vary depending on the environment and version.
With updates to the GitHub CLI, the --attach flag has been added, allowing users to upload local images and videos and reference them inline when creating or editing Issues, Pull Requests, and comments. This article provides a detailed breakdown of the specifications, usage points, security, and supported file formats of this feature based on the official Changelog.
What Can Be Confirmed from Official Information
According to primary sources, the GitHub CLI --attach flag is generally available (GA) to users on all plans. To use this feature, you must update the GitHub CLI to v2.99.0 or later.
Traditionally, when creating Issues or Pull Requests from the command line, conveying screen defects, rendering results, or error screens required opening a browser, dragging and dropping the file into the comment section, and copying and pasting the generated link. However, the introduction of the --attach flag makes it possible to directly attach images and videos within the same command used to write the text. This makes it easy to submit screenshots simultaneously with bug reports or show before-and-after comparisons of fixes in Pull Requests. It also allows coding agents to present results not just as text, but as visual images.
Components and Supported Commands
The --attach flag is repeatable and can be used with the following command groups that write Markdown text.
gh issue creategh issue editgh issue commentgh pr creategh pr editgh pr comment
References within Markdown and Automatic Rewriting Behavior
Primary sources explain how local paths already written in the body text are handled. If a local path is referenced in the body text like , it is rewritten on the spot to the uploaded asset, maintaining the specified alternative text (alt text). On the other hand, if a file is attached but never referenced in the body text, it is automatically appended to the end of the body.
How to Specify Alternative Text (Alt text)
To provide a description (alternative text) for the attached file, append a # after the path.
Description example: --attach './login.png#The login error state'
If alternative text is omitted, the GitHub CLI falls back to using the filename as the alternative text.
Supported Media Formats and File Size Limits
Available file formats and size limits are defined in official information as follows:
Supported formats: PNG, JPEG, GIF, WebP, SVG, MP4, MOV, WebM
Size limits (following the web upload flow):
Images and GIFs: Up to 10 MB
Videos (Free plan): Up to 10 MB
Videos (Paid plans): Up to 100 MB
Note that while there is no preview period and the feature is available on all plans, GitHub Enterprise Server is not supported in this release.
Security and Access Control Points
Authentication during upload uses the standard token types already used by the GitHub CLI (OAuth tokens via gh auth login or classic personal access tokens). Additionally, write access is required for the repository to which the images are being uploaded.
Usage Considerations and Future Outlook
[To be verified in a Windows environment] Verification on actual hardware and details of behavior in GUI environments remain verification tasks for the future. In particular, attention must be paid to environment-specific differences, such as how file paths are specified via PowerShell or Command Prompt, and behavior when filenames include Japanese characters.
Official guidance states that detailed flag references can be checked by running gh help. It is recommended to update to the latest environment and proceed with usage while referring to the documentation.
コメント