External Objects

Issues constantly reference work that lives somewhere else — a GitHub pull request, a ticket in another tracker, a deployment. Normally those are dead links: to know whether that PR merged, you leave Paperclip and go look.

With External Objects on, Paperclip detects external URLs anywhere in an issue — title, description, comments, documents — and renders them as live status pills instead of plain links. A referenced GitHub pull request shows up as Open, Draft, Merged, or Closed right where it's mentioned, plus in a rollup panel on the issue.

External object status on an issue

Turn it on

  1. Go to Settings → Instance settings → Experimental.
  2. Turn on Enable External Objects — "Detect external URLs in issues and show resolved status for pull requests, tickets, and other referenced work objects."

Using it

There's nothing to configure per issue — just paste URLs where you'd naturally write them:

  • Detection. Whenever an issue, comment, or document is created or updated, Paperclip extracts its URLs. GitHub pull-request and issue URLs (github.com/{owner}/{repo}/pull/{n} or /issues/{n}) are recognized as first-class work objects out of the box; anything else becomes a generic link object. Plugins can register additional detectors for other systems.
  • Status pills. Recognized references render inline as a pill with a provider icon, the object (e.g. owner/repo#123), and its state — with a distinct look for merged PRs, an ×N counter when the same object is referenced several times, and a dashed border when the status is stale, unreachable, or needs authentication. A newly detected object starts as "Not yet refreshed" until it's resolved.
  • The External objects panel. The issue's Related Work area gains an External objects section — "Remote work referenced from this issue — pull requests, deployments, tickets in other systems, and more." — listing every detected object with its status and where it was mentioned, sorted severity-first.
  • Lists and sidebar. Issue list rows get a compact status badge and the list toolbar gains an external-object status filter; project rows in the sidebar roll up the dominant status.

GitHub access

Public repositories resolve without setup. For private repos (and friendlier rate limits), add a company secret named GITHUB_TOKEN, GH_TOKEN, or PAPERCLIP_GITHUB_TOKEN. Without access, private objects show "Requires auth".

When it's off

Hidden and inert: detection stops, pills fall back to plain links, the panel and filters disappear. Already-detected objects are kept and reappear if you re-enable.

Caveats

  • GitHub is the only built-in resolver at this release, and only github.com URLs in the exact PR/issue path shape — GitHub Enterprise hosts and other trackers need a plugin that provides object detection.
  • Resolved statuses have a short TTL (about five minutes) and there's no background poller yet at this release — statuses refresh lazily, and agents can force a refresh through the API. Expect pills to read stale or "Not yet refreshed" between resolutions.

Where to go next