Document Gitea package publishing pitfalls

README.md

@@ -224,6 +224,17 @@ Authorization: token GITEA_TOKEN
 
 After pushing commits that trigger a Gitea workflow, Codex agents must keep checking the resulting workflow run before finishing. Poll the run until it reaches a terminal state. If it succeeds, report the successful run. If it fails or is cancelled, inspect the failing job/logs, fix the issue when it is in scope, commit, push, and repeat the check loop for the next run. A fixed failure is not a stopping point; the loop continues after the follow-up push until a workflow succeeds or a concrete out-of-scope blocker is reached. Do not stop after a single in-progress status when the user asked the agent to continue the loop.
 
+## Gitea Artifacts And Packages
+
+Actions artifacts and Gitea packages are separate storage paths.
+
+- `actions/upload-artifact` makes a workflow-run artifact. It does not create an entry in the Gitea Package Registry.
+- Use `actions/upload-artifact@v3` for Gitea/Act compatibility unless the target runner is known to support newer artifact actions.
+- To publish a downloadable package, upload it separately to the generic package registry with `curl --upload-file` and a CI secret such as `REGISTRY_TOKEN`.
+- Do not place raw build artifact names directly into package URLs. Build tools often emit names with spaces, parentheses, or platform-specific punctuation. Copy artifacts to temporary package files with URL-safe names before uploading.
+- For user-facing downloads, publish both an immutable version such as `PROJECT_VERSION-SHORT_SHA` and a stable `latest` package when the repository owner wants a moving download link.
+- After publishing, verify the actual package URL with an authenticated `HEAD` or lightweight download check. A green build does not always prove the package is visible where users expect it.
+
 <p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
 
 ## Agent Prompt For A New Repo

agent-quickstart.md

@@ -109,6 +109,14 @@ Did release behavior, artifacts, or downloads change?
   yes -> update docs/release-checklist.md and README downloads/artifacts
   no  -> do not invent release details
 
+Does the user expect a Gitea Package Registry package?
+  yes -> add an explicit generic package upload step; upload-artifact alone is not enough
+  no  -> workflow-run artifacts may be sufficient
+
+Do package upload URLs include raw build filenames?
+  yes -> copy artifacts to URL-safe filenames first, then upload those names
+  no  -> continue
+
 Is the work interrupted, risky, or multi-session?
   yes -> update docs/agent-handoff.md
   no  -> no handoff file is required

existing-project.md

@@ -114,6 +114,8 @@ If CI already exists:
 - keep existing artifact names unless they are broken,
 - avoid changing deployment behavior.
 
+Treat workflow-run artifacts and Package Registry packages as different outputs. If the project expects user-downloadable packages, confirm there is an explicit package publish step in addition to any `actions/upload-artifact` step. When adding or repairing package publishing, copy build outputs to URL-safe filenames before uploading and verify the final package URL after the workflow succeeds.
+
 If CI does not exist:
 
 - add `.gitea/workflows/build.yml` from the template,

files/AGENTS.md

@@ -25,6 +25,7 @@ PROJECT_NAME: PROJECT_DESCRIPTION
 - Add or preserve `.gitea/workflows/dependency-check.yml`, `.gitea/workflows/release-dry-run.yml`, and `.gitea/workflows/template-compliance.yml` when the repository is active, releasable, or intended as a Codex-maintained project.
 - Repository cleanup automation must be non-destructive. Do not delete branches, packages, releases, or tracked files without explicit user approval.
 - Dependency, compliance, and release dry-run automation must report findings only. Do not auto-update dependencies, auto-open PRs, create tags, publish packages, or create releases without explicit user approval.
+- Gitea Actions artifacts are not Gitea Package Registry packages. If the user expects a package/download entry, add an explicit registry publish step and verify the package URL after the workflow succeeds.
 
 ## Commands
 
@@ -66,6 +67,7 @@ ARTIFACT_NAME
 - Keep external network calls documented.
 - Prefer local processing for user data.
 - Keep CI publishing secrets in repository or organization secrets, not in tracked files. `REGISTRY_TOKEN` is the default package publishing secret name for the Gitea workflow template.
+- Use URL-safe package filenames when publishing to a registry. Do not put raw artifact names with spaces or punctuation directly into upload URLs.
 - Ensure `.gitignore` covers local config, build outputs, logs, temporary files, and secret material for the detected stack.
 
 ## Finish Checklist

