Wie veröffentlichen Sie Ihr Plugin?

Sat, 08 Aug 2026 13:00:00 +0300

GameAP-Plugins werden auf plugins.gameap.dev veröffentlicht — von dort installieren Nutzer sie direkt aus dem Panel. Diese Anleitung führt durch den gesamten Weg: vom Anlegen des Plugin-Eintrags bis zum automatischen Ausliefern neuer Versionen aus CI.

Vorausgesetzt wird, dass Ihr Plugin bereits geschrieben ist und zu einer .wasm gebaut wird. Außerdem brauchen Sie ein Konto auf plugins.gameap.dev: entweder eine normale Registrierung mit E-Mail-Bestätigung oder die Anmeldung über GitHub, GitLab oder Google.

Es gibt zwei Wege, eine Version hochzuladen: manuell über das Dashboard oder über die API aus CI. Beginnen Sie mit dem Dashboard und steigen Sie auf CI um, sobald Ihr Build stabil läuft.

Schritt 1. Ein Entwicklerkonto #

Das Veröffentlichen von Plugins erfordert ein Konto mit Entwicklerstatus. Dieser wird kostenlos und sofort vergeben — Sie müssen lediglich die Veröffentlichungsregeln akzeptieren.

Klicken Sie im Plugin-Marktplatz auf Publish your plugin („Ihr Plugin veröffentlichen“) — die Schaltfläche in der oberen rechten Ecke.

Der Plugin-Marktplatz

Die Seite mit den Veröffentlichungsregeln öffnet sich. Kurz gesagt, wozu Sie sich verpflichten:

Funktionierende, hochwertige Plugins — nur funktionsfähige, getestete Plugins, die das halten, was ihre Beschreibung verspricht.
Kein schädlicher Code — keine Backdoors, versteckten Miner oder verschleierte Logik; jede Erhebung von Nutzerdaten muss klar offengelegt werden.
Rechte und Lizenzierung — Sie besitzen den Code oder dürfen ihn verbreiten, Lizenzen Dritter werden eingehalten, und die Lizenz Ihres Plugins ist angegeben.
GameAP-Kompatibilität — das Plugin funktioniert mit aktuellen Panel-Releases und erfüllt die Anforderungen an das Plugin-Format.
Updates und Support — kritische Fehler und Sicherheitsprobleme werden innerhalb einer angemessenen Frist behoben, und Nutzermeldungen erhalten eine Antwort.
Moderation — jedes Plugin und jede Version wird geprüft, und ein Plugin, das gegen die Regeln verstößt, kann jederzeit entfernt werden.
Kein Spam und keine Duplikate — keine irreführenden Namen, kein Keyword-Stuffing.

Der vollständige Text steht auf der Seite selbst — lesen Sie ihn am besten ganz.

Klicken Sie unten auf Agree („Zustimmen“). Die Rolle wird sofort vergeben, ohne Prüfung und Wartezeit: In der Seitenleiste erscheint der Bereich Developer („Entwickler“) mit Dashboard, My Plugins, New Plugin und Support, und eine E-Mail teilt Ihnen mit, dass Sie nun Entwickler sind.

Hinweis. Die Regeln können nur mit einer bestätigten E-Mail-Adresse akzeptiert werden: Andernfalls bleibt die Schaltfläche Agree deaktiviert, und die Seite zeigt eine Erinnerung, Ihre Adresse zu bestätigen. Konten, die über GitHub, GitLab oder Google erstellt wurden, gelten sofort als bestätigt.

Die Schaltfläche Publish your plugin ist für alle sichtbar, auch für Besucher, die nicht angemeldet sind. Ohne Sitzung zeigt die Regelseite stattdessen Log in to agree („Anmelden, um zuzustimmen“) — nach der Anmeldung kehren Sie zu den Regeln zurück.

Schritt 2. Das Plugin anlegen #

Wählen Sie im linken Menü New Plugin („Neues Plugin“) — das Erstellungsformular öffnet sich.

Ein neues Plugin anlegen

