ake/paperclip-forgejo-issue-plugin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
paperclip-forgejo-issue-plugin/README.md

2.1 KiB
Raw Permalink Blame History

Forgejo Issue Sync Plugin

Paperclip plugin for one-way Paperclip issue -> Forgejo issue creation while enforcing the v1 attachment policy:

  • selected Paperclip issues are detected inside the plugin worker
  • scheduled reconciliation stays in plugin jobs
  • mappings, dedupe, and review state stay in the plugin database/state
  • attachment handling is metadata-only
  • no managed agents or managed skills are declared in v1

Layout

  • src/manifest.ts: manifest, capabilities, jobs, webhook declaration, instance config schema
  • src/worker.ts: plugin bootstrap, health, config validation, data/action registration
  • src/paperclip-issue-sync.ts: issue selection, payload shaping, and outbound sync flow
  • src/forgejo-client.ts: outbound Forgejo API client
  • src/reconciliation.ts: scheduled reconciliation job and instance-level last-run state
  • src/persistence.ts: namespace-local persistence helpers for mappings, reviews, and run snapshots
  • src/attachment-policy.ts: metadata-only attachment policy and synced markdown formatter
  • migrations/001_initial.sql: plugin-owned tables for mappings, dedupe, review queue, and reconciliation history

Attachment Policy

This plugin deliberately does not fetch attachment bytes and does not add any path that calls /api/attachments/{id}/content.

Instead it:

  • preserves attachment metadata only
  • appends Attachments are not synced. See the source Paperclip issue. to generated sync content
  • stores a machine-readable review reason code when the issue/comment text suggests the attachment is required for context
  • queues those payloads in review_queue for later human-routing work

Follow-Up Needed

The plugin emits attachments_context_required as a durable review signal, but the human-review destination is still a follow-up decision:

  • create Paperclip-visible review issues/comments
  • expose a plugin UI or scoped API route for triage
  • route review-required payloads into an existing operator workflow

That routing is intentionally left out of this v1 scaffold so the sync runtime stays inside plugin jobs/webhooks/state as requested.