Back to Details

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.
  1. gh
    CLI installed & authenticated
    bash
    gh auth status
    If it fails, tell the user to run 
    gh auth login
    (do not attempt it unattended).
  2. 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
  3. 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.
执行以下检查，仅处理未通过的项。
  1. gh
    CLI已安装并完成认证
    bash
    gh auth status
    如果检查失败，请告知用户运行
    gh auth login
    （请勿自动执行该操作）。
  2. 已安装
    gh-image
    扩展    （幂等操作——若已安装可跳过）
    bash
    gh extension list | grep -q 'drogers0/gh-image' || gh extension install drogers0/gh-image
  3. 用于上传的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.:
screenshot.png 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会渲染为内嵌播放器），其他文件对应下载链接，例如：
screenshot.png 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 -
or 
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

故障排除

SymptomCause / 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 cookiesKnown cookie-library limitation — use another browser or 
GH_SESSION_TOKEN
.
CI / headless runSet 
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
等）。