Skip to content

feat: GitHub integration plugin with bidirectional sync#197

Open
om952 wants to merge 5 commits into
OpenScanAI:masterfrom
om952:issue-15-clean
Open

feat: GitHub integration plugin with bidirectional sync#197
om952 wants to merge 5 commits into
OpenScanAI:masterfrom
om952:issue-15-clean

Conversation

@om952

@om952 om952 commented Jun 18, 2026

Copy link
Copy Markdown
  • Implemented GitHub integration plugin (packages/plugins/github/) with bidirectional issue sync between Paperclip and GitHub
  • Added plugin services for creating, updating, and linking GitHub issues from Paperclip tasks
  • Integrated plugin into the workspace build system with proper TypeScript configuration and exports
  • Added comprehensive README with setup instructions, configuration reference, and usage examples
  • Added unit tests for plugin services and integration tests for the full sync flow
  • Added architecture documentation explaining the plugin's design, data flow, and extension points
  • Fixed workspace integration issues to ensure plugin compiles and tests pass alongside core packages

Verification

# Install dependencies
pnpm install

# Run the plugin tests
pnpm test

# Run full typecheck to ensure no regressions
pnpm -r typecheck

# Build the project
pnpm build

Manual verification steps:

  1. Configure a GitHub personal access token in the plugin settings
  2. Link a Paperclip issue to a GitHub repository
  3. Verify issue title/body syncs to GitHub
  4. Update the issue in GitHub and confirm changes reflect back in Paperclip

Risks

  • Low to medium. The plugin is additive and does not modify core Paperclip logic, but the bidirectional sync introduces potential for race conditions if the same issue is edited concurrently in both systems.
  • The plugin requires a valid GitHub PAT with appropriate repo scopes; misconfigured tokens will fail gracefully with error logging but users need documentation to diagnose.
  • Workspace integration changes could theoretically affect other packages, but the fix was scoped to the plugin's own build configuration.

Closes #15

om952 added 5 commits June 18, 2026 16:09
- Auto-create GitHub issues from Paperclip issues
- Sync status changes bidirectionally (Paperclip ↔ GitHub)
- Mirror comments with user attribution [GitHub @username]
- Auto-create PRs when issues marked done (empty branch)
- Webhook signature verification (HMAC-SHA256)
- Timestamp-based conflict resolution (last-write-wins)
- Rate limit handling with exponential backoff
- State persistence for issue mappings across restarts

Closes OpenScanAI#15
- Add README.md with setup, config, and manual testing instructions
- Add comprehensive test suite (plugin.test.ts) covering:
  - Configuration validation
  - Event handling (issue.created, issue.updated, issue.comment.created)
  - Status mapping and reverse mapping
  - Conflict resolution (timestamp-based)
  - Webhook signature verification
  - State management
  - PR creation (branch naming)
  - Rate limiting
  - Error handling
  - Manifest capabilities
- Add vitest config and test scripts to package.json
- Add plugins/* to pnpm-workspace.yaml
- Fix @paperclipai/plugin-sdk dependency to use workspace:*
- Fix rate limiting test to use future timestamp
- All 30 tests passing
- Typecheck and build passing
- Add integration tests with mocked Octokit (15 tests)
  - GitHub issue CRUD operations
  - Branch and PR creation
  - Webhook signature verification
  - Sync job batch processing
  - Rate limit handling
  - State persistence
  - Error handling (401, 404, network)
- Add ARCHITECTURE.md with:
  - System overview diagram
  - Data flow diagrams (push/pull)
  - State storage schema
  - Conflict resolution logic
  - Security model
  - Rate limiting strategy
  - Component diagram
  - Troubleshooting guide
- All 45 tests passing
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.

Build GitHub Integration Plugin for Paperclip

1 participant