A screenshot or screen recording in a pull request usually means dragging the file into GitHub in a browser, which a script or CI job cannot do, so the image gets committed or left out. ghattach does that upload from a terminal and prints the link to paste, so nothing is committed.
This project is not affiliated with or endorsed by GitHub. It uses an undocumented endpoint that GitHub can change or withdraw. Use is subject to GitHub’s Terms of Service and Acceptable Use Policies. Attachments are not a general-purpose hosting service; automated bulk uploads may be restricted.
A local screenshot becomes a PR attachment; no image committed to git. Demo details.
Implementation flow
sequenceDiagram
actor You
participant G as ghattach
participant Local as Chrome and a local cookie file
participant GH as GitHub
participant S as user-attachments CDN
You->>G: log in from Chrome
G->>Local: copy Chrome's GitHub cookie to the file
You->>G: upload shot.png
G->>GH: look up the repo id with gh, then ask for an upload slot with the cookie
G->>S: send the file, no cookie
G->>GH: confirm the upload with the cookie
GH-->>G: user-attachments URL
G-->>You: print the Markdown link
ghattach keeps a copy of your GitHub browser session in a file on your machine. It asks GitHub for an upload slot with that session, the same way the browser does when you drag a file in, and prints the link GitHub returns. GitHub has no public API for this upload.
You need Go 1.26.10 or later, write access to the repository, and the GitHub CLI signed in, which ghattach uses to look up the repository id.
-
Install ghattach.
go installputs it in$(go env GOPATH)/bin, which must be on yourPATH.go install github.com/tetriz-ai/ghattach/cmd/ghattach@latest
-
Log in from Chrome on macOS, signed in to github.com. Choose "Allow" for this request when macOS asks for "Chrome Safe Storage". Repeat the approval when prompted. "Always Allow" gives
/usr/bin/securitystanding access to the key that decrypts Chrome cookies across sites, allowing other local processes to use that access.The stored session can act as your whole GitHub account, so log in only on a machine you trust. On Linux or with another browser, paste the cookie value instead.
$ ghattach login --from-chrome Session stored at /Users/you/.config/ghattach/cookies.json Verify with: ghattach upload <file> --repo OWNER/REPO
-
Upload an image and paste the printed line into a pull request or issue.
$ ghattach upload shot.png --repo OWNER/REPO --markdown 
To see these steps work without a GitHub account, run examples/embed-one-screenshot/run.sh
from a clone. It runs them against a local stub of GitHub. Release archives and other routes are
in docs/install.md, and what to do when the session expires is in
docs/usage.md.
| Use | When you want to |
|---|---|
ghattach upload |
Get a link or Markdown embed for files to paste into a pull request, issue or comment |
ghattach login |
Store your GitHub session, read from Chrome on macOS or pasted in |
ghattach logout |
Delete the stored session from a machine you are done with |
ghattach completion |
Load shell completion for bash, fish, PowerShell or zsh |
What it does not do:
- No token login. GitHub's upload endpoint rejects personal access and app tokens.
- No delete, list or download. ghattach only uploads.
- No GitHub Enterprise Server. Uploads go to github.com only.
--markdown prints an image embed, a bare URL for a video so GitHub shows its player, and a
link for any other file. examples/video-and-files runs this against the local stub.
$ ghattach upload shot.png demo.mp4 build.log --repo OWNER/REPO --markdown

https://github.com/user-attachments/assets/<uuid>
[build.log](https://github.com/user-attachments/assets/<uuid>)Look up the repository id once wherever gh works, then pass it with --repo-id on a machine
without gh, such as a CI runner. examples/ci-comment is a whole CI upload step.
$ gh api repos/OWNER/REPO --jq .id
123456789
$ ghattach upload shot.png --repo OWNER/REPO --repo-id 123456789
https://github.com/user-attachments/assets/<uuid>Pipe the value of GitHub's user_session cookie, such as a stored secret, into login --cookie -.
The prompt prints with no newline, so the output continues on its line. This is a full-account
session, not a repository-scoped token: possession can bypass a fresh password and two-factor
challenge. For CI, use a dedicated machine account with access only to a throwaway public test
repository. Keep the secret in a protected environment with required reviewers; never expose it
to pull-request code. See CI setup.
$ printf '%s\n' "$GITHUB_SESSION" | ghattach login --cookie -
Paste the user_session VALUE, then Enter: Session stored at /home/you/.config/ghattach/cookies.json
Verify with: ghattach upload <file> --repo OWNER/REPOlogout deletes the local copy only. Revoke the session on GitHub if it may have leaked.
$ ghattach logout
Removed /home/you/.config/ghattach/cookies.json
Also revoke the browser session if it is no longer wanted: https://github.com/settings/sessions- The stored session is your whole GitHub account. Log in only on machines you trust.
- Uploads to a public repository are public, and cannot be deleted. Check each file before you upload it.
- On macOS, an expired session may switch accounts. Pin one by logging in with
--from-chrome --chrome-profile. - A GitHub refusal stops the run. Earlier files stay uploaded, so keep their links.
- GitHub can change the upload endpoint at any time. Do not let a failed upload fail a build.
The full list, with what to do about each one, is in docs/limitations.md.
- docs/reference.md: every flag, output rule, exit status and file location.
- docs/install.md: release archives, checksums and the pasted-cookie login.
- docs/usage.md: expired sessions, CI jobs, profiles and GitHub's size limits.
- examples/: complete scripts that run against a local stub, with no GitHub account.
- CONTRIBUTING.md, SECURITY.md and the MIT License.
- Parts of the upload client are adapted from gh-image, as NOTICE records.
Releases follow Semantic Versioning and list their changes in CHANGELOG.md. Before v1.0.0 a breaking change ships in a new minor version. What counts as breaking is in docs/reference.md.
Copyright 2026 Workloom Solutions Private Limited. CONTRIBUTORS.md lists the project's team.
