Plugin: hook-exec

Führt benutzerdefinierte Shell-Befehle in jeder externen Plugin-Phase aus, die SemRel unterstützt: condition, generator, pre-tag und release. Damit lassen sich Build-Skripte, eigene Prüfungen oder Deployment-Befehle aufrufen, ohne ein eigenes Plugin schreiben zu müssen.

Installation

Binärdatei

semrel plugin install @semrel/hook-exec

semrel plugin install lädt die Binärdatei nach .semrel/plugins/ herunter und aktualisiert .semrel.lock. Committe .semrel.lock, um die Version für dein Team festzuschreiben.

Docker

Vorgefertigte, signierte Multi-Plattform-Images (linux/amd64, linux/arm64) werden bei jedem Release veröffentlicht:

docker pull ghcr.io/semrels/hook-exec:latest

Prüfe die Image-Signatur mit cosign:

cosign verify ghcr.io/semrels/hook-exec:latest \
  --certificate-identity-regexp 'https://github.com/SemRels/hook-exec/.github/workflows/release.yml.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Konfiguration

version: 1
plugins:
  - uses: @semrel/hook-exec
    phase: pre-tag
    args:
      cmd: ./scripts/build.sh
      timeout: 10m
      env: |
        BUILD_MODE: release

SemRel bildet jeden args-Wert auf genau eine Umgebungsvariable ab. Strukturierte Werte wie env müssen deshalb als YAML- oder JSON-String übergeben werden.

Umgebungsvariablen

Name	Erforderlich	Standard	Beschreibung
`SEMREL_PLUGIN_CMD`	nein	`—`	Befehl für die konfigurierte Phase. Erforderlich, sofern kein lebenszyklus-spezifischer Befehl gesetzt ist.
`SEMREL_PLUGIN_SHELL`	nein	`sh`	Shell-Programm. Unter Windows standardmäßig `cmd`.
`SEMREL_PLUGIN_CWD`	nein	Repository-Wurzel	Arbeitsverzeichnis des Kindprozesses.
`SEMREL_PLUGIN_ENV`	nein	`—`	YAML- oder JSON-String-Map, die in die Kind-Umgebung gemischt wird.
`SEMREL_PLUGIN_TIMEOUT`	nein	`5m`	Go-Dauer wie `30s` oder `10m`.
`SEMREL_PLUGIN_RUN_IN_DRY_RUN`	nein	`false`	Befehl auch bei `SEMREL_DRY_RUN=true` ausführen.
`SEMREL_PLUGIN_PHASE`	nein	abgeleitet	Explizite Phase für lebenszyklus-spezifische Befehle.

Lebenszyklus-spezifische Befehle

Zur Kompatibilität mit der Begrifflichkeit von @semantic-release/exec können diese Schlüssel cmd ersetzen:

Argument	SemRel-Phase	Verhalten
`verifyConditionsCmd`	`condition`	Entscheidet, ob die Release startet.
`generateNotesCmd`	`generator`	Stdout wird zu `SEMREL_CHANGELOG`; Diagnosen gehören auf stderr.
`verifyReleaseCmd`	`pre-tag`	Läuft vor `prepareCmd`.
`prepareCmd`	`pre-tag`	Bereitet Build-Ausgaben oder generierte Dateien vor.
`publishCmd`	`release`	Läuft vor `successCmd`.
`successCmd`	`release`	Aktion nach erfolgreicher Veröffentlichung.

Setze phase, wenn die Konfiguration Befehle für mehrere Phasen enthält. Ist genau eine Phasengruppe vorhanden, leitet hook-exec sie selbst ab. SemRel besitzt keine externe analyzer-Phase und ruft nach einem Fehlschlag keine Plugins mehr auf. analyzeCommitsCmd und failCmd werden deshalb mit einem expliziten Fehler abgelehnt, statt stillschweigend ignoriert zu werden.

Release-Kontextvariablen

SEMREL_VERSION
SEMREL_CURRENT_VERSION
SEMREL_TAG_NAME
SEMREL_BRANCH
SEMREL_BUMP
SEMREL_CHANGELOG
SEMREL_DRY_RUN

Befehle unterstützen zusätzlich die Platzhalter ${nextRelease.version}, ${lastRelease.version}, ${gitTag}, ${tag}, ${channel}, ${branch} und ${date}. Eingesetzte Werte werden shell-gequotet; setze einen Platzhalter daher nicht zusätzlich in Anführungszeichen.

Verhalten

POSIX-Shells werden mit -c aufgerufen, PowerShell mit -NoProfile -NonInteractive -Command und cmd.exe mit /D /S /C. Exit-Codes ungleich null und Timeouts lassen das Plugin fehlschlagen; unter Unix beendet ein Timeout die gesamte Prozessgruppe der Shell. Bei SEMREL_DRY_RUN=true werden Befehle protokolliert und übersprungen, sofern runInDryRun nicht aktiviert ist.

Sicherheit

hook-exec führt bewusst vertrauenswürdige Repository-Konfiguration mit den Rechten des SemRel-Prozesses aus. Prüfe Änderungen an Befehlen so sorgfältig wie Änderungen an CI-Workflows.

Verkette niemals Commit-Nachrichten, Changelog-Inhalte, Beitragendendaten oder Branch-Namen in einen Befehl.
Konsumiere den Release-Kontext über gequotete Umgebungsvariablen innerhalb eines Skripts.
Halte Geheimnisse aus .semrel.yaml heraus und stelle sie über die CI-Umgebung bereit.
Nutze eine minimale Shell, ein explizites Arbeitsverzeichnis und ein endliches Timeout.

Quelle

SemRels/hook-exec