41 lines
2.1 KiB
Markdown
41 lines
2.1 KiB
Markdown
# 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.
|