From 9bbe7cb24c7bf8fade6b6844a11bc9482ef66438 Mon Sep 17 00:00:00 2001
From: "dolgolyov.alexei" <dolgolyov.alexei@gmail.com>
Date: Thu, 26 Mar 2026 00:34:17 +0300
Subject: [PATCH] docs: add minimal Gitea release workflow document
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Standalone workflow: push v* tag → create Gitea release with
optional RELEASE_NOTES.md. No builds or artifacts — just the
release entry. Links to full CI/CD guide for extensions.
---
 README.md                 |   6 +-
 gitea-release-workflow.md | 127 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 132 insertions(+), 1 deletion(-)
 create mode 100644 gitea-release-workflow.md

diff --git a/README.md b/README.md
index fe913a2..6462ae4 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Claude Code Facts
 
-> Last updated: 2026-03-25
+> Last updated: 2026-03-26
 
 A collection of interesting and useful facts, tips, tools, and guides for working with Claude and Claude Code.
 
@@ -10,6 +10,10 @@ A collection of interesting and useful facts, tips, tools, and guides for workin
 
 MCP servers, skills, and plugins that extend Claude Code — including Context7 (library docs) and AST Index (fast code search).
 
+### [Gitea Release Workflow (Minimal)](gitea-release-workflow.md)
+
+Minimal Gitea Actions workflow: push a `v*` tag → create a Gitea release with optional `RELEASE_NOTES.md`. No builds, no artifacts — just a release entry.
+
 ### [CI/CD for Python Apps on Gitea](gitea-python-ci-cd.md)
 
 Reusable reference for building CI pipelines, release automation, and installer packaging for Python apps on Gitea — covering lint/test workflows, cross-compiled Windows builds (embedded Python + NSIS), Linux tarballs, Docker images, and Gitea REST API release management.
diff --git a/gitea-release-workflow.md b/gitea-release-workflow.md
new file mode 100644
index 0000000..d219da8
--- /dev/null
+++ b/gitea-release-workflow.md
@@ -0,0 +1,127 @@
+# Gitea Release Workflow (Minimal)
+
+Minimal Gitea Actions workflow: push a `v*` tag → create a Gitea release with optional release notes from `RELEASE_NOTES.md`.
+
+No build jobs, no artifacts, no Docker — just a release entry on the Gitea Releases page.
+
+For the full CI/CD pipeline (builds, installers, Docker), see [gitea-python-ci-cd.md](gitea-python-ci-cd.md).
+
+## Complete Workflow
+
+`.gitea/workflows/release.yml`:
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch RELEASE_NOTES.md only
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: RELEASE_NOTES.md
+          sparse-checkout-cone-mode: false
+
+      - name: Create Gitea release
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: |
+          TAG="${{ gitea.ref_name }}"
+          VERSION="${TAG#v}"
+          BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          # Detect pre-release (alpha/beta/rc)
+          IS_PRE="false"
+          if echo "$TAG" | grep -qE '(alpha|beta|rc)'; then
+            IS_PRE="true"
+          fi
+
+          # Read release notes if present
+          if [ -f RELEASE_NOTES.md ]; then
+            export RELEASE_NOTES=$(cat RELEASE_NOTES.md)
+            echo "Found RELEASE_NOTES.md"
+          else
+            export RELEASE_NOTES=""
+            echo "No RELEASE_NOTES.md found — release will have no body"
+          fi
+
+          BODY_JSON=$(python3 -c "
+          import json, os
+          notes = os.environ.get('RELEASE_NOTES', '')
+          print(json.dumps(notes.strip()))
+          ")
+
+          # Create release via Gitea API
+          RELEASE=$(curl -s -X POST "$BASE_URL/releases" \
+            -H "Authorization: token $DEPLOY_TOKEN" \
+            -H "Content-Type: application/json" \
+            -d "{
+              \"tag_name\": \"$TAG\",
+              \"name\": \"$VERSION\",
+              \"body\": $BODY_JSON,
+              \"draft\": false,
+              \"prerelease\": $IS_PRE
+            }")
+
+          # Fallback: if release already exists for this tag, reuse it
+          RELEASE_ID=$(echo "$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])" 2>/dev/null)
+          if [ -z "$RELEASE_ID" ]; then
+            echo "::warning::Release already exists for tag $TAG — reusing existing release"
+            RELEASE=$(curl -s "$BASE_URL/releases/tags/$TAG" \
+              -H "Authorization: token $DEPLOY_TOKEN")
+            RELEASE_ID=$(echo "$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+          fi
+          echo "Created release $RELEASE_ID for $TAG"
+```
+
+## Setup
+
+1. **Create a Gitea token** with `write:repository` permission
+2. **Add secret** in repo Settings → Secrets: `DEPLOY_TOKEN` = your token
+3. **Tag and push:**
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+## Release Notes (Optional)
+
+To include release notes, create `RELEASE_NOTES.md` in the repo root before tagging:
+
+```markdown
+### What's New
+
+- Added feature X
+- Fixed bug Y
+```
+
+If the file is absent, the release is created with an empty body — useful for quick pre-releases.
+
+> **Why sparse-checkout?** The workflow only needs one file. Sparse-checkout skips downloading the full repo, making the step faster — especially in large repos.
+
+## Pre-releases
+
+Tags containing `alpha`, `beta`, or `rc` are automatically marked as pre-release:
+
+| Tag | Pre-release? |
+|-----|-------------|
+| `v1.0.0` | No |
+| `v1.0.0-alpha.1` | Yes |
+| `v1.0.0-beta.2` | Yes |
+| `v1.0.0-rc.1` | Yes |
+
+## Extending
+
+This workflow is intentionally minimal. Common additions:
+
+- **Build artifacts** — add parallel jobs that upload assets to the release (see [gitea-python-ci-cd.md](gitea-python-ci-cd.md))
+- **Docker push** — build and push images after tagging
+- **Portainer webhook** — auto-redeploy after docker push
+- **Changelog generation** — auto-generate from git log between tags