Skip to content

fix(sync): degrade instead of block without board access - #226

Open
stfl wants to merge 1 commit into
alvarosanchez:mainfrom
stfl:upstream/degrade-without-board-access
Open

stfl wants to merge 1 commit into
alvarosanchez:mainfrom
stfl:upstream/degrade-without-board-access

Conversation

@stfl

@stfl stfl commented Oct 17, 2026

Copy link
Copy Markdown

Closes #225.

Summary

What breaks today. On a Paperclip deployment that reports deploymentMode: "authenticated", performSync refuses to run while any touched company lacks Paperclip board access and returns missing_board_access. The settings page, dashboard widget and toolbar lock the sync button for the same reason. This also blocks setups that only have link_github_item links and no repository mapping.

Scenario. An operator wants one thing from GitHub Sync: wake the assignee when review feedback or red CI lands on a linked PR. To get it, they must hand the plugin worker a board token, which carries all of a board user's rights. Without the token, nothing syncs.

What changes. Most of sync already has a plugin SDK path. Every fetchPaperclipApi call site is guarded by if (paperclipApiBaseUrl), and #225 lists the fallbacks. For a company without board access, performSync now passes no worker Paperclip API URL, so that company syncs through ctx.issues.* only:

 performSync
   probe /api/health
-  authenticated && company lacks board access → fail: missing_board_access
+  authenticated && company lacks board access
+    paperclipApiBaseUrl = undefined for that company   # SDK paths only
+    syncState.warnings += "needs board access: create labels, assign users, tool-access check"
   for each mapping / link
     status, agent assignee, execution policy, description, comments, wakeups
-      REST with board token
+      REST with board token, or ctx.issues.* without it
  • A GitHub label with no matching Paperclip label stays unmapped instead of failing the issue.
  • The UI no longer locks sync. Settings shows board access as Recommended and renders the warning.
  • An already persisted missing_board_access error state still normalizes, and it is shown and cleared as idle.
  • Companies that have board access behave as before.
  • The README documents a minimal PR follow-through setup: a read-only fine-grained GitHub token and no board token.

Evidence

  • Before: worker blocks sync when the Paperclip deployment is authenticated and board access is missing passes; sync returns missing_board_access.
    After: replaced by three tests that drive an authenticated deployment without board access:
    • worker syncs a mapped repository through the SDK when an authenticated deployment has no board access: the status transition, comment and wake go through the SDK, and no Paperclip REST call is made besides /api/health.
    • scheduled sync follows a link-only third-party pull request through the SDK when an authenticated deployment has no board access
    • worker leaves GitHub labels unmapped without failing imports or status sync when an authenticated deployment has no board access
  • pnpm typecheck, pnpm test, and pnpm test:e2e (real Paperclip host, plugin install and UI mount) pass on the branch.

Merge Danger

Door: two-way

Reverting restores the block. Nothing is migrated, and the missing_board_access type stays.

Blast Radius: authenticated-without-board-access

Only companies on authenticated deployments without board access change: they sync where they used to be refused. On those companies, label creation, user assignment and the tool-access check stay off, and the sync state warns about it.

…ez#225)

On an authenticated Paperclip deployment, sync refused to run until every
touched company had connected Paperclip board access (missing_board_access).
Most of what sync does already has a plugin SDK path, so the block forced
operators to grant a board user's rights just for PR follow-through.

performSync now gives companies without board access no worker Paperclip
API URL, so status, assignee, execution-policy and description updates,
comments, and wakeups go through ctx.issues.* and no Paperclip REST call
is made for them (only the /api/health probe). Unresolved GitHub labels
stay unmapped for those companies instead of failing the issue. The sync
state records a non-fatal warning naming what needs board access:
creating missing labels, assigning issues to users, and the agent
tool-access check. Companies with board access behave as before.

The settings page, dashboard widget and toolbar no longer lock sync on
missing board access; settings shows it as "Recommended" and renders the
warning. The missing_board_access type stays so error states persisted
by earlier builds still normalize; they are displayed and cleared as idle.

README documents a minimal PR follow-through setup: a read-only
fine-grained GitHub token and no board token.

Refs alvarosanchez#225
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Sync should degrade instead of block when board access is missing on authenticated deployments

1 participant