GitHub App

Optional, but nicer: bot-posted comments and live PR/issue titles.

App installed — you're done. There is nothing to configure on this side. The CLI notices the installation automatically the next time you run uploads attach.

What it adds #

Everything in these docs works without the App. Installing the uploads-sh GitHub App on your repos upgrades three things:

Comments post as uploads-sh[bot]. The managed "📎 Attachments" comment is created and updated by the App on the server, instead of under your own GitHub identity via the local gh CLI. That keeps attachment noise off your account — and it works in environments with no gh auth at all.
File pages show titles for private repos. A file attached to a PR or issue gets a share page that names its PR or issue. For public repos that works out of the box; for private repos the App is what grants read access to the title.
Titles stay current. The App's webhooks tell uploads.sh when a PR or issue is renamed, closed, or merged, so file pages don't show stale titles.
Screenshots staged before the PR exists get promoted automatically.See Staging before a PR exists below.

Install it #

Install from github.com/apps/uploads-sh. Pick the organization or account, then choose the repositories you attach files to — "only select repositories" is fine, and you can add more later from GitHub's settings.

That's the whole setup. The next uploads attach against an installed repo prints (uploads-sh[bot]) instead of (via gh):

uploads attach ./after.png

>> uploading ./after.png
>> attachments comment updated (uploads-sh[bot])

Staging before a PR exists #

Working on a branch with no PR open yet? --branch stages screenshots against the branch instead of a PR — no comment to post yet, nothing to target:

uploads attach --branch ./progress.png

It defaults to your current git branch (or pass --branch some-nameexplicitly). Staged files are hosted and public immediately, same as any attachment — there's just no PR to comment on yet.

Once a pull request opens for that branch, staged files land on it one of two ways:

With the App installed (and this workspace linked to the repo — that linking happens automatically the first time the workspace posts a comment or promotes for it), the webhook promotes staged files onto the PR and posts or updates the bot comment the moment the PR opens, reopens, or gets new commits. No CLI involvement at all — this is on by default for fresh installs.
Without the App, the next uploads attach you run against that PR promotes them automatically, or run uploads attach --promote with no files to do it explicitly (--no-promote skips promotion).

Staged files that never make it into a PR are cleaned up on their own — promoted files drop out of the staging area after about 7 days, and anything abandoned is removed after about 30.

Permissions #

The App asks for the minimum it needs:

Issues and Pull requests: read & write — read titles and state, and post the one managed attachments comment. It never touches other comments, PR descriptions, or your code.

If your org installed the App before a permission was added, GitHub holds the upgrade until an org admin approves it. The CLI tells you when that's the case — it prints the exact approval link and falls back to posting via gh in the meantime.

The App also needs to be subscribed to the issues andpull_request webhook events (Settings → your App →Permissions & events → Subscribe to events). Without them the App's ping still shows green — GitHub always sends ping and installation events regardless of subscription — but webhook-driven title cache invalidation and branch-staged attachment auto-promotion silently do nothing. Run uploads github doctor to check: it calls the App API directly and reports any missing subscription.

Without the App #

No install, no problem: uploads attach posts the same managed comment through your local gh CLI, and file pages still resolve titles for public repos. Uninstalling later just returns you to that behavior — hosted files and their URLs are unaffected either way.