gh-attach uploads the same kinds of attachments GitHub's web UI supports for issues, pull requests, and discussions: images, videos, and common document/code/archive files.
The happy path is one command:
gh-attach screenshot.pngAnd the power path stays small:
gh-attach clip.mp4 report.pdf --repo owner/repo --jsonOne-line install:
curl -fsSL https://github.com/ain3sh/gh-attach/releases/latest/download/install.sh | shInstall to a custom directory:
curl -fsSL https://github.com/ain3sh/gh-attach/releases/latest/download/install.sh | sh -s -- --bin-dir "$HOME/bin"Pin a specific version:
curl -fsSL https://github.com/ain3sh/gh-attach/releases/latest/download/install.sh | sh -s -- --ref v0.1.0The bootstrap script downloads the latest published release source by default and builds locally, so go must already be installed.
From a local checkout:
./install.shFrom a local checkout, install to a custom directory:
./install.sh --bin-dir "$HOME/bin"Build manually:
go build -o gh-attach .If you publish it as a GitHub CLI extension, GitHub CLI will expose the same binary as:
gh attachRun directly from the checkout:
go run . screenshot.png --repo owner/repogh-attach [--repo owner/repo] [--auth auto|token|cookie] [--auto|--link|--md|--url|--json|--format auto|link|url|json] FILE...If installed as a GitHub CLI extension, the same binary is typically invoked as:
gh attach FILE...gh-attach FILE... # default: markdown links
gh-attach FILE... --repo OWNER/REPO # explicit target repo
gh-attach FILE... --auto # image => , else raw URL
gh-attach FILE... --url # raw URLs
gh-attach FILE... --json # JSON objects
gh-attach FILE... --auth token # force API-token upload (no cookie fallback)
gh-attach FILE... --auth cookie # force the browser-cookie flow
gh-attach FILE... --user ACCOUNT # use a specific logged-in gh account's token
gh-attach -- FILE... # filenames that begin with '-'
Upload an image from the current repo:
gh-attach screenshot.pngUpload a regular file and get a Markdown link:
gh-attach report.pdfUpload several attachments at once:
gh-attach image.png clip.mp4 report.pdfUpload several attachments to an explicit repo:
gh-attach clip.mp4 report.pdf logs.zip --repo owner/repoMatch GitHub's web-style output:
gh-attach --auto screenshot.png clip.mp4Emit plain URLs:
gh-attach --url report.pdfEmit structured JSON:
gh-attach --json screenshot.pngPass a filename that starts with -:
gh-attach -- --trace.log| Flag | Behavior |
|---|---|
default / --link / --md |
Always prints a Markdown link: [name](url) |
--auto |
Prints  for images, plain URLs for everything else |
--url |
Prints the raw uploaded URL |
--json |
Prints a JSON object with URL, name, MIME type, size, and category |
--format auto|link|url|json is the long-form equivalent when you want to generate flags programmatically.
gh-attach uploads through GitHub's API-token attachment endpoint whenever a token is available, and falls back to the browser-cookie flow otherwise.
Token resolution order:
GH_TOKENGITHUB_TOKENgh auth token
This means gh-attach works out of the box wherever the gh CLI is authenticated, including headless CI (GitHub Actions provides GITHUB_TOKEN ambiently).
The token needs write access to the target repository. gh-attach checks this before uploading, using the permissions returned by the repository lookup it already performs, so a no-access token produces a precise message instead of GitHub's ambiguous 404. If another logged-in gh account does have write access, the message names it:
Note: the active gh account has no write access to owner/repo; gh account "other-account" has write access — rerun with --user other-account; falling back to browser-cookie auth
In multi-account setups, pick the token account explicitly:
gh-attach screenshot.png --user other-accountThe token endpoint accepts a much narrower set of file types than GitHub's web UI:
| Token endpoint | Cookie flow | |
|---|---|---|
png, jpg, jpeg, gif, svg, webp |
yes | yes |
mp4, mov, webm |
yes | yes |
Documents, text, code, archives, audio, bmp, tif |
no | yes |
gh-attach routes each file accordingly, so a mixed upload works in one command: images go over the token endpoint, everything else over the cookie flow.
gh-attach screenshot.png report.pdf # png via token, pdf via cookiesSelect the transport explicitly with --auth:
| Mode | Behavior |
|---|---|
--auth auto (default) |
Token endpoint for the types it accepts, cookie flow for the rest; also falls back on 401/403/404/410 |
--auth token |
API token only; fails on types the endpoint does not accept |
--auth cookie |
Browser-cookie flow only |
Because the token path needs no browser at all, headless environments can upload images and videos with nothing but a token. Other file types still require the cookie flow.
When no token is available, or the token endpoint rejects the request, gh-attach reads your GitHub auth cookies from a supported local browser profile. The cookie flow can succeed where a token cannot, for example attaching to issues in repositories you can comment on but not push to.
Supported browser sources:
- Chrome
- Brave
- Chromium
- Edge
- Firefox
- Zen
For Firefox-derived browsers such as Firefox and Zen, gh-attach also reads live session cookies from sessionstore-backups/*.jsonlz4 so authenticated uploads keep working even when cookies.sqlite alone is not enough. Because browsers keep cookies.sqlite in WAL mode, gh-attach checkpoints a temporary copy of the database before reading it, so a session refreshed moments ago is still visible.
Inspect what auth source gh-attach will use:
gh-attach auth doctorExport a reusable auth-cookie file:
gh-attach auth export --session-file "$HOME/.config/gh-attach/session.json"For headless or scripted environments, set:
export GH_ATTACH_USER_SESSION=...Or reuse an exported session file directly:
gh-attach report.pdf --session-file "$HOME/.config/gh-attach/session.json"If --repo is omitted, gh-attach tries to infer the target repo from:
git remote get-url originIt then resolves the numeric repository ID via:
gh api repos/{owner}/{repo} --jq .idSo the gh CLI must be installed and authenticated.
The CLI is built around the file classes GitHub documents for comment attachments, including:
- Images:
png,gif,jpg,jpeg,svg,webp,bmp,tif,tiff - Videos:
mp4,mov,webm - Documents:
pdf, Office docs, OpenDocument files,rtf,doc - Text/data/code:
txt,md,json,log,csv,py,ts,tsx,html,xml,yaml, and more - Archives/audio/log-style files:
zip,gz,tgz,mp3,wav,msg,eml,debug
The CLI validates against GitHub's attachment limits before upload:
- Images and GIFs: 10 MB
- Videos: 10 MB on free plans, up to 100 MB on paid plans
- Other files: 25 MB
These are enforced server-side and confirmed against the live API: a 15 MB image is rejected, a 90 MB video succeeds while 110 MB is rejected, and a 30 MB document is refused with 25 MB are allowed. Validating locally just turns a slow failed upload into an instant error.
For videos above 10 MB, the CLI warns instead of failing because the final outcome depends on the repository plan and your access level.
The primary path is a single request to GitHub's undocumented token-authenticated attachment endpoint:
POST https://uploads.github.com/user-attachments/assets?name=...&content_type=...&repository_id=...
Authorization: Bearer <token>
GitHub responds with the https://github.com/user-attachments/assets/... URL, the same kind of reference the web UI produces when you drag-and-drop a file. This endpoint only accepts images and videos.
For every other file type, and because the endpoint is undocumented and could disappear, gh-attach keeps the web UI's internal cookie-based flow:
- Resolve GitHub auth cookies from
--session-file,GH_ATTACH_USER_SESSION, or a supported browser profile - Fetch the repository page and extract the upload token
- Request an upload policy from GitHub
- Upload the file to GitHub's temporary S3 target
- Finalize the upload using GitHub's returned asset endpoint and print the resulting attachment reference
Both paths produce attachments scoped the way GitHub's web uploads are, including private-repo behavior.
This project was inspired by drogers0/gh-image, which proved out the core GitHub asset-upload flow for images. gh-attach extends that idea to cover the broader set of attachment types supported by GitHub's web UI.
The token-authenticated primary path comes from Ben Sheldon's write-up of the uploads.github.com/user-attachments/assets endpoint, surfaced via Intercom's attach-github-assets skill.