github-image-upload

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Upload images and files to GitHub (gh-image)

上传图片和文件到GitHub (gh-image)

GitHub has no public API for attachment uploads — the web UI uses an internal endpoint that mints

user-attachments

URLs scoped to the repo's visibility.

gh-image

(MIT, © drogers0) replicates that flow as a

gh

CLI extension, so you can upload images or other files (PDF, zip, log, …) from the terminal and get a ready-to-paste reference back — an

![name](url)

embed for images, a bare URL for videos (GitHub renders it as an inline player), or a

[name](url)

download link for other files.

This skill drives

gh-image

and then embeds the result into a PR/issue/comment.

GitHub 没有用于附件上传的公开API——网页端UI使用一个内部端点生成与仓库可见性绑定的

user-attachments

链接。

gh-image

（MIT协议，© drogers0）将该流程复刻为一款

gh

CLI扩展，让你可以从终端上传图片或其他文件（PDF、zip、日志等），并直接获得可粘贴的引用——图片对应

![name](url)

嵌入格式，视频对应纯链接（GitHub会将其渲染为内嵌播放器），其他文件则对应

[name](url)

下载链接。

本技能调用

gh-image

并将结果嵌入到PR/Issue/评论中。

Prerequisites — verify these before uploading

前置条件——上传前请确认以下事项

Run these checks; only act on the ones that fail.

gh
CLI installed & authenticated
bash
```
gh auth status
```
If it fails, tell the user to run
```
gh auth login
```
(do not attempt it unattended).

The
gh-image
extension installed (idempotent — skip if already present)

bash

gh extension list | grep -q 'drogers0/gh-image' || gh extension install drogers0/gh-image

A GitHub session for the upload.
```
gh-image
```
does NOT use the
```
gh
```
token for the upload (that endpoint rejects tokens); it needs the browser
```
user_session
```
cookie. Resolution order (first match wins):
- ```
--token <value>
```
  flag, or
- ```
GH_SESSION_TOKEN
```
  env var (use this in CI / headless), or
- the cookie store of a logged-in browser (Chrome/Brave/Chromium/Edge/Firefox/ Opera/Safari) — the default for local use. On macOS the first read may show a Keychain prompt; the user should click Always Allow.
⚠️ A
```
user_session
```
cookie grants full account access (it is not scoped like a PAT). Treat it like a password; in CI use a dedicated bot account.

执行以下检查，仅处理未通过的项。

gh
CLI已安装并完成认证
bash
```
gh auth status
```
如果检查失败，请告知用户运行
```
gh auth login
```
（请勿自动执行该操作）。

已安装
gh-image
扩展（幂等操作——若已安装可跳过）

bash

gh extension list | grep -q 'drogers0/gh-image' || gh extension install drogers0/gh-image

用于上传的GitHub会话。
```
gh-image
```
不会使用
```
gh
```
令牌进行上传（该端点拒绝令牌）；它需要浏览器的
```
user_session
```
Cookie。优先级顺序（匹配到第一个即生效）：
- ```
--token <value>
```
  参数，或
- ```
GH_SESSION_TOKEN
```
  环境变量（适用于CI/无头环境），或
- 已登录浏览器的Cookie存储（支持Chrome/Brave/Chromium/Edge/Firefox/Opera/Safari）——本地使用的默认方式。在macOS上首次读取时可能会弹出钥匙链提示，用户应点击始终允许。
⚠️
```
user_session
```
Cookie授予完整账户访问权限（不像PAT那样有范围限制）。请像对待密码一样妥善保管；在CI环境中请使用专用机器人账户。

Step 1 — Normalize the file path

步骤1——标准化文件路径