Feld	Pflicht	Was gehört hinein
Name	ja	Bis zu 255 Zeichen
Summary	ja	Ein einziger Satz für die Katalogkarte, bis zu 500 Zeichen
Description	ja	Vollständige Beschreibung in Markdown — das Feld hat eine Formatierungs-Symbolleiste
Category	nein	Eine der drei unten
Labels	nein	Stichwörter, über die sich das Plugin leichter finden lässt
License	nein	Freier Text: `MIT`, `GPL-3.0`, `Proprietary`
Source URL	nein	Link zu den Quellen, falls sie offen sind
Repository URL	nein	Link zum Repository
Homepage URL	nein	Website des Plugins oder des Autors

Die Kategorien:

Server Management („Serververwaltung“) — die meisten Plugins. Alles, was Aktionen auf einem Gameserver hinzufügt.
Files („Dateien“) — Erweiterungen des Dateimanagers: Editoren, Viewer für bestimmte Formate.
Integrations („Integrationen“) — Plugins, die die Möglichkeiten des Panels wesentlich erweitern, etwa die Datenbankverwaltung.

Das Icon kann in diesem Schritt noch nicht hochgeladen werden — das Formular weist ausdrücklich darauf hin; der Uploader erscheint direkt nach dem Anlegen.

Hinweis. Source URL und Repository URL wirken sich auf mehr als den Eintrag aus. Wenn keines der beiden Felder ausgefüllt ist, muss jede Version ein Quellarchiv mitbringen — die Moderatoren brauchen etwas, gegen das sie den Build prüfen können. Füllen Sie mindestens eines der Felder aus, wenn Ihre Quellen öffentlich sind.

Schritt 3. Die Plugin-ID #

Nach dem Klick auf Create („Anlegen“) landen Sie auf der Bearbeitungsseite des Plugins. Ihr erster Block ist die Plugin ID — ein schreibgeschütztes Feld mit einer Kopierschaltfläche.

Diese ID muss in den Quellcode Ihres Plugins eingetragen werden — in das id-Feld der PluginInfo-Struct, die GetInfo zurückgibt. So ordnet das Panel ein installiertes Plugin seinem Marktplatz-Eintrag zu.

Die ID wird einmalig beim Anlegen erzeugt und kann nicht geändert werden. Im Kern ist sie eine 64-Bit-Zahl (8 zufällige Bytes) in Base32-Schreibweise — 13 lateinische Buchstaben und Ziffern, zum Beispiel fmqnme42gg7da. Dieselbe ID taucht in der URL der Plugin-Seite und in der Adresse des CI-Endpunkts auf.

Wie das in bestehenden Plugins aussieht:

plugin-mysql — die Konstante PLUGIN_ID (fmqnme42gg7da)
plugin-goldsrc-addons — PLUGIN_ID (ezvdsxmlu6fbk)
plugin-minecraft-modrinth — PLUGIN_ID (dshdabjp2l73a)

Hinweis. Tragen Sie die ID ein und bauen Sie die .wasm neu, bevor Sie die erste Version hochladen. Versionen sind unveränderlich: Sie können eine Datei nicht unter derselben Nummer erneut hochladen — Sie müssten die Versionsnummer erhöhen.

Schritt 4. Icon und Übersetzungen #

Dieselbe Bearbeitungsseite enthält einen Icon-Uploader: JPG, PNG, WebP oder SVG, bis zu 2 MB, empfohlen 128×128.

Die Plugin-Seite hat einen Block Translations („Übersetzungen“). Der Katalog ist zweisprachig, und jeder Besucher sieht den Eintrag in seiner eigenen Sprache: Ohne Übersetzung bekommt ein russischer Nutzer die englische Beschreibung und umgekehrt. Name, Kurzbeschreibung und Beschreibung werden pro Sprache separat übersetzt — fünf Minuten Arbeit, die den Eintrag spürbar besser lesen lassen.

Schritt 5. Eine Version hochladen #

Suchen Sie auf der Plugin-Seite die Karte Versions („Versionen“) und klicken Sie auf Upload Version („Version hochladen“).

Eine neue Version hochladen

