@prskr/paperclip-plugin-forgejo (0.1.1)

Published 2026-10-02 14:44:35 +00:00 by prskr in prskr/tools

Installation

@prskr:registry=
npm install @prskr/paperclip-plugin-forgejo@0.1.1
"@prskr/paperclip-plugin-forgejo": "0.1.1"

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
    • 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. 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-02 14:44:35 +00:00
1
MIT
236 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