Plugins verwalten

semrel installiert Plugins als lokale Binärdateien und löst sie zur Laufzeit direkt auf — kein Daemon, kein globaler Zustand. Das Plugin-Management-System stellt sicher, dass jedes Teammitglied und jeder CI-Runner exakt dieselbe Binary, in exakt derselben Version, verwendet.

Ein Plugin installieren projektlokal

1. Vollständige Registry-Referenz verwenden

   Alle offiziellen Plugins gehören zum Namespace @semrel. Dieser muss immer angegeben werden:

   semrel plugin install @semrel/github

   Einen nackten Namen (github) akzeptiert semrel nur, wenn der Registry-Eintrag keinen Namespace hat.

2. Bei Bedarf eine Version pinnen

   semrel plugin install @semrel/github@1.2.0

3. Die Lock-Datei committen

   Eine Standard-Installation schreibt automatisch .semrel.lock im Repository-Root. Diese Datei zusammen mit .semrel.yaml committen, damit alle dieselbe Version verwenden.

Namespace erforderlich

semrel plugin install github schlägt fehl, wenn das Plugin zum Namespace @semrel gehört:

plugin "github" belongs to namespace @semrel — use:
  semrel plugin install @semrel/github

Kategorie-Präfix-Namen wie provider-github oder condition-github-actions werden zu ihren kurzen Registry-Namen (github, github-actions) aufgelöst und unterliegen derselben Namespace-Regel.

Benennung und Normalisierung

Alle Schreibweisen führen zur gleichen Binary auf der Festplatte — semrel entfernt Namespace, Version und Kategorie-Präfix, bevor es nach einer Binärdatei sucht:

Config-Eintrag	Binary auf der Platte
uses: github	semrel-plugin-github
uses: provider-github	semrel-plugin-github
uses: @semrel/github@1.2.0	semrel-plugin-github
uses: github-actions	semrel-plugin-github-actions
uses: condition-github-actions	semrel-plugin-github-actions

---

Die Datei .semrel.lock neu

.semrel.lock speichert die exakte Version und die veröffentlichten Prüfsummen jeder projektlokalen Plugin-Installation. Die Datei wird automatisch aktualisiert, wenn semrel plugin install ohne --plugin-dir aufgerufen wird.

{
  "semrelLockVersion": 1,
  "updatedAt": "2026-06-11T09:33:00Z",
  "plugins": [
    {
      "binaryName": "semrel-plugin-github",
      "ref": "@semrel/github",
      "version": "1.2.0",
      "checksums": {
        "linux_amd64":   "3b4c…",
        "linux_arm64":   "9f1e…",
        "darwin_amd64":  "c72a…",
        "darwin_arm64":  "55d0…",
        "windows_amd64": "a81b…",
        "windows_arm64": "e3f7…"
      }
    }
  ]
}

Prüfsummen werden für alle veröffentlichten Plattformen gespeichert, sodass semrel plugin restore die Binary auf jedem Betriebssystem und jeder Architektur ohne Registry-Abfrage verifizieren kann.

Was committen, was ignorieren

• .semrel.yaml Konfiguration — committen
• .semrel.lock gepinnte Plugin-Versionen — committen
• Ordner.semrel/

  • Ordnerplugins/ Binary-Cache — ignoriert

    • …
  • Ordnerregistry-cache/ Metadaten-Cache — ignoriert

    • …
  • Ordnerlinux_amd64/ Download-Cache — ignoriert

    • …
  • Ordnerdarwin_arm64/ Download-Cache — ignoriert

    • …
  • Ordnerwindows_amd64/ Download-Cache — ignoriert

    • …
  • …

Folgende Einträge in .gitignore aufnehmen:

# semrel — lokale Binärdateien und Caches (NICHT committen)
.semrel/plugins/
.semrel/registry-cache/
.semrel/linux_*/
.semrel/darwin_*/
.semrel/windows_*/
# .semrel.lock im Repo-Root wird committed

---

semrel plugin restore neu

semrel plugin restore liest .semrel.lock, lädt alle aufgeführten Plugins nach .semrel/plugins/, überspringt bereits vorhandene Binärdateien und verifiziert die Prüfsumme für die aktuelle Plattform.