Feld	Pflicht	Was gehört hinein
Version	ja	Semantische Version: `1.0.0`, `1.2.0-beta.1`
Plugin File	ja	Die kompilierte `.wasm`, bis zu 100 MB
GPG Signature	nein	Abgetrennte Signatur `.sig` oder `.asc`, bis zu 1 MB
Source Code Archive	abhängig	`.zip` oder `.tar.gz`, bis zu 50 MB
Changelog	nein	Was sich seit der vorherigen Version geändert hat, in Markdown
Stable Release	—	Ein Schalter, standardmäßig aktiviert
Min GameAP Version	nein	Die Panel-Version, ab der Ihr Plugin funktioniert

Die GPG-Signatur ist optional, aber willkommen: Der Server speichert sie unverändert und verifiziert sie nie — sie existiert, damit Nutzer die Authentizität der Datei selbst prüfen können.

Das Quellcode-Archiv ist Pflicht, wenn beim Plugin weder Source URL noch Repository URL ausgefüllt sind — das Formular ändert die Feldbezeichnung dann selbstständig von „(Optional)“ zu „(Required)“. Das Archiv wird nur für Moderation und Build-Verifikation verwendet; es wird nie veröffentlicht und ist über keinen öffentlichen Endpunkt erreichbar.

Hinweis. Eine über das Dashboard hochgeladene Version bleibt ein Entwurf. Bis Sie sie zur Prüfung einreichen, sieht sie niemand.

Screenshots der Version #

Direkt nach dem Upload öffnet sich ein zweiter Schritt — Add Screenshots („Screenshots hinzufügen“). Screenshots gehören zu einer bestimmten Version: JPG, PNG oder WebP, bis zu 10 Stück, jeweils 5 MB. Der Schritt kann übersprungen und später von der Versionsseite aus nachgeholt werden.

Schritt 6. Zur Prüfung einreichen #

Plugins durchlaufen eine Moderation — anhand genau der Veröffentlichungsregeln, die Sie in Schritt 1 akzeptiert haben. Im Kopfbereich der Plugin-Seite gibt es die Schaltfläche Submit for Review („Zur Prüfung einreichen“) — sie ist nur sichtbar, solange das Plugin den Status Draft oder Rejected hat.

Ein Plugin ohne Versionen kann nicht eingereicht werden — laden Sie zuerst eine Version hoch. Das Einreichen einer Version über die Versionstabelle versetzt auch das Plugin selbst von Draft zu Pending Review, sodass die Schaltfläche im Kopfbereich in der Regel nicht separat gebraucht wird.

Status	Bedeutung	Was Sie tun können
Draft	Angelegt, nirgendwo eingereicht	Bearbeiten, zur Prüfung einreichen, löschen
Pending Review	Wartet auf einen Moderator	Warten
Rejected	Ein Moderator hat es zurückgeschickt	Korrigieren und erneut einreichen
Released	Für alle im Katalog verfügbar	Neue Versionen hochladen
Approved	Ein Zwischenstatus im Datenmodell	—
Deprecated	Als veraltet markiert	Weiterhin installierbar, aber gekennzeichnet
Retracted	Von der Veröffentlichung zurückgezogen	Nicht zur Installation verfügbar

Nach der Freigabe wechseln Plugin und Version direkt zu Released. Öffentlich sichtbar sind nur Objekte in diesem Status: Wenn ein Plugin veröffentlicht ist, seine einzige Version aber noch in der Prüfung, gibt es nichts zu installieren.

Der Ablehnungsgrund kommt per E-Mail — die Plugin-Seite zeigt nur den Status, also prüfen Sie Ihren Posteingang.

Deploy-Tokens #

Um Versionen aus CI zu veröffentlichen, brauchen Sie ein Deploy-Token. Es befindet sich ganz unten auf der Plugin-Seite, in der Karte Deploy Tokens.

Die Karte mit den Deploy-Tokens

Klicken Sie auf Create Token („Token erstellen“) und füllen Sie den Dialog aus: einen Namen (zum Beispiel GitHub Actions) und optional ein Ablaufdatum.

Ein Deploy-Token erstellen

