@prskr/paperclip-plugin-forgejo (0.2.0)

Published 2026-10-03 14:16:14 +00:00 by prskr in prskr/tools

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

  1. 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).
  2. As paperclip-bot, create an access token (Settings → Applications) with scopes read:user, write:issue, write:repository. This is the plugin's Forgejo token.
  3. Generate a webhook secret: openssl rand -hex 32.

2. Forgejo: npm publishing token (CI)

  1. As prskr, create a token with write:package (and read:package).
  2. In prskr/tools → Settings → Actions → Secrets, add NPM_TOKEN with that token. (RELEASE_TOKEN already exists for fj release create.)
  3. 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:

  • ~/.npmrc of the server user (in Kubernetes: mount a Secret at that path or set NPM_CONFIG_USERCONFIG to 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

  1. In Paperclip, create two secrets in the company: forgejo-token (step 1.2) and forgejo-webhook-secret (step 1.3).
  2. 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 https URL 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 with issueId get a Paperclip: [ICB-20](…) line.
    • Mappings: e.g. prskr/tools → project tools; leave sync comments and export new issues on, inbound status backlog.
  3. 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.detect and external.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 #42 are 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_required means 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.

Keywords

paperclip paperclip-plugin forgejo
Details
npm
2026-10-03 14:16:14 +00:00
1
MIT
244 KiB
Assets (1)
Versions (4) View all
0.3.0 2026-10-04
0.2.0 2026-10-03
0.1.1 2026-10-02
0.1.0 2026-10-02