Plugin-Caller-Workflow — Template

Jedes Plugin-Repo (ideenfabrik/idf-<slug>) bekommt genau diese eine Datei, um den Release-Mechanismus zu aktivieren:

Datei: `.gitea/workflows/release.yml`

name: Release

on:
  push:
    tags: ['v*.*.*']

jobs:
  release:
    uses: ideenfabrik/idf-ci/.gitea/workflows/release-plugin.yml@v1
    with:
      slug: idf-<plugin-slug>
    secrets: inherit

Nur slug anpassen — exakt der Plugin-Slug (= Repo-Name ohne Org-Präfix, z. B. idf-login-branding).

Voraussetzungen im Plugin-Repo

Damit der Reusable Workflow durchläuft, müssen im Plugin-Repo vorhanden sein:

<slug>.php — Plugin-Haupt-PHP mit standardmäßigem Plugin-Header, inklusive Zeile Version: X.Y.Z.
Versions-Konstante in einer PHP-Datei des Plugins: define('IDF_<UPPER_SLUG_OHNE_IDF_>_VERSION', 'X.Y.Z'); Beispiel: Für idf-login-branding → IDF_LOGIN_BRANDING_VERSION.

readme.txt im Repo-Root im WordPress-Standard-Format. Nur die WP-Metadaten pflegen — der Changelog-Abschnitt wird vom Release-Workflow automatisch aus CHANGELOG.md gefüllt:

=== Plugin Name ===
Contributors: ideenfabrik
Tags: …
Requires at least: 6.0
Tested up to: 6.4
Requires PHP: 7.4
Stable tag: 1.2.3
License: GPLv2 or later

== Description ==
Kurzbeschreibung des Plugins.

== Changelog ==
(wird beim Release automatisch aus CHANGELOG.md generiert)

CHANGELOG.md im Repo-Root — SSOT für den Changelog. Format:

# Changelog

## v1.2.3 — 2026-04-23

### Neu
- Feature xyz

### Gefixt
- Bug abc

---

## v1.2.2 — 2026-04-10
…

Alle vier Werte (Tag, Plugin-Header-Version:, PHP-Konstante, Stable tag: in readme.txt) müssen identisch sein. Der Pre-Flight-Check im Reusable bricht sonst ab.

Pflege-Aufteilung: Changelog-Einträge nur in CHANGELOG.md pflegen. readme.txt bekommt seine == Changelog == beim Release automatisch generiert — manuelle Einträge dort werden überschrieben.

Release-Ablauf (Agent/Mensch)

Auf main, nachdem alles für die Version gemergt ist:

# 1. Plugin-Header-Version, Versions-Konstante und Stable tag in readme.txt auf X.Y.Z setzen
# 2. Neuen Block in CHANGELOG.md ergänzen (neueste Version oben)
# 3. Commit
git add -A
git commit -m "Release v1.2.3"
git push

# 4. Tag setzen und pushen
git tag v1.2.3
git push --tags

Danach läuft die Action automatisch durch. Bei Erfolg liegt auf Gitea ein Release v1.2.3 mit dem ZIP idf-<slug>_v1.2.3.zip als Asset und dem Changelog-Block als Body. Das ZIP enthält readme.txt mit der automatisch befüllten == Changelog ==-Section.

Pinning-Empfehlung

Beim uses:-Aufruf die Version pinnen:

@v1 — rolling, zieht Patches und Minors automatisch mit. Empfohlen für die meisten Plugins.
@v1.2 — Patches ja, Minors nein.
@v1.2.3 — exakt einfrieren. Nur für Plugins, die gegen eine bestimmte Workflow-Version validiert wurden.

Breaking Changes am Reusable Workflow → neuer Major (v2). Plugin-Repos müssen dann bewusst auf @v2 wechseln.

Fehlerdiagnose

Bei abgebrochenem Release:

„Tag entspricht nicht vMAJOR.MINOR.PATCH" → Tag falsch formatiert. Alten Tag löschen (git tag -d vX && git push origin :refs/tags/vX), neu taggen.
„Pflichtdateien fehlen: CHANGELOG.md / readme.txt" → Datei im Repo-Root anlegen, Commit, Tag neu setzen.
„Plugin-Header-Version ≠ Tag" → <slug>.php Version-Zeile korrigieren, Commit, Tag neu setzen.
„Konstante ≠ Tag" → Versions-Konstante im PHP anpassen, Commit, Tag neu setzen.
„Stable tag ≠ Tag" → Stable tag: in readme.txt korrigieren, Commit, Tag neu setzen.
„Kein Changelog-Block für v…" → Block ## v1.2.3 — <Datum> in CHANGELOG.md anlegen, Commit, Tag neu setzen.
Release-Anlage fehlgeschlagen → Wahrscheinlich fehlende Token-Berechtigung. GITEA_TOKEN-Secret prüfen oder den Standard github.token nutzen.

Wichtig: Ein Tag, unter dem ein Release bereits existiert, kann nicht erneut einen Release erzeugen. Bei Korrekturen eine PATCH-Version höher tagen, nicht denselben Tag neu setzen.

4.1 KiB Raw Permalink Blame History