Hinweis. Das Token wird genau einmal angezeigt, direkt nach dem Erstellen. Auf dem Server wird nur sein Hash gespeichert, der Wert lässt sich nicht wiederherstellen — kopieren Sie es direkt in Ihre CI-Secrets.

Was Sie über Tokens wissen sollten:

Ein Token ist an ein Plugin gebunden und kann nur dessen Versionen hochladen. Es öffnet weder andere Plugins noch den Rest der API.
Das Format ist gapd_ plus 43 Zeichen, insgesamt 48. Das Präfix ist für Secret-Scanner leicht zu erkennen.
Die Tabelle zeigt das Token-Präfix, das Erstellungsdatum, die letzte Verwendung und das Ablaufdatum — praktisch, um herauszufinden, welches Token noch in Gebrauch ist.
Der Widerruf wirkt sofort: Eine Pipeline mit einem widerrufenen Token schlägt beim nächsten Lauf fehl.
Ein einzelnes Plugin kann bis zu 20 Tokens haben.

Aus CI veröffentlichen #

Der CI-Endpunkt nimmt eine neue Version ohne interaktiven Login entgegen — er authentifiziert sich mit einem Deploy-Token.

Hochladen mit curl #

curl --fail-with-body -sS \
 -H "Authorization: Bearer $GAMEAP_DEPLOY_TOKEN" \
 -F "version=1.2.3" \
 -F "file=@build/plugin.wasm" \
 -F "signature=@build/plugin.wasm.asc" \
 -F "changelog=Absturz beim Serverneustart behoben" \
 -F "min_gameap_version=4.1.0" \
 -F "is_stable=true" \
 "https://plugins.gameap.dev/api/ci/plugins/$GAMEAP_PLUGIN_ID/versions"

Die Anfrage ist ein POST mit multipart/form-data. Die Formularfelder:

Feld	Pflicht	Beschreibung
`version`	ja	Semantische Version, z. B. `1.2.3`
`file`	ja	Die kompilierte `.wasm`, bis zu 100 MB
`signature`	nein	Abgetrennte GPG-Signatur, bis zu 1 MB
`source`	abhängig	Quellarchiv `.zip`/`.tar.gz` bis 50 MB; Pflicht, wenn das Plugin weder Source URL noch Repository URL hat
`changelog`	nein	Release-Notes; praktisch aus einer Datei: `-F "changelog=<CHANGELOG.md"`
`min_gameap_version`	nein	Minimale GameAP-Version
`min_plugin_api_version`	nein	Minimale Plugin-API-Version (das Dashboard-Formular hat dieses Feld nicht)
`is_stable`	nein	`true` oder `1` markiert die Version als stabil
`submit`	nein	Standardmäßig `true`; `false` belässt die Version als Entwurf

Setzen Sie keinen Schrägstrich ans Ende der URL. Der Router beantwortet .../versions/ mit einem 301, und curl wiederholt den POST-Body bei einem Redirect nicht — der Upload würde still zu einem GET.

Eine erfolgreiche Antwort ist ein 201 mit einem Body wie:

{
 "id": 123,
 "plugin_id": "fmqnme42gg7da",
 "version": "1.2.3",
 "file_size": 1048576,
 "file_hash": "9f86d081884c7d65...",
 "has_source": false,
 "status": "pending_review"
}

GitHub Actions #

Dieser Workflow wird ausgelöst, wenn ein GitHub-Release veröffentlicht wird, baut das Plugin, signiert es — sofern ein GPG-Schlüssel in den Secrets konfiguriert ist — und lädt es zu plugins.gameap.dev hoch. Der Release-Text wird zum Changelog, und die Version wird nur dann als stabil markiert, wenn das Release kein Pre-Release ist.

name: Publish plugin

on:
 release:
 types: [published]

