Aaron Reynoza
Repositories
5
 Projects Packages
2
 Public activity Starred repositories

@aaron/paperclip-alertmanager-plugin (0.2.0-live.20260702.15)

Published 2026-07-02 00:29:04 +00:00 by aaron in aaron/paperclip-alertmanager-plugin

Installation

@aaron:registry=
npm install @aaron/paperclip-alertmanager-plugin@0.2.0-live.20260702.15
"@aaron/paperclip-alertmanager-plugin": "0.2.0-live.20260702.15"

About this package

@aaron/paperclip-alertmanager-plugin

Paperclip native plugin for Alertmanager alert intake.

  • Receives Alertmanager v4 webhook notifications.
  • Creates Paperclip issues for firing alerts.
  • Closes issues when alerts are resolved.
  • Deduplicates by alert fingerprint.

Install into Paperclip

Install the published npm package from the Forgejo registry. Always pin to an exact version in production so plugin upgrades are deliberate.

# Replace <VERSION> with the exact tag you want, e.g. 0.1.0
paperclipai plugin install @aaron/paperclip-alertmanager-plugin@<VERSION> \
  --registry https://forgejo.aaron.reynoza.org/api/packages/aaron/npm/

In the Paperclip plugin settings, configure the Alertmanager webhook receiver and target project/assignee. The webhook URL is shown on the plugin detail page after installation.

Configuration

Setting Required Default Description
companyId yes — UUID of the company that owns generated issues.
bearerTokenEnv no ALERTMANAGER_WEBHOOK_TOKEN Environment variable holding the shared bearer token. Preferred for GitOps because the same Kubernetes secret can be mounted for Alertmanager.
bearerSecretRef no — Paperclip secret-provider reference. Used only if bearerTokenEnv is unset or empty.
alertnames yes ["KubePersistentVolumeFillingUp"] Alert names that create issues.
projectId no — Optional project UUID for created issues.
priority no high Default priority for created issues.

Bearer-token source

For shared-secret GitOps deployments, set the token in a Kubernetes Secret and mount it into the Paperclip pod as ALERTMANAGER_WEBHOOK_TOKEN. The same secret is mounted into Alertmanager as bearer_token_file. The plugin validates the token with constant-time comparison and returns 401 Unauthorized on mismatch.

Development

npm install
npm run dev         # watch builds to dist/
npm run typecheck
npm test

Local-path installs are supported for development:

paperclipai plugin install /absolute/path/to/paperclip-alertmanager-plugin

Paperclip watches dist/ for local-path plugins and reloads the worker on rebuild.

Build

npm run build

This produces:

  • dist/manifest.js — plugin manifest
  • dist/worker.js — worker entrypoint
  • dist/ui/ — UI bundle

Version pinning

This repo uses semantic-version tags (v0.1.0, v0.2.0, etc.). The CI pipeline publishes an npm package on every tag push and on every push to the live branch. Use an exact version when installing:

paperclipai plugin install @aaron/paperclip-alertmanager-plugin@0.1.0

CI / npm publish

Forgejo Actions builds and publishes the package to the Forgejo npm registry.

  • Push to live publishes a live dist-tag (development / continuous delivery).
  • Push a tag v*.*.* publishes that exact version (release).

Set the repository secret NPM_TOKEN with a Forgejo package-scope token.

Dependencies

Dependencies

ID Version
@paperclipai/plugin-sdk 2026.618.0

Development dependencies

ID Version
@types/node ^24.6.0
@types/react ^19.0.8
esbuild ^0.27.3
typescript ^5.7.3
vitest ^3.0.5

Peer dependencies

ID Version
react >=18

Keywords

paperclip plugin alertmanager monitoring alerting
Details
npm
aaron/paperclip-alertmanager-plugin
2026-07-02 00:29:04 +00:00
0
Aaron Reynoza
MIT
live
130 KiB
Assets (1)
paperclip-alertmanager-plugin-0.2.0-live.20260702.15.tgz 130 KiB
Versions (6) View all
0.2.0 2026-07-02
0.2.0-live.20260702.15 2026-07-02
0.2.0-live.20260702.13 2026-07-02
0.1.0-live.20260702.12 2026-07-02
0.1.1 2026-06-23
Issues