GitHub App

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):

>> 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:

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 & events #

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.

Permissions alone aren't enough — the App also has to besubscribed to webhook events (Settings → your App →Permissions & events → Subscribe to events):

• Required — issues and pull_request. Without these 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.
• Recommended — issue_comment. Optional; the App works fully without it. It's what lets the managed attachments comment self-heal if it's ever deleted or edited out from under the bot, instead of waiting for the next PR push to re-render it.

Run uploads github doctor to check: it calls the App API directly and reports any missing required subscription, so a silent misconfiguration doesn't sit there unnoticed.

Repo bindings #

One repo maps to at most one workspace's managed comment — first claim wins. The binding is normally created implicitly the first time a workspace successfully comments, attaches, or promotes against a repo; you can also inspect or claim it explicitly:

Claiming an already-bound repo never steals it from whoever claimed it first — the command just reports the current owner. uploads github unlink releases a binding your own workspace owns; it fails if another workspace owns it, same as claiming does. If a binding is stuck or abandoned, an operator can reassign or remove it from the admin panel without going through the owning workspace at all.

Other workspaces can't post to your repo. If your repo is bound to your workspace, a different workspace's comment/attach call against it is declined outright (not_authorized) — it does not fall back to posting under that person's own gh credentials, so there's no way for someone else's workspace to deface or duplicate the bot comment on your repo. The one exception runs the other way: the shared, communal default workspace can post to repos it already owns, but it can never claim a fresh, unbound repo — that keeps the widest-shared workspace from silently annexing other people's repos.

Self-healing comments #

With the issue_comment event subscribed (seePermissions & events above), deleting the manageduploads-sh[bot] comment — or editing out its hidden marker — doesn't leave a PR or issue without one for long. The next issue_comment webhook delivery notices it's gone or mangled and recreates it automatically, with the same attachment list it would have shown. No CLI call needed to trigger it. If an agent notices the comment briefly missing, that's expected — it isn't a signal to panic-repost with a freshuploads comment call.

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.