From f69f2580b032e3933a9b3f971c687cd889e176c4 Mon Sep 17 00:00:00 2001
From: Malin <malin@cloudhost.es>
Date: Wed, 12 Aug 2026 13:06:54 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20gitea-release-workflow=20=E2=80=94=20as?=
 =?UTF-8?q?set=20downloads=20work=20via=20public=20host=20substitution?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Confirmed on Gitea 1.27.1 (2026-08-12): browser_download_url in the API
response points at an internal hostname (gitea.barky) but the file
downloads correctly once you swap in the instance's public hostname.
Verified end-to-end with a real binary asset (md5sum match) on a private
repo accessed via token.
---
 skills/gitea-release-workflow/SKILL.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/skills/gitea-release-workflow/SKILL.md b/skills/gitea-release-workflow/SKILL.md
index dc40d17..0a9943e 100644
--- a/skills/gitea-release-workflow/SKILL.md
+++ b/skills/gitea-release-workflow/SKILL.md
@@ -21,6 +21,31 @@ Note: on at least one real self-hosted instance, `/releases/latest` 404s
 for unauthenticated requests even on a public repo — always send the
 token, don't assume public-repo endpoints are auth-free.
 
+## Attaching a binary asset (e.g. a compiled build artifact) to a release
+
+For releases that need to ship a real binary (a compiled `.app`, a zip, an
+installer) rather than just source-tree metadata, upload it as a release
+asset after creating the release:
+
+```bash
+curl -s -X POST -H "Authorization: token $TOKEN" \
+  -F "attachment=@/path/to/file.ext" \
+  "$HOST/api/v1/repos/$OWNER/$REPO/releases/$RELEASE_ID/assets"
+```
+
+The response includes `browser_download_url` — **on this instance
+(confirmed on Gitea 1.27.1, 2026-08-12) it returns an internal address
+(`http://gitea.barky/attachments/<uuid>`) even though the download itself
+works fine once you substitute the public hostname**:
+`https://devops.cloudhost.es/attachments/<uuid>`. This is a narrower,
+now-fixed case of the ROOT_URL gotcha below — as of this instance's current
+state, asset upload/download for **private repos accessed with a token**
+works correctly end-to-end; only the URL string in the API response is
+wrong. Don't assume this generalizes to every repo/instance — verify per
+the "Verify a release actually works end-to-end" section, but know that
+the fix here is a simple hostname swap, not the full archive-endpoint
+workaround.
+
 ## KNOWN GOTCHA: release-asset downloads can be unreachable
 
 **Confirmed live on a real self-hosted Gitea instance**: uploading a zip