Wie veröffentlichen Sie Ihr Plugin?

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.

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.

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“).

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.

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.

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

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:

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.

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

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

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 #

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 #

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.