Skip to content
ain3shPublic

About

No description, website, or topics provided.

Resources

Stars

27 stars

Watchers

0 watching

Forks

Latest commit

 

History

15 Commits

Folders and files

Repository files navigation

gh-attach

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.

Quick start

The happy path is one command:

gh-attach screenshot.png

And the power path stays small:

gh-attach clip.mp4 report.pdf --repo owner/repo --json

Install

One-line install:

curl -fsSL https://github.com/ain3sh/gh-attach/releases/latest/download/install.sh | sh

Install 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.0

The bootstrap script downloads the latest published release source by default and builds locally, so go must already be installed.

From a local checkout:

./install.sh

From 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 attach

Run directly from the checkout:

go run . screenshot.png --repo owner/repo

Usage

gh-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...

One-glance CLI prototype

gh-attach FILE...                   # default: markdown links
gh-attach FILE... --repo OWNER/REPO # explicit target repo
gh-attach FILE... --auto            # image => ![name](url), 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 '-'

Simple examples

Upload an image from the current repo:

gh-attach screenshot.png

Upload a regular file and get a Markdown link:

gh-attach report.pdf

Upload several attachments at once:

gh-attach image.png clip.mp4 report.pdf

More advanced examples

Upload several attachments to an explicit repo:

gh-attach clip.mp4 report.pdf logs.zip --repo owner/repo

Match GitHub's web-style output:

gh-attach --auto screenshot.png clip.mp4

Emit plain URLs:

gh-attach --url report.pdf

Emit structured JSON:

gh-attach --json screenshot.png

Pass a filename that starts with -:

gh-attach -- --trace.log

Output modes

Flag Behavior
default / --link / --md Always prints a Markdown link: [name](url)
--auto Prints ![name](url) 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.

Authentication

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:

  1. GH_TOKEN
  2. GITHUB_TOKEN
  3. gh 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-account

What each transport can upload

The 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 cookies

Select 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.

Cookie fallback

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 doctor

Export 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"

Repository targeting

If --repo is omitted, gh-attach tries to infer the target repo from:

git remote get-url origin

It then resolves the numeric repository ID via:

gh api repos/{owner}/{repo} --jq .id

So the gh CLI must be installed and authenticated.

Supported attachments

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

Size limits

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.

How it works

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:

  1. Resolve GitHub auth cookies from --session-file, GH_ATTACH_USER_SESSION, or a supported browser profile
  2. Fetch the repository page and extract the upload token
  3. Request an upload policy from GitHub
  4. Upload the file to GitHub's temporary S3 target
  5. 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.

Inspiration

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.

About

No description, website, or topics provided.

Resources

Stars

27 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages