Upload and download GitHub user-attachments (gh-attach)

GitHub has no public API for user-attachments. The web UI uses an internal endpoint that mints github.com/user-attachments URLs whose visibility follows the repository they belong to. gh-attach (MIT, sudosubin) replicates that drag-and-drop flow as a gh CLI extension, so an agent can upload a local file from the terminal, get a URL back, and later download an attachment URL to a file.

Overview

This skill drives gh-attach to turn a local file (screenshot, image, PDF, zip, log, or video) into a hosted GitHub user-attachments URL, then embeds that URL into a pull request, issue, or comment. It also downloads an existing attachment URL back to a local file. GitHub auto-renders the URL as an image, video, or file wherever it is pasted, and the URL inherits the repository's visibility, so a private-repo upload stays private. It works against GitHub Cloud and GitHub Enterprise Server.

When to Use This Skill

Use this skill when asked to:

"Attach a screenshot to the PR" or "add an image to the PR description"
"Attach this file (PDF, zip, log, video) to the issue or comment"
"Embed before/after screenshots" in a PR, issue, or README
"Download this GitHub attachment" from a user-attachments URL

How It Works

Step 1: Verify prerequisites

gh auth status                                   # gh installed and authenticated
gh extension install sudosubin/gh-attach --pin v0.4.2 --force
gh extension list | grep -F 'sudosubin/gh-attach' # require the reviewed v0.4.2 release

Uploads use a GitHub user_session browser cookie, not the gh token (that endpoint rejects tokens). By default gh must be authenticated so gh-attach can select the matching browser account (Chromium family, Firefox family, or Safari). If the wrong account is selected, add --browser <name> --profile <name>. Obtain explicit approval before allowing the pinned extension to access that interactive browser profile. Headless and CI uploads are intentionally unsupported: never export, store, or pass a raw user_session cookie to the extension.

Step 2: Upload

# Use an absolute quoted path; -R is optional inside a repo working dir.
URL=$(gh attach "/abs/path/screenshot.png" -R <owner>/<repo>)

gh attach prints the URL on one line to stdout. For GitHub Enterprise Server, use -R host/owner/repo. Capture the output; it is the embeddable reference.

Step 3: Embed into the PR / issue / comment

printf '## Screenshots\n\n%s\n' "$URL" \
  | gh pr comment <pr> -R <owner>/<repo> --body-file -

Use gh pr edit, gh issue comment, or gh issue edit with --body-file - for other targets. Always pass --body-file - (not inline --body) so multi-line bodies and special characters cannot break shell quoting. GitHub auto-renders the URL, so paste it as-is.

Step 4: Download

# Specify the destination explicitly.
gh attach download "$URL" -O "/abs/path/out.png"

Downloads of private attachments use the active gh token, with browser cookies as an authorization fallback.

Examples

Attach a screenshot to PR #42: upload the file, then append the URL under a ## Screenshots heading in the PR body with gh pr edit ... --body-file -.
Embed before/after screenshots in a README: upload both files, paste the two URLs into the README at the relevant section.
Download an attachment for review: run gh attach download "$URL" -O out.zip to fetch a user-attachments file locally.

Best Practices

Resolve globs to absolute paths first, and quote paths that contain spaces or Unicode.
For display sizing, embed an HTML tag instead of the bare URL: <img width="800" src="$URL">.
Keep uploads interactive. Do not place a GitHub browser session in CI, an environment variable, a secret store consumed by this extension, or an agent log.
gh-attach can upload multiple files concurrently and emit Markdown or JSON output with jq-style filtering when you need to script around the result.

Limitations

Interactive session cookie required. A user_session cookie grants full account access and is not scoped like a PAT. The supported path is the reviewed, pinned extension reading an explicitly approved local browser profile; CI and headless cookie injection are out of scope.
Write access to the target repo is required to upload.
Private-repo attachments stay private: the user-attachments URL inherits repo visibility, so an anonymous fetch on a private repo returns 404 or 403 by design.
GitHub Cloud and GitHub Enterprise Server each decide which file extensions and content types they accept.
The skill embeds the URL itself; gh attach only prints it.

Security & Safety Notes

The user_session cookie is a full-account credential. Never print, export, paste, log, or commit it, and never make it available to CI or headless agents.
Do not install or upgrade gh-attach from a moving branch or an unpinned latest release. Re-review and update the exact --pin only in a repository change.
Uploaded attachments are auto-rendered by GitHub, so only upload files you intend to share with everyone who can view the target repository.
Confirm the destination -R <owner>/<repo> before uploading so an attachment is not created against the wrong repository.