From f17ff30c1195ad7e9df083a02d9e6f697f2e9b75 Mon Sep 17 00:00:00 2001
From: "dolgolyov.alexei" <dolgolyov.alexei@gmail.com>
Date: Mon, 23 Mar 2026 02:47:57 +0300
Subject: [PATCH] docs: add release fallback logic and troubleshooting section

Add ::warning:: annotation and fallback to fetch existing release
when tag already has a release. Add troubleshooting section for
re-triggering failed release workflows. Fix markdown lint warnings.
---
 gitea-python-ci-cd.md | 40 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/gitea-python-ci-cd.md b/gitea-python-ci-cd.md
index 5a39934..07d47d8 100644
--- a/gitea-python-ci-cd.md
+++ b/gitea-python-ci-cd.md
@@ -12,7 +12,7 @@ A reusable reference for building CI pipelines, release automation, and installe
 
 Two workflows, triggered by different events:
 
-```
+```text
 push/PR to master  ──►  test.yml   (lint + test)
 push tag v*        ──►  release.yml (build + release + Docker)
 ```
@@ -127,7 +127,14 @@ create-release:
             \"prerelease\": \$IS_PRE
           }")
 
-        RELEASE_ID=$(echo "\$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+        # Fallback: if release already exists for this tag, fetch it instead
+        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 \$GITEA_TOKEN")
+          RELEASE_ID=$(echo "\$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+        fi
         echo "release_id=\$RELEASE_ID" >> "\$GITHUB_OUTPUT"
 ```
 
@@ -409,7 +416,7 @@ CMD ["uvicorn", "your_package.main:app", "--host", "0.0.0.0", "--port", "8080"]
 ## 8. Release Versioning
 
 | Tag format | Example | Pre-release? | Docker `:latest`? |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | `v{major}.{minor}.{patch}` | `v0.2.0` | No | Yes |
 | `v{major}.{minor}.{patch}-alpha.{n}` | `v0.2.0-alpha.1` | Yes | No |
 | `v{major}.{minor}.{patch}-beta.{n}` | `v0.2.0-beta.2` | Yes | No |
@@ -430,7 +437,7 @@ git push origin v0.2.0-alpha.1
 ## 9. Gitea vs GitHub Actions Differences
 
 | Feature | GitHub Actions | Gitea Actions |
-|---|---|---|
+| --- | --- | --- |
 | Context prefix | `github.*` | `gitea.*` |
 | Ref name | `${{ github.ref_name }}` | `${{ gitea.ref_name }}` |
 | Server URL | `${{ github.server_url }}` | `${{ gitea.server_url }}` |
@@ -453,3 +460,28 @@ git push origin v0.2.0-alpha.1
 - [ ] Create `Dockerfile` for Docker builds (optional)
 - [ ] Configure `pyproject.toml` with `[tool.ruff]` and `[tool.pytest]`
 - [ ] Set up `.pre-commit-config.yaml` with ruff + black
+
+## 11. Troubleshooting
+
+### Release already exists for tag
+
+If the `create-release` job fails with `KeyError: 'id'`, the Gitea API returned an error
+because a release already exists for that tag (e.g., from a previous failed run).
+
+**Prevention:** The fallback logic in section 2.1 handles this automatically — if creation
+fails, it fetches the existing release by tag and reuses its ID. A `::warning::` annotation
+is emitted in the workflow log.
+
+**Re-triggering a failed release workflow:**
+
+```bash
+# Option A: Delete and re-push the same tag
+git push origin :refs/tags/v0.1.0-alpha.2   # delete remote tag
+# Delete the release in Gitea UI or via API
+git tag -f v0.1.0-alpha.2                    # recreate local tag
+git push origin v0.1.0-alpha.2               # push again
+
+# Option B: Just bump the version (simpler)
+git tag v0.1.0-alpha.3
+git push origin v0.1.0-alpha.3
+```