@prskr/paperclip-plugin-forgejo (0.3.0)

Published 2026-10-04 09:50:27 +00:00 by prskr in prskr/tools

Installation

@prskr:registry=
npm install @prskr/paperclip-plugin-forgejo@0.3.0
"@prskr/paperclip-plugin-forgejo": "0.3.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; for review delegation (section 10) also Pull request (review request events)
  • 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, …:comment_on_pull_request and …:submit_pull_request_review (verdict COMMENT or REQUEST_CHANGES with optional inline comments; APPROVE is rejected on purpose). 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.

10. Delegate pull request reviews to an agent

Request a review from the bot user on a pull request in a mapped repo and a Paperclip agent reviews it.

  1. In Paperclip, create a label (e.g. forgejo-review). Tasks with this label are never synced to Forgejo.
  2. Copy the agent ID of the reviewer and the label ID. The settings form has no pickers, so paste the ids into Settings → Plugins → Forgejo → Pull request reviews, tick Enable review delegation and save.
  3. Upgrading adds the capability issues.wakeup; approve it. Tick Pull request events on the Forgejo webhook (section 6).
  4. In Forgejo, request a review from the bot. The plugin creates one task in the mapped project for the agent (with the label), wakes the agent and comments on the PR with a link to the task. The agent delivers the review with submit_pull_request_review and sets the task done.
  5. When the task is done or cancelled, the plugin removes the bot from the requested reviewers, so the PR does not trigger again. Requesting a review again creates a new task. If Forgejo is unreachable at that moment, the next reconcile run retries the removal.

Only one review task is open per PR. A missed webhook is caught by the reconcile job (≤ 10 min). Closing the PR does not cancel the task.

The X-Forgejo-Event header of review requests has not been confirmed on the deployed Forgejo yet; the plugin accepts pull_request and pull_request_review_request and reconcile is the fallback.

Keywords

paperclip paperclip-plugin forgejo
Details
npm
2026-10-04 09:50:27 +00:00
2
MIT
latest
247 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