GitHub CLI 在 2026 年 9 月 1 日发布的 v2.99.0 中，正式引入了可重复使用的 --attach 参数。它做的事情很直接：把本地图片或视频上传到 GitHub，并在 issue、pull request 或评论的 Markdown 正文中内联引用。官方宣布该功能已对所有用户、所有计划正式可用（GA），没有预览期。

命令覆盖与核心行为

--attach 贯穿所有写 Markdown 的 gh 子命令：gh issue create、gh issue edit、gh issue comment、gh pr create、gh pr edit、gh pr comment。参数可重复，意味着一条命令可以附加多个文件。

官方资料特别说明了 Markdown 的两种处理行为：

  1. 原地重写：如果正文中已存在本地路径引用（如 ![alt](./login.png)），gh 会将其替换为上传后的资源，保留原有的 alt 文本。用户可以沿用原有的 Markdown 写法，不需要为了上传改变格式。
  2. 追加兜底：附加了但未被正文引用的文件，会被追加到正文末尾。

alt 文本的指定方式也很简单：路径后加 # 分隔，例如 --attach './login.png#The login error state'。如果省略，则回退到文件名。

媒体类型与大小限制

支持格式包括：PNG、JPEG、GIF、WebP、SVG、MP4、MOV、WebM。大小限制与 GitHub 网页上传流程一致：

  • 图片和 GIF：10 MB；
  • Free 计划视频：10 MB；
  • 付费计划视频：100 MB。

权限与适配范围

官方明确的三项边界：

  • 认证复用 gh 已有的 token 类型：OAuth token（来自 gh auth login）或 classic personal access token；
  • 上传需要目标仓库的写权限；
  • 当前版本不支持 GitHub Enterprise Server。

工程价值判断

从工程角度看，这次更新的本质不是"新增了一个参数"，而是消除了命令行协作中一个长期存在的断点。

此前，开发者通过 gh 提交带截图的 issue 需要这样操作：在终端写好文本 → 打开浏览器 → 粘贴文本 → 拖拽文件 → 复制最终内容回到终端或直接留在网页。现在，截图和描述在同一条命令中完成。官方举的例子很实际：提交 bug 时附上截图，issue 第一次出现就能展示实际错误状态；提交 PR 时带上 before/after，审查者可以直接看到变更结果，而无需拉取分支验证。

对自动化场景，官方明确提到 coding agents 也可以使用该能力。这意味着 agent 完成 UI 验证后，能直接产出带视觉证据的 PR 或评论，而不是只能输出"测试通过"这样的文本结论。对依赖 agent 生成 PR 的团队来说，这降低了人工审查的验证成本。

尚未披露的细节

官方资料没有说明上传后的 URL 形态与存储位置，也没有说明 SVG 上传后的处理机制。对常规使用没有影响，但如果要在 CI 中大规模依赖 --attach 做自动化证据采集，这些细节需要团队在实际环境中自行验证。

上手

升级到 gh v2.99.0，然后运行：

gh issue comment --attach ./screenshot.png

带 alt 文本的写法：

gh issue comment --attach './login.png#The login error state'

完整的参数说明可运行 gh help 查看，官方文档位于 https://docs.github.com/en/github-cli/github-cli/attaching-files-with-github-cli。