paperclip-plugin-github-issues

Paperclip plugin that imports GitHub issues into Paperclip tasks.

Each binding ties one GitHub repo to one Paperclip project inside a specific company. Configure as many bindings as you need across as many companies as you need — the plugin polls every binding on a 10-minute cron and creates / updates the corresponding Paperclip tasks.

Features

• Multi-binding: N × (Paperclip company → GitHub repo) per plugin install.
• Idempotent import: (bindingId, ghIssueNumber) mapping prevents duplicates.
• Incremental polling using GitHub's since filter.
• Status mirroring: GitHub closed → Paperclip done; reopened → configured default. Manual edits in Paperclip survive intermediate syncs.
• In-page secret picker — operators never type secret UUIDs.
• Activity log entries per sync run.

Install

paperclipai plugin install @wil0x91/paperclip-plugin-github-issues

The plugin shows up under Settings → Plugins → GitHub Issues Sync.

Configure a binding

1. Settings → Plugins → GitHub Issues Sync.
2. Pick a company from the dropdown at the top.
3. Click + Add binding.
4. Pick (or create inline) a Paperclip secret holding a GitHub PAT (scope repo for private, public_repo for public-only).
5. Type GitHub owner and repo.
6. Pick the target Paperclip project.
7. Choose default status / label prefix.
8. Save binding. Allow ~30s for secret authorization to refresh, then click Sync on the new row.

You can repeat for multiple repos in the same company, or switch companies in the dropdown and add bindings there too.

Configuration shape

The plugin stores all bindings inside its configJson:

{
  "defaultPriority": "medium",
  "bindings": [
    {
      "id": "<companyId>:<owner>/<repo>",
      "companyId": "<uuid>",
      "projectId": "<uuid>",
      "owner": "acme",
      "repo": "widgets",
      "tokenRef": "<secret-uuid>",
      "defaultStatus": "todo",
      "labelPrefix": "github:",
      "createdAt": "2026-04-26T19:00:00Z"
    }
  ]
}

Operators normally never edit this directly — the plugin's settings page does it through POST /api/plugins/:id/config and the GitHub PAT is stored as a Paperclip secret (referenced by UUID, never inlined).

Capabilities declared

• issues.read, issues.create, issues.update
• plugin.state.read, plugin.state.write
• jobs.schedule
• http.outbound
• secrets.read-ref
• activity.log.write
• companies.read
• projects.read
• instance.settings.register

The plugin only reads / writes issues in companies and projects you bind explicitly. The GitHub PAT never leaves the Paperclip secret store except in process memory during the sync call.

Behaviour

• Cron: */10 * * * * (every 10 minutes), with a manual Sync now action per binding or for all bindings.
• Issues are matched on (bindingId, gh.number) and persisted in plugin state so re-runs are no-ops.
• New issues are imported with the configured defaultStatus. Closed GitHub issues flip the Paperclip task to done once. Reopened GitHub issues flip it back to defaultStatus once. In between, Paperclip status edits made by humans / agents are preserved.
• Imported description includes a link to the source GitHub issue, the author, the GitHub state, and a list of GitHub labels with a configurable prefix.

Limitations

• One-way sync (GitHub → Paperclip). Paperclip status changes do not echo back to GitHub.
• No webhook support yet — relies on the 10-minute cron.
• No comment sync.
• No assignee mapping.

Development

npm install
npm run typecheck
npm run test
npm run build
paperclipai plugin install --local "$(pwd)"

When bumping the version, run npm version <patch|minor|major> — the included version script keeps the manifest bundle filename in sync with the package version (Paperclip's host caches plugin manifests by absolute import path; a fresh filename per release avoids stale loads).

License

MIT — see LICENSE.