feat(github-comment): add self-documenting media hint

[Zach Dunn (zachdunn)]

Summary

• The managed uploads-sh[bot] attachments comment now ends with a short "Add media" hint so anyone reading it can learn how to add to it themselves, without needing prior context on the CLI.
• Change is mirrored byte-for-byte in both comment renderers (apps/api/src/github-comment-render.ts and packages/uploads/src/github.ts) and covered by test/fixtures/github-comment-golden.json / github-comment-golden-cap.json.
• Per the issue, this intentionally ships now that Cross-tenant authorization for the bot-comment endpoint (workspace may target any org's repo) #297's authz baseline (PR fix(api,cli): cross-tenant authorization for the bot-comment endpoint #327) is merged — the comment endpoint is workspace-binding-gated, so it's safe to publish an invitation to post into it.
• Copy is generic (repo + number placeholders only) — never a workspace name or token — and links to https://uploads.sh/docs/github-app for more detail.

Copy added

<sub>Add media: <code>uploads put &lt;file&gt; --pr &lt;N&gt; --comment</code> (or <code>--issue &lt;N&gt;</code>) · <a href="https://uploads.sh/docs/github-app">docs</a></sub>

Renders as:

Add media: uploads put <file> --pr <N> --comment (or --issue <N>) · docs

It's a new final line in the comment footer, after the existing "Maintained by uploads.sh" line — so it doesn't interfere with the 16-image inline cap or the <details> overflow block, which both render above it regardless of comment length.

Before / after (golden fixture body)

Before:

<!-- uploads.sh:attachments -->
### 🖼️ Galleries

#### <a href="https://uploads.sh/g/abc">Design review</a>
<a href="https://uploads.sh/g/abc/i1"><img width="320" alt="screen one" src="https://embed.uploads.sh/g/abc/i1.png"></a>
<sub><a href="https://uploads.sh/g/abc">Open gallery</a></sub>


### 📎 Attachments

- [build.log](https://uploads.sh/f/acme/gh/acme/web/pull/12/build.log)
<a href="https://uploads.sh/f/acme/gh/acme/web/pull/12/hero.png"><img width="400" alt="hero.png" src="https://embed.uploads.sh/f/hero.png"></a>

<sub>Maintained by <a href="https://uploads.sh">uploads.sh</a> — re-uploading a file with the same name updates it everywhere it is embedded.</sub>

After:

<!-- uploads.sh:attachments -->
### 🖼️ Galleries

#### <a href="https://uploads.sh/g/abc">Design review</a>
<a href="https://uploads.sh/g/abc/i1"><img width="320" alt="screen one" src="https://embed.uploads.sh/g/abc/i1.png"></a>
<sub><a href="https://uploads.sh/g/abc">Open gallery</a></sub>


### 📎 Attachments

- [build.log](https://uploads.sh/f/acme/gh/acme/web/pull/12/build.log)
<a href="https://uploads.sh/f/acme/gh/acme/web/pull/12/hero.png"><img width="400" alt="hero.png" src="https://embed.uploads.sh/f/hero.png"></a>

<sub>Maintained by <a href="https://uploads.sh">uploads.sh</a> — re-uploading a file with the same name updates it everywhere it is embedded.</sub>
<sub>Add media: <code>uploads put &lt;file&gt; --pr &lt;N&gt; --comment</code> (or <code>--issue &lt;N&gt;</code>) · <a href="https://uploads.sh/docs/github-app">docs</a></sub>

Test plan

• pnpm --filter @uploads/api test — 812 tests passed
• pnpm --filter @buildinternet/uploads test — 608 tests passed
• pnpm -r typecheck — clean
• Added a patch changeset for @buildinternet/uploads (the CLI-side renderer changed)

Fixes #298

Summary by CodeRabbit

• New Features

  • Added an “Add media” hint to managed GitHub attachment comments.
  • Included command examples for adding media to pull requests and issues.
  • Linked users to the relevant documentation for more guidance.

• Documentation

  • Updated attachment comment guidance to reflect the new self-service media workflow.

• Tests

  • Updated expected GitHub comment outputs to include the new instructions.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cc91669e-92df-49e4-b986-372aed83c043

📥 Commits

Reviewing files that changed from the base of the PR and between 9e06ef6 and a182a09.

📒 Files selected for processing (5)

• .changeset/self-documenting-attachments-comment.md
• apps/api/src/github-comment-render.ts
• packages/uploads/src/github.ts
• test/fixtures/github-comment-golden-cap.json
• test/fixtures/github-comment-golden.json

---

📝 Walkthrough

Walkthrough

Managed GitHub attachment comments now include an “Add media” command with a documentation link. Both renderers and their golden fixtures reflect the updated footer, and a package changeset records the patch release.

Changes

GitHub attachment comment guidance

Layer / File(s)	Summary
Add media footer rendering apps/api/src/github-comment-render.ts, packages/uploads/src/github.ts	Both managed comment renderers add upload command guidance and a documentation link.
Rendered output and release metadata test/fixtures/github-comment-golden*.json, .changeset/self-documenting-attachments-comment.md	Golden outputs include the new footer, and the package changeset records the patch update.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• buildinternet/uploads#290: Modified the same managed GitHub attachment comment rendering path and golden fixtures.

Poem

A bunny found uploads tucked out of sight,
And added a hint in the comment’s moonlight.
“Add media,” it sings, “with one tiny command,”
With docs for the path and a paw-print at hand.
The fixtures all echo, “It renders just right!”

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding a self-documenting media hint to GitHub comments.
Linked Issues check	✅ Passed	The PR adds the generic add-media command to the shared comment body, mirrors it in both renderers, and updates golden fixtures as requested.
Out of Scope Changes check	✅ Passed	The changes stay focused on the comment footer hint, renderer parity, fixtures, and the related changeset, with no unrelated code introduced.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/self-documenting-comment

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 Checkov (3.3.8)

test/fixtures/github-comment-golden-cap.json

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

test/fixtures/github-comment-golden.json

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

---

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	uploads-api	a182a09	Commit Preview URL Branch Preview URL	Jul 21 2026, 11:39 AM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	uploads-auth	a182a09	Commit Preview URL Branch Preview URL	Jul 21 2026, 11:39 AM

[Zach Dunn (zachdunn)]

CodeRabbit (@coderabbitai) review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.