从官方信息解读 GitHub CLI 通过 –attach 标志向 Issue、PR 和评论添加媒体的功能

本文是一篇利用 AI 生成的技术解析与实现示例。所发布的代码和步骤基于第一手资料构建，但未经作者在真实设备上进行运行验证。根据环境和版本的不同，运行结果可能会有所差异。

随着 GitHub CLI 的更新，现已新增 --attach 标志，允许在创建或编辑 Issue、Pull Request 以及评论时上传本地图片或视频并进行内联引用。本文将根据官方的更新日志（Changelog），详细整理该功能的规范、使用要点、安全性以及支持的文件格式等内容。

---

从官方信息中可以确认的内容

根据第一手资料显示，GitHub CLI 的 --attach 标志已向所有计划的用户全面推出（GA）。要使用此功能，您需要将 GitHub CLI 更新至 v2.99.0 或更高版本。

以往，从命令行创建 Issue 或 Pull Request 时，若要传达屏幕故障、渲染结果或错误画面等信息，必须先打开浏览器将文件拖放到评论区，然后复制并粘贴生成的链接。然而，随着 --attach 标志的出现，现在可以直接在编写文本的同一个命令中附加图片或视频。这使得在报告漏洞时能够同时发送截图，或者在 Pull Request 中轻松展示修改前后的对比。此外，它还允许编码代理（Coding Agent）不仅提供文本，还能以直观的图片形式呈现结果。

---

组成要素与支持的命令

--attach 标志支持重复指定（可重复使用），并可在编写 Markdown 文本的以下命令组中使用。

• gh issue create

• gh issue edit

• gh issue comment

• gh pr create

• gh pr edit

• gh pr comment

Markdown 内的引用与自动重写行为

第一手资料中说明了正文中已编写的本地路径的处理方式。如果在正文中通过 ![alt](./login.png) 等形式引用了本地路径，它将被即时重写为上传的资源，并保留指定的替代文本（alt text）。另一方面，如果附加了文件但在正文中从未引用，它将自动追加到正文的末尾。

替代文本（Alt text）的指定方法

如果要为附加的文件赋予说明（替代文本），请在路径后面加上 # 进行编写。 编写示例：--attach './login.png#The login error state'

如果省略了替代文本，GitHub CLI 将默认使用文件名作为替代文本。

---

可发布的媒体格式与文件大小限制

关于可用的文件格式和大小限制，官方信息定义如下：

• 支持的格式：PNG、JPEG、GIF、WebP、SVG、MP4、MOV、WebM

• 大小限制（遵循网页上传流程）：

  • 图片及 GIF：最大 10 MB

  • 视频（免费计划）：最大 10 MB

  • 视频（付费计划）：最大 100 MB

需要说明的是，此功能未设预览期，所有计划均可使用，但本次发布暂不支持 GitHub Enterprise Server。

---

安全与访问控制要点

在上传时的身份验证，将使用 GitHub CLI 已经在使用的通用令牌类型（通过 gh auth login 获取的 OAuth 令牌，或经典的个人访问令牌）。此外，需要对上传图片的目标仓库具备写入权限（Write access）。

---

使用时的注意事项与未来展望

【计划在 Windows 环境下确认】 实机操作验证以及 GUI 环境下行为的详细信息，将作为今后的验证课题。特别是在通过 PowerShell 或命令提示符指定文件路径的方法，以及包含日文文件名时的行为等方面，需要注意不同环境之间的差异。

根据官方指南，执行 gh help 可以查看详细的标志参考。建议在更新到最新环境后，参考文档继续使用。

---

参考信息

• GitHub Changelog: GitHub CLI: Media in issues, pull requests, and comments