Dieses Kommando auf CI und nach dem Klonen eines Repositories ausführen:

GitHub Actions

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: semrel einrichten
        run: |
          curl -sSL https://semrel.io/install.sh | sh
      - name: semrel-Plugins wiederherstellen
        run: semrel plugin restore
      - name: Release
        run: semrel release
        env:
          SEMREL_PLUGIN_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

release:
  stage: release
  script:
    - semrel plugin restore
    - semrel release
  variables:
    SEMREL_PLUGIN_TOKEN: $CI_JOB_TOKEN

Gitea Actions

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: semrel-Plugins wiederherstellen
        run: semrel plugin restore
      - name: Release
        run: semrel release
        env:
          SEMREL_PLUGIN_TOKEN: ${{ secrets.GITEA_TOKEN }}

---

Plugin-Auflösungsreihenfolge

Beim Suchen nach einer Plugin-Binary prüft semrel diese Orte in dieser Reihenfolge:

1. path: in .semrel.yaml — explizite lokale Binary, höchste Priorität. Ideal für Entwicklung oder eigene Builds.

2. .semrel/plugins/<binary> — projektlokale Installation. Wird durch semrel plugin install und semrel plugin restore befüllt.

3. ~/.semrel/plugins/<binary> — benutzerglobale Installation. Steht in allen Repositories auf der Maschine zur Verfügung.

4. $PATH — systemverwaltete Binary. Nützlich für Paketmanager-Installationen.

Tipp

Projektlokale Binärdateien (.semrel/plugins/) haben Vorrang vor dem benutzerglobalen Verzeichnis, sodass verschiedene Repositories unterschiedliche Plugin-Versionen pinnen können, ohne sich gegenseitig zu beeinflussen.

---

---

Automatischer Plugin-Restore während semrel release

semrel release prüft die Plugin-Verfügbarkeit vor allem anderen. Das genaue Verhalten hängt davon ab, ob .semrel.lock committed ist:

Situation	Was semrel macht
Alle Plugins vorhanden	Sofort weitermachen — kein Download notwendig
Plugins fehlen + .semrel.lock vorhanden	semrel plugin restore automatisch ausführen, dann weitermachen
Plugins fehlen, kein Lock-File	Einzelnen Auto-Install versuchen (Best-Effort, neueste stabile Version)

Mit .semrel.lock (empfohlen)

$ semrel release
⬇  plugins missing — running semrel plugin restore from .semrel.lock…
✓  restored @semrel/github@1.2.0 → .semrel/plugins/semrel-plugin-github
✓  restored @semrel/github-actions@0.1.0 → .semrel/plugins/semrel-plugin-github-actions
Running condition checks…

Der Restore aus der Lock-Datei ist eine harte Operation: Wenn die Prüfsumme einer Binary nicht übereinstimmt, bricht semrel sofort ab, statt stillschweigend eine andere Binary zu verwenden.

Ohne .semrel.lock

Ohne Lock-Datei versucht semrel, jedes fehlende Plugin einzeln zu installieren. Versions-Auflösung:

1. Version aus uses: — uses: github@1.2.0 pinnt die Version explizit.
2. Neueste stabile Version — wenn keine Version angegeben ist, wird die neueste Nicht-Prerelease-Version geladen.

Tipp

.semrel.lock committen für reproduzierbare, auditierbare Plugin-Installationen. Ohne Lock-Datei holt sich semrel release auf einem frischen Rechner die gerade aktuelle Version — was sich im Laufe der Zeit ändern kann.

---

Installation in ein anderes Verzeichnis

Mit --plugin-dir in ein anderes Verzeichnis als .semrel/plugins/ installieren:

# Benutzerglobale Installation (aktualisiert .semrel.lock NICHT)
semrel plugin install @semrel/github --plugin-dir ~/.semrel/plugins

# Eigener Pfad
semrel plugin install @semrel/github --plugin-dir /opt/semrel/plugins

Achtung

Die Installation mit --plugin-dir aktualisiert .semrel.lock nicht. Nur Standard-projektlokale Installationen werden in der Lock-Datei erfasst.

---

Plugin-Überblick CLI-Referenz Registry ↗