files/build-gitea.yml

@@ -53,26 +53,53 @@ jobs:
         run: |
           app_version="PROJECT_VERSION"
           package_version="${app_version}-${GITHUB_SHA::7}"
+          package_name="PACKAGE_NAME"
+          package_dir="package-registry"
           latest_url="https://git.wilkensxl.de/api/packages/REPOSITORY_OWNER/generic/PACKAGE_NAME/latest"
 
-          for artifact in ARTIFACT_OUTPUT_DIRECTORY/*; do
+          mapfile -d '' artifacts < <(find ARTIFACT_OUTPUT_DIRECTORY -maxdepth 1 -type f -print0)
-            [ -f "$artifact" ] || continue
+          if [ "${#artifacts[@]}" -eq 0 ]; then
-            file_name="$(basename "$artifact")"
+            echo "No package artifacts found in ARTIFACT_OUTPUT_DIRECTORY"
+            exit 1
+          fi
+
+          rm -rf "${package_dir}"
+          mkdir -p "${package_dir}/versioned" "${package_dir}/latest"
+
+          for artifact in "${artifacts[@]}"; do
+            extension=""
+            base_name="$(basename "$artifact")"
+            stem="$base_name"
+            if [[ "$base_name" == *.* ]]; then
+              extension=".${base_name##*.}"
+              stem="${base_name%.*}"
+            fi
+            safe_stem="$(echo "$stem" | tr -cs 'A-Za-z0-9._-' '-' | sed 's/^-//; s/-$//')"
+            safe_name="${safe_stem}-${package_version}${extension}"
+            cp "$artifact" "${package_dir}/versioned/${safe_name}"
 
             curl --fail-with-body \
               --user "REPOSITORY_OWNER:${REGISTRY_TOKEN}" \
-              --upload-file "$artifact" \
+              --upload-file "${package_dir}/versioned/${safe_name}" \
-              "https://git.wilkensxl.de/api/packages/REPOSITORY_OWNER/generic/PACKAGE_NAME/${package_version}/${file_name}"
+              "https://git.wilkensxl.de/api/packages/REPOSITORY_OWNER/generic/PACKAGE_NAME/${package_version}/${safe_name}"
           done
 
           curl --silent --show-error --user "REPOSITORY_OWNER:${REGISTRY_TOKEN}" --request DELETE "${latest_url}" || true
 
-          for artifact in ARTIFACT_OUTPUT_DIRECTORY/*; do
+          for artifact in "${artifacts[@]}"; do
-            [ -f "$artifact" ] || continue
+            extension=""
-            file_name="$(basename "$artifact")"
+            base_name="$(basename "$artifact")"
+            stem="$base_name"
+            if [[ "$base_name" == *.* ]]; then
+              extension=".${base_name##*.}"
+              stem="${base_name%.*}"
+            fi
+            safe_stem="$(echo "$stem" | tr -cs 'A-Za-z0-9._-' '-' | sed 's/^-//; s/-$//')"
+            safe_name="${safe_stem}-latest${extension}"
+            cp "$artifact" "${package_dir}/latest/${safe_name}"
 
             curl --fail-with-body \
               --user "REPOSITORY_OWNER:${REGISTRY_TOKEN}" \
-              --upload-file "$artifact" \
+              --upload-file "${package_dir}/latest/${safe_name}" \
-              "${latest_url}/${file_name}"
+              "${latest_url}/${safe_name}"
           done

new-repository.md

@@ -159,7 +159,7 @@ build
 upload artifacts
 ```
 
-Only publish artifacts to a package registry when the artifact names and credentials are known.
+Only publish artifacts to a package registry when the artifact names and credentials are known. `actions/upload-artifact` creates a workflow-run artifact, not a Gitea Package Registry package. If users need a package/download entry, add a separate generic package upload step with `REGISTRY_TOKEN`, copy artifacts to URL-safe filenames before upload, and verify the final package URL after the workflow succeeds.
 
 For releasable projects, config tools, apps, or repositories that process user data, secrets, or deployment files, also add `.gitea/workflows/security-scan.yml`. Keep the scheduled workflow conservative and review false positives before silencing checks.