feat(scripts): add CI utilities for versioning and changelog

- Add scripts to detect version changes and generate changelogs
- Include setup for installing and configuring git-cliff
- Automate release creation and changelog updates for CI workflows
- Improve Git author setup for consistent commits

scripts/detect-version-change.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# === Inputs from GitHub/Gitea Action environment ===
+GIT_REF="${GITHUB_REF:-}"
+COMMIT_BEFORE="${GITHUB_EVENT_BEFORE:-}"
+COMMIT_AFTER="${GITHUB_SHA:-}"
+VERSION_FILE="VERSION"
+
+echo "🔍 Comparing commits:"
+echo "Before: $COMMIT_BEFORE"
+echo "After:  $COMMIT_AFTER"
+
+# === Check branch condition ===
+if [[ "$GIT_REF" != "refs/heads/main" ]]; then
+  echo "Not on 'main' branch – skipping version check."
+  echo "version_changed=false" >> "$GITHUB_OUTPUT"
+  exit 0
+fi
+
+echo "📄 Changed files:"
+git diff --name-only "$COMMIT_BEFORE" "$COMMIT_AFTER" || echo "(diff failed)"
+
+if git diff --name-only "$COMMIT_BEFORE" "$COMMIT_AFTER" | grep -q "^$VERSION_FILE$"; then
+  echo "✅ VERSION file was changed"
+  echo "VERSION_CHANGED=true" >> "$GITHUB_ENV"
+  echo "version_changed=true" >> "$GITHUB_OUTPUT"
+else
+  echo "ℹ️ VERSION file not changed"
+  echo "VERSION_CHANGED=false" >> "$GITHUB_ENV"
+  echo "version_changed=false" >> "$GITHUB_OUTPUT"
+fi

scripts/generate-unreleased-changelog.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CHANGELOG_FILE="CHANGELOG.md"
+CLIFF_CONFIG="cliff.toml"
+GIT_BRANCH="${GITHUB_REF##refs/heads/}"
+
+# === Step 1: Generate Changelog (only if file exists or on main) ===
+if [[ -f "$CHANGELOG_FILE" || "$GIT_BRANCH" == "main" ]]; then
+  echo "📄 Generating $CHANGELOG_FILE using git-cliff..."
+  git-cliff -c "$CLIFF_CONFIG" -o "$CHANGELOG_FILE"
+else
+  echo "ℹ️  $CHANGELOG_FILE does not exist and branch is not 'main'. Skipping generation."
+  exit 0
+fi
+
+# === Step 2: Commit and push changes if any ===
+git add "$CHANGELOG_FILE"
+
+if git diff --cached --quiet; then
+  echo "✅ No changes to commit – changelog is up to date."
+else
+  echo "✍️  Committing updated $CHANGELOG_FILE..."
+  git commit -m "chore(changelog): update unreleased changelog"
+  echo "🚀 Pushing to origin/$GIT_BRANCH..."
+  git push origin "$GIT_BRANCH"
+fi

