@prskr/paperclip-plugin-forgejo (0.2.0)
Installation
@prskr:registry=npm install @prskr/paperclip-plugin-forgejo@0.2.0"@prskr/paperclip-plugin-forgejo": "0.2.0"About this package
paperclip-forgejo
Paperclip plugin providing two-way Forgejo issue sync and pull request tools for agents.
1. Forgejo: bot user and tokens
- Create a bot user, e.g.
paperclip-bot, and give it Write access to every repo you want to sync or open PRs in (collaborator or team). - As
paperclip-bot, create an access token (Settings → Applications) with scopesread:user,write:issue,write:repository. This is the plugin's Forgejo token. - Generate a webhook secret:
openssl rand -hex 32.
2. Forgejo: npm publishing token (CI)
- As
prskr, create a token withwrite:package(andread:package). - In
prskr/tools→ Settings → Actions → Secrets, addNPM_TOKENwith that token. (RELEASE_TOKENalready exists forfj release create.) - Release:
git tag -a paperclip-forgejo-v0.1.0 -m "paperclip-forgejo v0.1.0" && git push origin paperclip-forgejo-v0.1.0. The package shows up under prskr → Packages as@prskr/paperclip-plugin-forgejo.
3. Paperclip server: point npm at the Forgejo registry
The Paperclip server installs plugins with npm install as its own user, so the registry config must be visible to that process. Pick one:
~/.npmrcof the server user (in Kubernetes: mount a Secret at that path or setNPM_CONFIG_USERCONFIGto the mounted file):@prskr:registry=https://code.icb4dc0.de/api/packages/prskr/npm/ # only if the package is not public: //code.icb4dc0.de/api/packages/prskr/npm/:_authToken=<read:package token>- Or env on the server process:
npm_config_@prskr:registry=https://code.icb4dc0.de/api/packages/prskr/npm/.
Fallback if this does not work: download the tarball, unpack it on the server and run paperclipai plugin install /abs/path/to/package --local.
4. Install and enable the plugin
paperclipai plugin install @prskr/paperclip-plugin-forgejo --version 0.1.0
paperclipai plugin list # expect prskr.forgejo, enabled
Upgrade later with the same command and a new --version.
5. Configure per company
- In Paperclip, create two secrets in the company:
forgejo-token(step 1.2) andforgejo-webhook-secret(step 1.3). - Settings → Plugins → Forgejo (instance admin), select the company, and fill in:
- Base URL:
https://code.icb4dc0.de - Token:
forgejo-token - Webhook secret:
forgejo-webhook-secret - Paperclip base URL (optional): public
httpsURL of Paperclip, e.g.https://paperclip.home.icb4dc0.de. When set, issues exported to Forgejo get a linked footer (_Synced from Paperclip [ICB-20](…)_) and PRs created withissueIdget aPaperclip: [ICB-20](…)line. - Mappings: e.g.
prskr/tools→ project tools; leave sync comments and export new issues on, inbound statusbacklog.
- Base URL:
- Save. Validation checks the token and repo access. The first reconcile (≤ 10 min) imports the currently open Forgejo issues.
6. Forgejo webhook
For each mapped repo (or once at org/user level): Settings → Webhooks → Add webhook → Forgejo:
- Target URL:
https://paperclip.home.icb4dc0.de/api/plugins/prskr.forgejo/webhooks/forgejo - HTTP method / content type:
POST,application/json - Secret: the webhook secret from step 1.3
- Trigger on: Custom events → Issues and Issue comment
- Hit Test delivery; the plugin answers 2xx and the delivery shows in Paperclip's plugin webhook log.
If Forgejo cannot reach Paperclip, skip this step: sync still works through the 10-minute reconcile, just slower.
7. Let agents use the tools
Agents see the tools as prskr.forgejo:create_pull_request, …:get_pull_request, …:list_pull_requests, …:list_pull_request_comments and …:comment_on_pull_request. Allow them in Paperclip's tool policy for the agents that should use them. Agents still push their branch with their workspace git credentials before calling create_pull_request.
8. Object references (issue and PR chips)
Forgejo issue and pull request URLs in Paperclip issues, comments and documents render as chips with title and live status (Open, Closed, Merged, Draft, Open · CI failing, Open · CI running).
- Enable External objects in Paperclip's experimental instance settings (
enableExternalObjects). Without it the host never calls the plugin. - Upgrading from 0.1.x adds the capabilities
external.objects.detectandexternal.objects.read; approve them when upgrading. - Only URLs on the company's configured Base URL host are claimed:
/{owner}/{repo}/issues/{n}and/{owner}/{repo}/pulls/{n}[/…]. Short references like#42are not linkified. - Status refreshes every 5 minutes for open objects (1 minute while CI runs, 6 hours once closed, never once merged); use the manual refresh on the issue page to force it.
auth_requiredmeans the bot token got 401/403/404 for that object. Forgejo answers 404 for repositories the bot cannot read, so grant the bot read access to them.
9. Verify
- Open an issue in
prskr/tools→ it appears in the mapped project within seconds (webhook) or ≤ 10 minutes (reconcile). - Comment in Paperclip → the comment shows up in Forgejo, authored by
paperclip-bot, prefixed with your name. - Close in Forgejo → the Paperclip issue becomes
done.