aaron/paperclip-alertmanager-plugin
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages 1 Wiki Activity Actions
Paperclip native plugin for Alertmanager alert intake: create issues on firing alerts, close on resolved, with deduplication.
2 commits 11 branches 2 tags 164 KiB
  • TypeScript 98.1%
  • JavaScript 1.9%
Find a file
Exact
Paperclip Operator efcd6f3b4b
Some checks are pending
npm publish / publish (push) Waiting to run
Details
Implement plugin v0.1.0: auth, create-on-firing, close-on-resolved, fingerprint dedup 
- Bearer-token auth: validates Authorization header against ALERTMANAGER_WEBHOOK_TOKEN
- Firing → create: creates Paperclip issues for KubePersistentVolumeFillingUp alerts
- Resolved → close: auto-closes issues when alert resolves with closing comment
- Fingerprint dedup: idempotent on Alertmanager fingerprint, no duplicate issues
- Configurable alertname filter (ALERTMANAGER_ALERTNAMES)
- Configurable reopen-on-firing (ALERTMANAGER_REOPEN_ON_FIRING)
- Priority mapping: critical→critical, warning→high, info→medium
- Full instance config schema with validation
- 26 passing tests covering auth, create, dedup, close, reopen, filtering

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-23 01:27:27 +00:00
.forgejo/workflows feat: scaffold Paperclip Alertmanager plugin with npm publish CI 2026-06-22 01:20:24 +00:00
src Implement plugin v0.1.0: auth, create-on-firing, close-on-resolved, fingerprint dedup 2026-06-23 01:27:27 +00:00
tests Implement plugin v0.1.0: auth, create-on-firing, close-on-resolved, fingerprint dedup 2026-06-23 01:27:27 +00:00
.gitignore feat: scaffold Paperclip Alertmanager plugin with npm publish CI 2026-06-22 01:20:24 +00:00
esbuild.config.mjs feat: scaffold Paperclip Alertmanager plugin with npm publish CI 2026-06-22 01:20:24 +00:00
LICENSE feat: scaffold Paperclip Alertmanager plugin with npm publish CI 2026-06-22 01:20:24 +00:00
package-lock.json feat: scaffold Paperclip Alertmanager plugin with npm publish CI 2026-06-22 01:20:24 +00:00
package.json feat: scaffold Paperclip Alertmanager plugin with npm publish CI 2026-06-22 01:20:24 +00:00
README.md feat: scaffold Paperclip Alertmanager plugin with npm publish CI 2026-06-22 01:20:24 +00:00
tsconfig.json feat: scaffold Paperclip Alertmanager plugin with npm publish CI 2026-06-22 01:20:24 +00:00
vitest.config.ts feat: scaffold Paperclip Alertmanager plugin with npm publish CI 2026-06-22 01:20:24 +00:00

README.md

@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.

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.