scripts/install-git-cliff.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# install-git-cliff.sh – holt neueste oder gewünschte git-cliff-Binary (x86_64)
+# Usage: sudo ./install-git-cliff.sh        # neueste Version
+#        sudo ./install-git-cliff.sh 2.9.0  # bestimmte Version
+set -euo pipefail
+
+REPO="orhun/git-cliff"
+ARCH_OS="x86_64-unknown-linux-gnu"
+INSTALL_DIR="/usr/local/bin"
+VERSION="${1:-latest}"
+
+need() { command -v "$1" >/dev/null || { echo "$1 fehlt"; exit 1; }; }
+need curl; need tar; need grep; need sed; need awk
+
+# 1 Version ermitteln → Release-JSON abrufen
+if [[ "$VERSION" == "latest" ]]; then
+  API_URL="https://api.github.com/repos/${REPO}/releases/latest"
+else
+  API_URL="https://api.github.com/repos/${REPO}/releases/tags/v${VERSION}"
+fi
+
+echo "🔍 Hole Release-Info ($API_URL)…"
+JSON=$(curl -sL "$API_URL")
+
+VERSION=$(echo "$JSON" | grep -m1 '"tag_name":' | sed -E 's/.*"v?([^"]+)".*/\1/')
+ASSET_URL=$(echo "$JSON" |
+  grep -Eo '"browser_download_url": *"[^"]+' |
+  cut -d'"' -f4 |
+  grep "${ARCH_OS}\\.tar" | head -n1)
+
+[[ -z "$ASSET_URL" ]] && { echo "❌ passender Asset nicht gefunden"; exit 1; }
+
+ASSET_FILE=$(basename "$ASSET_URL")
+echo "📦 Lade git-cliff v${VERSION} (${ASSET_FILE}) …"
+TMP=$(mktemp -d)
+curl -#L -o "${TMP}/${ASSET_FILE}" "$ASSET_URL"
+
+# 2 Entpacken je nach Endung
+case "$ASSET_FILE" in
+  *.tar.gz|*.tgz) tar -C "$TMP" -xzf "${TMP}/${ASSET_FILE}" ;;
+  *.tar.xz)       tar -C "$TMP" -xJf "${TMP}/${ASSET_FILE}" ;;
+  *.zip)          need unzip; unzip -q "${TMP}/${ASSET_FILE}" -d "$TMP" ;;
+  *) echo "❌ Unbekanntes Archivformat: $ASSET_FILE"; exit 1 ;;
+esac
+
+BIN_PATH=$(find "$TMP" -type f -name git-cliff -perm -u+x | head -n1)
+[[ -z "$BIN_PATH" ]] && { echo "❌ Binary nicht gefunden"; exit 1; }
+
+sudo install -m755 "$BIN_PATH" "${INSTALL_DIR}/git-cliff"
+echo "✅ git-cliff $(git-cliff --version) installiert unter ${INSTALL_DIR}"

scripts/read-cliff-version.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CLIFF_TOML="${1:-cliff.toml}"
+
+if [[ ! -f "$CLIFF_TOML" ]]; then
+  echo "❌ File not found: $CLIFF_TOML" >&2
+  echo "version=" >> "$GITHUB_OUTPUT"
+  exit 0
+fi
+
+VERSION_LINE=$(awk -F '=' '/^# CLIFF_VERSION=/ { gsub(/[" ]/, "", $2); print $2 }' "$CLIFF_TOML" || true)
+
+if [[ -n "$VERSION_LINE" ]]; then
+  echo "✅ Extracted CLIFF_VERSION: $VERSION_LINE"
+else
+  echo "⚠️  No CLIFF_VERSION found in $CLIFF_TOML"
+fi
+
+# Output für GitHub Actions / Composite Action
+echo "version=${VERSION_LINE:-}" >> "$GITHUB_OUTPUT"