jobs:
 publish:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Build plugin
 run: make wasm  # muss build/plugin.wasm erzeugen

 - name: Sign plugin
 if: env.GPG_SIGNING_KEY != ''
 env:
 GPG_SIGNING_KEY: ${{ secrets.GPG_SIGNING_KEY }}
 GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
 run: |
 printf '%s' "$GPG_SIGNING_KEY" | gpg --batch --import
 printf '%s' "$GPG_PASSPHRASE" | gpg --batch --yes \
 --pinentry-mode loopback --passphrase-fd 0 \
 --detach-sign --armor \
 -o build/plugin.wasm.asc build/plugin.wasm

 - name: Publish to plugins.gameap.dev
 env:
 GAMEAP_DEPLOY_TOKEN: ${{ secrets.GAMEAP_DEPLOY_TOKEN }}
 GAMEAP_PLUGIN_ID: ${{ vars.GAMEAP_PLUGIN_ID }}
 TAG: ${{ github.event.release.tag_name }}
 RELEASE_BODY: ${{ github.event.release.body }}
 PRERELEASE: ${{ github.event.release.prerelease }}
 run: |
 VERSION="${TAG#v}"
 printf '%s' "$RELEASE_BODY" > "$RUNNER_TEMP/changelog.md"
 ARGS=(--fail-with-body -sS
 -H "Authorization: Bearer ${GAMEAP_DEPLOY_TOKEN}"
 -F "version=${VERSION}"
 -F "file=@build/plugin.wasm"
 -F "changelog=<${RUNNER_TEMP}/changelog.md")
 # Signatur nur anhängen, wenn der Sign-Schritt sie erzeugt hat
 if [ -f build/plugin.wasm.asc ]; then
 ARGS+=(-F "signature=@build/plugin.wasm.asc")
 fi
 if [ "$PRERELEASE" != "true" ]; then
 ARGS+=(-F "is_stable=true")
 else
 ARGS+=(-F "is_stable=false")
 fi
 curl "${ARGS[@]}" \
 "https://plugins.gameap.dev/api/ci/plugins/${GAMEAP_PLUGIN_ID}/versions"

VERSION="${TAG#v}" entfernt das führende v, sodass das Tag v1.2.3 als Version 1.2.3 veröffentlicht wird.

Die produktive Variante dieses Workflows — mit Frontend-Build, Cargo-Cache und HTTP-Statusprüfung — liegt in plugin-mysql.

Das GitHub-Repository konfigurieren #

Token und Plugin-ID gehören nicht in den Code — sie gehören in die Repository-Einstellungen. Öffnen Sie Settings → Secrets and variables (unter Security and quality) → Actions.

Der Einstellungsbereich des Repositorys

Klicken Sie auf dem Tab Secrets auf New repository secret und fügen Sie hinzu:

Name	Wert
`GAMEAP_DEPLOY_TOKEN`	Das Deploy-Token, das Sie beim Erstellen kopiert haben (beginnt mit `gapd_`)
`GPG_SIGNING_KEY`	Ein privater GPG-Schlüssel im ASCII-Armor-Format, falls Sie Ihre Builds signieren
`GPG_PASSPHRASE`	Die Passphrase des GPG-Schlüssels, falls dieser geschützt ist

Repository-Secrets

Auf dem Tab Variables klicken Sie auf New repository variable und fügen Sie hinzu:

Name	Wert
`GAMEAP_PLUGIN_ID`	Die Plugin-ID, z. B. `fmqnme42gg7da`

Repository-Variablen

Die Plugin-ID ist derselbe Base32-Bezeichner, den Sie in PluginInfo eingetragen haben. Kopieren Sie ihn mit der Schaltfläche neben dem Feld Plugin ID auf der Bearbeitungsseite oder aus dem Block Details auf der Plugin-Seite.

Die ID liegt absichtlich in den Variablen und nicht in den Secrets: Sie ist kein Geheimnis, und wenn sie in den CI-Logs sichtbar ist, lassen sich Fehler deutlich leichter diagnostizieren. Das Token hingegen ist immer ein Secret.

So exportieren Sie einen privaten GPG-Schlüssel für GPG_SIGNING_KEY:

gpg --armor --export-secret-keys IHRE_KEY_ID

Veröffentlichen Sie den öffentlichen Schlüssel dort, wo Nutzer ihn finden können — etwa im README des Plugins —, damit die Signatur überprüfbar ist.

