@prskr/paperclip-plugin-forgejo (0.1.0)
Installation
@prskr:registry=npm install @prskr/paperclip-plugin-forgejo@0.1.0"@prskr/paperclip-plugin-forgejo": "0.1.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 - 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. 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.