Comment config

Full example #

Commit this at the repo root as .uploads.yml:

comment:
  # "auto" (the default filename-based sizing), "full" (natural width up to
  # the comment column, no fixed attribute), or a pixel number from 160 to
  # 1000. Applies to inline images, pair cells, and video posters alike;
  # "full" and an explicit number override their sizing too, "auto" keeps it.
  imageWidth: auto

  # How many images render inline before the rest collapse to links.
  # Clamped to 1-48. Default: 16.
  maxInlineImages: 16

  # Caption metadata under each image. Each key can be forced on or off.
  # An omitted key follows the workspace default.
  meta:
    path: true
    state: true

  # Whether images link to the file's share page. Overrides the workspace
  # setting.
  linkToFilePage: true

  # Optional short markdown shown under the comment header, before the
  # attachments — repo-specific context, a link to a contributing guide, and
  # so on. Trimmed, capped at 500 characters, rendered as-is: it's
  # repo-owner-authored markdown in the owner's own repo, the same trust
  # level as a PR description. Empty or whitespace-only counts as absent.
  note: ""

A value outside its valid range doesn't fail the whole file: numbers clamp to their bounds, and an unrecognized value for a key drops just that key while every other key still applies.

File location #

The bot and the CLI both check these locations, in order, and use the first one they find:

• .uploads.yml
• .uploads.yaml
• .uploads.json
• .github/uploads.yml
• .github/uploads.yaml
• .github/uploads.json

Only the file on the repo's default branch is read — config committed on a feature branch or a PR doesn't take effect until it lands on default.

Precedence #

Each key resolves independently, in this order:

1. Repo config — a value set in .uploads.yml.
2. Workspace default — set on the workspace's comment settings by a workspace admin.
3. Automatic behavior — the built-in default when neither is set.

A repo can set some keys and leave others out; the ones it leaves out fall through to the workspace default or the automatic behavior on a per-key basis, not as a single all-or-nothing switch.

The note field #

note renders directly under the comment header, before the attachments themselves — a good place for "these are staging shots" or a link to a contributing guide. It's capped at 500 characters.

A note over the cap is dropped whole, not cut short. Truncating mid-sentence could post a note that reads as a different, unintended message, so the render falls back to no note at all rather than a partial one. Trim the note in the file and it posts normally.

Fail-closed behavior #

A missing, unreadable, or unparseable config file never breaks the comment — it just falls back to the workspace defaults, the same as if no file existed. This applies to the whole file: a YAML syntax error anywhere in it means the whole file is ignored for that render, not just the broken part.

The server caches a repo's config for about five minutes, so a commit that changes or removes the file can take up to that long to take effect on the next bot comment. The CLI's gh-fallback path reads the file straight from your local working tree instead, with no cache, so both paths end up honoring the same file.

Preview before committing #

The workspace's comment settings page includes a live preview: pick a repo the workspace is bound to and it renders the resolved comment body using the same code path the bot uses, with a badge on each setting showing whether it came from the repo config, the workspace default, or automatic behavior. Use it to check a change before committing .uploads.yml.