Dashboard und CI: unterschiedliche Vorgaben #

Was	Dashboard	CI
Stabiles Release	Der Schalter ist standardmäßig aktiviert	`is_stable` ist standardmäßig false — explizit übergeben
Einreichen zur Prüfung	Manuell, per Schaltfläche	`submit` ist standardmäßig true — die Version geht sofort in die Prüfung
Screenshots	Werden direkt nach dem Upload angeboten	Nicht unterstützt, fügen Sie sie über das Dashboard hinzu

Wenn CI nur die Datei hochladen und Sie die Metadaten von Hand nachpflegen wollen, übergeben Sie submit=false, und die Version bleibt ein Entwurf.

Fehler #

Code	Ursache
`400`	Ungültige Plugin-ID, ein fehlerhafter Multipart-Body oder kein `file` übergeben
`401`	Das Token fehlt, ist ungültig oder abgelaufen; der Header hat nicht die Form `Bearer gapd_...`
`403`	Das Token ist gültig, wurde aber für ein anderes Plugin ausgestellt
`409`	Eine Version mit dieser Nummer existiert bereits
`422`	Die Version besteht die Semver-Prüfung nicht; das Quellarchiv fehlt, ist zu groß oder kein `.zip`/`.tar.gz`; die Größenlimits für Datei oder Signatur sind überschritten

Fehler-Bodies haben eine einheitliche Form:

{
 "status": "error",
 "error": "version already exists",
 "message": "version already exists",
 "http_code": 409
}

Wiederholen Sie den Upload nach einem 5xx-Fehler nicht blind. Das Schreiben der Version und ihr Einreichen zur Prüfung sind keine einzelne Transaktion: Die Version kann bereits existieren, und ein erneuter Versuch liefert 409. Öffnen Sie das Dashboard und prüfen Sie, was tatsächlich passiert ist.

Versionen aktualisieren und zurückziehen #

Eine neue Version wird genau wie die erste hochgeladen — über das Dashboard oder aus CI. Bereits hochgeladene Versionen sind unveränderlich: Eine Datei unter derselben Nummer erneut hochzuladen ist nicht möglich, der Versuch liefert 409. War der Build falsch, erhöhen Sie die Patch-Version.

Jede Zeile der Versionstabelle hat eigene Aktionen:

Edit („Bearbeiten“) — Changelog und Metadaten ändern.
Submit for Review („Zur Prüfung einreichen“) — für Entwürfe und abgelehnte Versionen.
Deprecate („Als veraltet markieren“) — für veröffentlichte Versionen. Die Version bleibt verfügbar, wird aber als veraltet gekennzeichnet.
Retract („Zurückziehen“) — für veröffentlichte und veraltete Versionen. Die Version wird von der Veröffentlichung zurückgezogen.

Nur ein Plugin im Status Draft kann gelöscht werden. Ein veröffentlichtes Plugin lässt sich nicht entfernen — es kann zurückgezogen werden.

Checkliste #

Die E-Mail ist bestätigt, die Veröffentlichungsregeln sind akzeptiert, und das Konto hat Entwicklerstatus.
Das Plugin ist angelegt, und Name sowie beide Beschreibungen sind ausgefüllt.
Source URL oder Repository URL ist ausgefüllt — sonst braucht jede Version ein Quellarchiv.
Die Plugin-ID steht in PluginInfo.id, und die .wasm wurde danach neu gebaut.
Das Icon ist hochgeladen, und die Übersetzungen des Eintrags sind gepflegt.
Die Version ist hochgeladen, optional ergänzt um Signatur und Screenshots.
Die Version ist zur Prüfung eingereicht, nicht als Entwurf liegen geblieben.
Für CI: Ein Deploy-Token ist erstellt und in den Secrets hinterlegt, die Plugin-ID steht in den Variablen.
Der Workflow hat keinen Schrägstrich am Ende der URL und übergibt is_stable explizit.
Nach dem Release ist bestätigt, dass Plugin und Version den Status Released haben.

Anleitungen — GameAP-Blog