Paperclip Plugin Github Issues

paperclip-plugin-github-issues

Bidirectional GitHub Issues sync for [Paperclip](https://paperclip.ing).

This is the first external Paperclip plugin built as a standalone npm package, created to validate the plugin developer experience.

What it does

• Selective linking - pick individual GitHub issues to sync with Paperclip issues
• Bidirectional status sync - close a GitHub issue, the Paperclip issue updates (and vice versa)
• Comment bridging - optionally mirror comments between systems
• Agent tools - Paperclip agents can search GitHub issues and create links during runs
• Webhook support - receives GitHub webhook events for real-time sync
• Periodic polling - catches changes missed by webhooks

Requirements

• Paperclip instance with plugin runtime enabled (requires PR #821 to be merged)
• GitHub personal access token with repo scope (or fine-grained token with Issues read/write)

Installation

# From the Paperclip CLI
pnpm paperclipai plugin install paperclip-plugin-github-issues

Or for development:

git clone https://github.com/mvanhorn/paperclip-plugin-github-issues.git
cd paperclip-plugin-github-issues
npm install
npm run build

Configuration

After installation, configure the plugin in Paperclip Settings > GitHub Issues Sync:

1. Create a secret - go to Paperclip Settings → Secrets, click "Add Secret", paste your GitHub PAT as the value, and copy the generated UUID
2. GitHub Token - paste the secret UUID from step 1 into the "GitHub Token" field
3. Default Repository - optional owner/repo for agent tool searches
4. Sync Comments - enable to mirror comments between systems
5. Sync Direction - bidirectional, github-to-paperclip, or paperclip-to-github

GitHub Webhook Setup

For real-time sync, configure a webhook on your GitHub repository:

1. Go to your GitHub repo > Settings > Webhooks > Add webhook
2. Payload URL: `https://your-paperclip-instance/api/plugins/papercl