Use an absolute path. If a glob is given, resolve it first. Paths with spaces or Unicode (e.g. CleanShot's narrow spaces) work, but quote them.

使用绝对路径。如果给定通配符，先解析路径。包含空格或Unicode字符的路径（例如CleanShot的窄空格）可以正常使用，但需要加引号。

Step 2 — Upload

步骤2——上传

bash

undefined

bash

undefined

One or more files (images or PDF/zip/log/…); --repo is optional inside a repo

单个或多个文件（图片或PDF/zip/日志等）；在仓库工作目录中时--repo参数可选（会自动从远程仓库推断）。

working dir (inferred from the remote).

—

gh image "/abs/path/screenshot.png" --repo <owner>/<repo>


`gh image` prints the reference to **stdout** — an image embed for images, a bare
URL for videos (GitHub renders it as an inline player), and a download link for
other files, e.g.:

https://github.com/user-attachments/assets/<uuid> report.pdf


Capture that output — it is the embeddable reference. For multiple files it prints
one line per file.

gh image "/abs/path/screenshot.png" --repo <owner>/<repo>


`gh image` 将引用输出到**标准输出**——图片对应图片嵌入格式，视频对应纯链接（GitHub会渲染为内嵌播放器），其他文件对应下载链接，例如：

https://github.com/user-attachments/assets/<uuid> report.pdf


捕获该输出——这就是可嵌入的引用。如果上传多个文件，每个文件对应一行输出。

Step 3 — Embed into the PR / issue / comment

步骤3——嵌入到PR / Issue / 评论中

gh-image

only prints the markdown; you embed it. Pick the target the user asked for.

Append to a PR description (preserves the existing body):

bash

MD="$(gh image "/abs/path/shot.png" --repo owner/repo)"
BODY="$(gh pr view <pr> --repo owner/repo --json body -q .body)"
printf '%s\n\n## Screenshots\n\n%s\n' "$BODY" "$MD" \
  | gh pr edit <pr> --repo owner/repo --body-file -

Post as a new PR comment:

bash

MD="$(gh image "/abs/path/shot.png" --repo owner/repo)"
printf '## Screenshots\n\n%s\n' "$MD" | gh pr comment <pr> --repo owner/repo --body-file -

Add to an issue body / comment: same pattern with

gh issue edit <n> --body-file -

gh issue comment <n> --body-file -

Always use

--body-file -

(not inline

--body

) so multi-line bodies and special characters can't break shell quoting.

gh-image

仅输出Markdown内容，需要你将其嵌入。根据用户指定的目标进行操作。

追加到PR描述中（保留原有内容）：

bash

MD="$(gh image "/abs/path/shot.png" --repo owner/repo)"
BODY="$(gh pr view <pr> --repo owner/repo --json body -q .body)"
printf '%s\n\n## 截图\n\n%s\n' "$BODY" "$MD" \
  | gh pr edit <pr> --repo owner/repo --body-file -

发布为新的PR评论：

bash

MD="$(gh image "/abs/path/shot.png" --repo owner/repo)"
printf '## 截图\n\n%s\n' "$MD" | gh pr comment <pr> --repo owner/repo --body-file -

添加到Issue内容/评论： 使用相同模式，替换为

gh issue edit <n> --body-file -

或

gh issue comment <n> --body-file -

。

请始终使用

--body-file -

（而非内联的

--body

），这样多行内容和特殊字符不会破坏shell引号规则。

Step 4 — Verify

步骤4——验证

bash

gh pr view <pr> --repo owner/repo --json body -q .body   # confirm the URL is present

The

user-attachments

URL inherits the repo's visibility, so on a private repo it renders only for authorized viewers (an anonymous fetch returns 404/403 — that is expected, not a failure).

bash

gh pr view <pr> --repo owner/repo --json body -q .body   # 确认链接已存在

user-attachments

链接继承仓库的可见性，因此在私有仓库中，仅授权用户可查看（匿名访问会返回404/403——这是预期行为，并非错误）。

Sizing (optional)

尺寸调整（可选）

To control display size, embed an HTML tag instead of the bare markdown:

html

<img width="800" alt="screenshot" src="https://github.com/user-attachments/assets/<uuid>" />

如需控制显示尺寸，使用HTML标签替代纯Markdown格式：

html

<img width="800" alt="screenshot" src="https://github.com/user-attachments/assets/<uuid>" />

Troubleshooting

故障排除

Symptom	Cause / fix
`<org> enforces SAML SSO and your session is not authorized…`	The org requires SSO and your session isn't authorized. Open the `https://github.com/orgs/<org>/sso` URL from the message in a browser, authorize (lasts ~24h), then retry. Write access alone is not enough — this is not a permissions problem.
`uploadToken not found … do you have write access?`	The generic no-token case. Confirm you have write access; if the repo's org uses SSO, authorize at `https://github.com/orgs/<org>/sso` (the message includes this hint) and retry.
No `user_session` cookie found	Log into GitHub in a supported browser, or set `GH_SESSION_TOKEN` .
Windows + Chrome 127+ can't read cookies	Known cookie-library limitation — use another browser or `GH_SESSION_TOKEN` .
CI / headless run	Set `GH_SESSION_TOKEN` (dedicated bot account); the browser cookie path won't exist.
`gh: command not found`	Install the GitHub CLI ( `brew install gh` , etc.).

症状	原因/解决方法
`<org> enforces SAML SSO and your session is not authorized…`	该组织要求SSO且你的会话未授权。在浏览器中打开消息中的 `https://github.com/orgs/<org>/sso` 链接，完成授权（有效期约24小时），然后重试。仅拥有写入权限不足——这并非权限问题。
`uploadToken not found … do you have write access?`	通用的无令牌情况。确认你拥有写入权限；如果仓库所属组织使用SSO，请访问 `https://github.com/orgs/<org>/sso` 完成授权（消息中包含该提示），然后重试。
No `user_session` cookie found	在支持的浏览器中登录GitHub，或设置 `GH_SESSION_TOKEN` 环境变量。
Windows + Chrome 127+无法读取Cookie	已知的Cookie库限制——使用其他浏览器或设置 `GH_SESSION_TOKEN` 。
CI / 无头环境运行	设置 `GH_SESSION_TOKEN` （使用专用机器人账户）；浏览器Cookie路径不存在。
`gh: command not found`	安装GitHub CLI（例如 `brew install gh` 等）。