scripts/release-from-version.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+VERSION_FILE="VERSION"
+CHANGELOG_FILE="CHANGELOG.md"
+CLIFF_CONFIG="cliff.toml"
+RELEASE_BODY_TMP="$(mktemp)"
+BODY_OUTPUT_VAR="changelog_body_path"
+
+# === Schritt 1: Read version from VERSION ===
+if [[ ! -f "$VERSION_FILE" ]]; then
+  echo "❌ VERSION file not found"
+  exit 1
+fi
+VERSION="$(<"$VERSION_FILE")"
+echo "📦 Version: $VERSION"
+
+# === Schritt 2: Generate changelog for release ===
+echo "📄 Generating changelog for tag v$VERSION"
+git-cliff -c "$CLIFF_CONFIG" -t "v$VERSION" -o "$CHANGELOG_FILE"
+
+ESCAPED_VERSION="$(echo "$VERSION" | sed 's/\./\\./g')"
+
+awk -v ver="$ESCAPED_VERSION" '
+  $0 ~ "^## \\[" ver "\\]" {
+    print_flag=1
+    line = $0
+    sub(/^## /, "", line)
+    sub(/\\s*\\(.*\\)/, "", line)  # entfernt z. B. "(...)" oder "(*)"
+    print line
+    next
+  }
+  $0 ~ "^## \\[" && $0 !~ "^## \\[" ver "\\]" {
+    print_flag=0
+  }
+  print_flag
+' "$CHANGELOG_FILE" > "$RELEASE_BODY_TMP"
+
+# === Schritt 3: Commit updated changelog ===
+git add "$CHANGELOG_FILE"
+if git diff --cached --quiet; then
+  echo "✅ No changes to commit"
+else
+  echo "📝 Committing updated changelog"
+  git commit -m "chore(changelog): update changelog for v$VERSION"
+  git push origin main
+fi
+
+# === Schritt 4: Create tag if not exists ===
+if git rev-parse "v$VERSION" >/dev/null 2>&1; then
+  echo "🔁 Tag v$VERSION already exists, skipping."
+else
+  echo "🏷️  Creating annotated tag v$VERSION"
+  export GIT_AUTHOR_DATE="$(date --iso-8601=seconds)"
+  export GIT_COMMITTER_DATE="$GIT_AUTHOR_DATE"
+  git tag -a "v$VERSION" -F "$RELEASE_BODY_TMP" --cleanup=verbatim
+  git push origin "v$VERSION"
+fi
+
+# === Schritt 5: Create Gitea release ===
+OWNER="$(echo "$GITHUB_REPOSITORY" | cut -d/ -f1)"
+REPO="$(echo "$GITHUB_REPOSITORY" | cut -d/ -f2)"
+TOKEN="${RELEASE_PUBLISH_TOKEN:-$ACTIONS_RUNTIME_TOKEN}"
+
+if [[ -z "${RELEASE_PUBLISH_TOKEN:-}" ]]; then
+  echo "::warning title=Limited Release Propagation::"
+  echo "RELEASE_PUBLISH_TOKEN is not set. Using ACTIONS_RUNTIME_TOKEN instead."
+  echo "⚠️  Release events may not trigger other workflows if created with the runtime token."
+  echo
+fi
+
+# Prüfen, ob Release bereits existiert
+if curl -sf "$GITHUB_API_URL/repos/$OWNER/$REPO/releases/tags/v$VERSION" \
+  -H "Authorization: token $TOKEN" > /dev/null; then
+  echo "🔁 Release for tag v$VERSION already exists, skipping."
+  exit 0
+fi
+
+echo "🚀 Creating Gitea release for v$VERSION"
+
+RELEASE_BODY=$(tail -n +2 "$RELEASE_BODY_TMP" | jq -Rs .)
+
+curl -X POST "$GITHUB_API_URL/repos/$OWNER/$REPO/releases" \
+  -H "Authorization: token $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d @- <<EOF
+{
+  "tag_name": "v$VERSION",
+  "target_commitish": "main",
+  "name": "Release v$VERSION",
+  "body": $RELEASE_BODY,
+  "draft": false,
+  "prerelease": false
+}
+EOF
+
+echo "✅ Release for tag $VERSION created successfully."

scripts/setup-git.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Optional inputs (positionals) oder Fallback auf Umgebungsvariablen
+AUTHOR_NAME="${1:-${CI_COMMIT_AUTHOR_NAME:-CI Bot}}"
+AUTHOR_EMAIL="${2:-${CI_COMMIT_AUTHOR_EMAIL:-ci@example.com}}"
+
+echo "🔧 Setting up git author:"
+echo "   Name : $AUTHOR_NAME"
+echo "   Email: $AUTHOR_EMAIL"
+
+git config --global user.name "$AUTHOR_NAME"
+git config --global user.email "$AUTHOR_EMAIL"