DottaandPaperclip
ed2c22ea8c
## Thinking Path > - Paperclip manages agent work and the tools each agent can use. > - GitHub bots need their own App identity and restricted repository access. > - Manual App configuration and repeated setup gates make that connection hard to finish. > - GitHub can create an App from a manifest, but people must approve creation and repository access. > - Each Paperclip stack should own configuration, credentials, signature verification, and task admission. > - This change uses Cloud as an encrypted callback and event gateway, then completes setup in the stack. > - GitHub review bots have their own experimental setting. Chat connector opt-in does not control them. ## Linked Issues or Issue Description **What existing behavior does this improve?** Dedicated GitHub App setup, bot settings, and task-scoped GitHub replies. **Current behavior** Users must configure an App, copy credentials, repeat repository selection, and complete manual verification gates. Review settings are hard to scan. Mentions in descriptions can be missed, and automatic completion text can produce an extra GitHub comment. **Proposed behavior** Choose an agent and connect GitHub under a personal account or organization. GitHub asks for creation and installation consent. Paperclip resumes the same draft, stores secrets locally, imports access, verifies delivery, and opens Settings. Each accepted request has one editable App-owned comment for progress and results. Review assessments produce deterministic checks for the reviewed commit. **Breaking changes** GitHub bots require their own default-off experimental opt-in. The setup-method and delegated-agent screens are removed. Per-person automatic-run flags remain readable but are replaced by author filters. Existing connections, direct webhooks, saved restrictions, and manual existing-App recovery remain supported. Companion gateway: https://github.com/paperclipai/paperclip-cloud/pull/688 (merged). The roadmap and related PRs were checked; no duplicate dedicated-App wizard was found. ## What Changed - Add an independent **GitHub review bots** setting across the catalog, routes, identity admission, and task controls. Existing bots continue running when the UI setting is off. - Replace setup with Choose agent and Connect GitHub. Support personal and organization owners, inline low-trust conversion, saved drafts, known organization suggestions, automatic completion, and same-App recovery. - Keep manifests, OAuth PKCE, credential exchange, vault storage, installation verification, and original webhook-signature validation in the stack. Use the Cloud sealed gateway for public callbacks and outbound local delivery. - Add resumable owner metadata in migration 0323. Retry a failed registration renewal through the same durable replacement rather than creating another App route. - Support authorized mentions in issue and PR bodies, comments, inline comments, and review summaries. Preserve attachments, edited-source identity, duplicate protection, and lifecycle invalidation. Filter requests explicitly addressed to another connected bot. - Give agents task-scoped review, comment, and update tools. Update one working comment through progress and final output. Close coalesced requests and recover delayed acknowledgements, including deleted earlier working comments. Preserve automatic replies for legacy connections without saved review configuration. Preserve partial publication evidence and quarantine uncertain automatic fallbacks without blocking Board messages or questions. - Reorganize Settings and Access with rich slash-skill instructions, numeric passing scores, clear automation controls, formal-review tooltips, member and contributor sections, and verified App branding links. Preserve invalid score drafts and automation choices across tabs. - Paginate repositories in 20-row batches with search and a true connection-wide toggle. Batch verification at GitHub's 500-ID token limit. Keep saved repository overrides while hiding their editor. - Give each review a detail URL that remains usable beyond the newest 100 records. Synchronize the manager OpenAPI contracts and add recovery, authorization, UI, and browser regressions. - Reconcile the current master branch and retain its agent avatar, feature catalog, and extracted heartbeat preparation code. Preserve a saved test-drive port and recover from an occupied high port. ## Verification - Focused UI, independent experimental-setting, and CLI tests: 199 passed. - `pnpm -r typecheck`, `pnpm build`, and `pnpm check:token-gates` passed. The broad local Vitest attempt was interrupted after resource timeouts and stale expectations; the affected regressions passed focused reruns. The latest-head full CI matrix passed, including all browser shards, server/chat suites, builds, typechecking, canary packaging, and Docker context integrity. A Docker Hub 429 required a CI retry; it passed without changing the code. - Final review repairs: 127 attachment/event tests and server typecheck passed. All 13 final integration regressions passed under the normal CI timeout, covering legacy reply compatibility, deleted coalesced comments, inline-only review completion, progress edits, and native final recovery. Restart-safe description/review attachments passed the attachment suite. - Final regressions: four reply/lifecycle tests, both native GitHub wait tests, 171 feature-gate/reply-contract tests, the routed review preview, and five scheduler/reply regressions passed. The final fixture repair also passed all six setup-continuation cases and all three complete chat-test shards in CI, covering terminal receipts and retries under the normal CI timeout. One loaded-host receipt run exceeded its local timeout; the exact case passed in an isolated rerun and the complete CI shard. - GitHub integration tests cover personal and organization setup, retry recovery, edited mentions, attachment provenance, coalesced requests, delayed acknowledgements, partial review writes, old review URLs, and company boundaries. - Browser qualification: both GitHub journeys, all five provider setup/management journeys, and the GitHub uncertain-send recovery journey passed. GitHub setup, reconnect, and task replies run with chat disabled; chat enabled alone cannot expose GitHub bots. The disposable qualification database was removed after testing. - Earlier live qualification verified App-owned issue replies, native slash-skill invocation, progress comment edits, and a 5/5 PR review with a passing current-head check in the dedicated permissions-smoke repository. These live checks did not use personal credentials as bot execution authority. ## Risks - Deploy the merged Cloud gateway protocol before the stack update. Each callback and encrypted event must retain the original instance and tenant binding. - Migration 0323 uses idempotent column additions for test installations that already applied the earlier draft migration number. - A verified connection does not prove runtime isolation or a completed review. Runtime checks remain separate. - Required merge checks must be configured in GitHub. A passing numeric score does not formally approve a PR; approval and request-changes tools remain opt-in. - Existing-App credentials cannot silently renew an uncertain manifest exchange. Recovery preserves the existing App, draft, connection, and agent. - Repository changes save immediately. Global toggles affect all currently available repositories, including unloaded rows, without granting new installation access. - A failed or uncertain tool write suppresses automatic fallback text; the governed outbox retains its evidence. Deleted or replaced response comments are not recreated through a personal credential fallback. - GitHub logo upload remains an optional human action in GitHub App settings. Runtime provisioning, delegated setup, screenshot publication, and production push delivery remain deferred. ## Model Used OpenAI Codex, based on GPT-6, with tool use and code execution. The exact runtime model identifier and context size are not exposed in this session. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub references) - [x] My branch name describes the change and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass (focused suites; complete test matrix is checked in CI) - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
13 KiB
GitHub chat and review bots
A GitHub bot belongs to one Paperclip agent. GitHub issues, pull requests, and review threads enter ordinary Paperclip tasks; the agent's runs, permissions, budget, and activity remain visible there. The Reviews page is a projection of assessments attached to those tasks, not a separate execution system.
For a step-by-step explanation of mentions, automatic reviews, scores, and required GitHub checks, read Understanding GitHub PR review bots.
Set up a bot
Enable GitHub review bots in instance Experimental settings, then open the GitHub Code Review Bot connector. This default-off setting is independent of Chat connectors. Hiding either feature does not pause existing provider delivery.
- Choose the bot agent. Prefer a low-trust review agent with an isolated sandbox and a scoped task boundary. Standard-trust agents show a warning with Change to a low trust agent. This explicitly saves the low-trust preset; it does not configure a sandbox or task boundary.
- Choose My account or An organization. Enter the organization when needed and review the App name suggested from your agent. Click Continue to GitHub. Paperclip fills permissions, events, and callbacks.
- Confirm creation on GitHub, then select repositories and approve installation. Paperclip stores the credentials securely and imports the initial selection, including an explicit All repositories choice. Organization policies may require administrator approval; resume the same draft when it is granted.
- Paperclip reuses your verified GitHub identity when available. Otherwise, authorize the dedicated App and confirm the observed account once. Bot work uses installation credentials, never your personal GitHub token.
- Connection verification and completion happen automatically. Paperclip opens the bot's Settings with a connected confirmation modal showing the actual App identity, enabled repository count, and a copyable optional review mention. Dismiss it with Done, the close button, or Escape to stay in Settings. Runtime and isolation readiness remain separate prerequisites.
Installation may return before GitHub's separately delivered signed webhook ping. Paperclip keeps the same draft and credentials, shows a waiting state, and continues automatically after authenticating the ping. Refreshing or resuming that draft must not create another App or bypass signature verification.
New connections default to authorized mentions, advisory reviews, linked-member access, guests off, and enabled bot GitHub tools. Existing instructions, explicit behavior, and narrower saved repository restrictions remain intact. Later repository additions require enablement in Access. Advanced review rules and prompts live in Settings.
The App belongs to the selected account or organization and uses its own bot
identity. The editable App name determines GitHub's slug and @mention; there
is no separate editable bot username. Paperclip shows and copies the verified
mention in the connected bot's header. Type @app-slug, without the [bot]
suffix shown on GitHub's API author records.
GitHub App name and logo is optional on the connected page and in Settings. Download the agent's avatar as a PNG, then follow the link to this App's GitHub settings to upload it under Display information. GitHub's manifest parameters do not include an avatar; the logo upload remains a GitHub settings action. After renaming the App on GitHub, use the existing reconnect this App flow to refresh its verified identity using its stored credentials. Legacy manual connections without recorded ownership link to the App settings list instead of assuming an owner.
Local instances receive public callbacks and signed events through an enrolled Paperclip Cloud connector, using outbound requests instead of a public tunnel. Your localhost instance does not need HTTPS or a tunnel for this flow. Setup asks you to connect Cloud only if the instance is not already enrolled. The Cloud gateway capability must be deployed before localhost onboarding. Direct public-HTTPS webhook connections and manual existing-App credential recovery remain supported. An expired, unconsumed Cloud handoff can be renewed in the same draft after the configuring manager confirms that no App was created on GitHub. Claimed, consumed, and uncertain exchanges still require existing-App recovery. Setup tasks and copied prompts are not part of this wizard. Normal agent API keys cannot call its board-only management APIs.
GitHub review bots use the existing agent runtime; this connector does not add
provider software to the Cloud server image. Codex with managed MCP tools and
the native Runner Codex backend do not require a server-side remote provider
pack. Remote native ACPX (including Claude) and OpenCode currently require an
operator-supplied, build-owned provider pack configured through
PAPERCLIP_RUNNER_REMOTE_PROVIDER_PACK_PATH; the standard Cloud server image
does not supply one. A pack installed in the sandbox alone does not satisfy
that existing runtime requirement. Treat that provider setup as a separate
Runner prerequisite, not an automatic connector installation step.
Connection setup reports tool/runtime support and isolation separately; an actual test task is still required to prove that the chosen provider can execute in the selected environment.
Manage a connected bot
- Settings: edit instructions, choose when the bot runs, and set review output. Event-specific instructions, filters, and formal approvals are available in disclosures. Repository-override editing is temporarily hidden in the UI; existing overrides and the configuration API remain supported. Changing defaults preserves saved overrides.
- Access: choose enabled repositories and allowed people. Repository switches save immediately. Other changes use Save changes. A linked account alone does not grant selected-member access. Add external contributor still requires a sponsor and restricted permissions. Bot tools are enabled during setup; a previously disabled connection exposes an explicit repair action without silently changing its permissions.
- Reviews: see every assessment as one row, newest first. Open a row for its summary, commit, findings, coverage, and task/run/publication links. Each review has its own URL. A previous passing result does not stand in for a pending review of a newer commit.
- Conversations: follow the task title to Paperclip or the repository/thread label to GitHub.
Settings and Access share unsaved edits while you switch connection tabs. Save before reloading or leaving the connection. No permissions change merely by opening a tab.
The repository list loads 20 rows at a time as you scroll. Search covers the entire connection. Disable all and Enable all also apply to the entire connection, including unloaded rows and repositories outside the search results. Enabling all includes only repositories still available in the App installation; it cannot restore revoked GitHub access. These changes save immediately.
Who can start work
Linked members may be allowed together or selected individually. Teammates connect and confirm their own accounts; an administrator cannot assert someone else's identity by entering a username.
To admit an unlinked GitHub person, explicitly add their verified GitHub account, choose an active sponsor, and use the restricted guest profile. Guests receive no company membership or sponsor credentials. Authority is checked again before tool calls and publication, so revocation also affects queued or ongoing work.
Choose automatic events and author filters in Settings to control which
authored PRs and issues start work. Authorized mentions remain available with
automatic events off and bypass automatic author filters. The shared external-
contributor switch controls whether sponsored guests may start automatic work;
there are no per-person automatic-run switches in Access. Legacy saved
automaticReviews values are ignored.
Automatic tasks use the configured responsible Paperclip member for accountability, not that member's personal GitHub credentials. A member named Board in a local test drive is still the responsible user, not a separate GitHub actor. The PR author and webhook sender are recorded independently. Follow-ups preserve task ownership while checking the current requester's authority.
Mentions and pushes
Use mentions only for reviews initiated by an authorized @your-bot request.
Choose automatic reviews and enable updated commits to review new pushes.
Opened, reopened, ready-for-review, and updated-commit events are independently
configurable. Draft and bot-authored PRs are excluded by default. Settings can
be overridden per enabled repository.
New GitHub issues is a separate opt-in automatic event, disabled on existing
and new connections until selected. It uses the same repository, author,
linked-member or sponsored-guest, responsible-member, and label restrictions as
automatic PR events; PR branch filters do not apply to issues. Its instructions
start an ordinary issue task with task-bound comment tools, without a PR
assessment or commit check. Older manually configured Apps must subscribe to
the issues webhook event before enabling this setting.
An authorized mention can bypass automatic author/branch/label scheduling filters. It cannot bypass repository restrictions, excluded files, or access permissions. Ordinary discussion does not change a review score. Repeat review mentions and pushes continue the existing task; inline replies return to the task owning that thread.
Event prompts supplement the agent's instructions. Repository content and PR prose are untrusted input and cannot change tool authority or publication policy. The execution records the configuration revision and event context used.
Assessments, checks, and formal reviews
The agent reads through task-bound bot tools, explicitly begins an assessment, and submits the reviewed commit, findings, rationale, and coverage. Paperclip validates the result and computes the Paperclip Review check. The default threshold is 5/5; choose 1–5 or report-only as needed.
| Score | Assessment rubric |
|---|---|
| 0 | No usable assessment; explain what prevented evaluation. |
| 1 | Critical defects make the change unsafe to ship. |
| 2 | Major defects require substantial correction. |
| 3 | Meaningful defects require correction before merging. |
| 4 | Minor concerns remain; explain impact and remaining risk. |
| 5 | No actionable defects found within the stated coverage and limitations. |
Incomplete coverage cannot pass. Filtering which findings become inline comments does not remove them from the assessment. A new head requires a new assessment; old runs cannot publish over the latest head. One current summary is updated in place, with history and task/run links retained. Stable finding keys prevent duplicate inline comments on repeated reviews.
The check's Details link opens its Paperclip task on the current instance hostname, or the connector's Reviews page when no task has been created yet.
Formal APPROVE and REQUEST_CHANGES are separate governed tools, each off by default. Enabling either does not automatically perform it. A score of 5/5 alone never approves a PR. The agent must finish an assessment and explicitly choose the allowed action. Allow approvals permits a formal ready-to-merge decision; Allow request changes permits a formal change request, which can prevent merging when the repository's review rules require resolution. Keeping these off leaves scores, comments, and checks available while making formal review decisions opt-in. The controls include contextual tooltips.
To enforce the rating at merge time, configure GitHub branch protection or a ruleset to require Paperclip Review, selecting this bot App as the source where supported. Paperclip does not change repository rules. GitHub account and repository plan restrictions may limit required-check enforcement. If automatic execution is disallowed, a gated head requests an authorized manual review.
Hosted ingress
Dedicated Apps use Cloud as a sealed transport gateway. Cloud routes opaque callbacks and signed webhook bytes to the enrolled instance; the instance exchanges GitHub codes, stores credentials, verifies webhook signatures, and applies repository and actor policy. Local instances poll outbound and do not need an inbound tunnel.
Legacy direct-webhook Cloud deployments proxy only POST /api/chat-webhooks/:publicId/github and the narrow
GET /api/chat-github/manifest/callback registration callback without browser
login. The instance verifies the untouched webhook body and GitHub signature;
registration uses expiring, single-use user/company/origin-bound state.
Installation return, configuration, and identity confirmation remain
authenticated. URLs use the trusted current vanity hostname, with explicit
webhook-ingress overrides preserved.
Existing chat connections do not gain review execution or broader permissions until explicitly configured. GitHub.com and UI-managed settings are the initial scope; cross-repository indexing and auto-fix are not included.