From 0e26d99228c4d6354536c63e02b01e9135d35f65 Mon Sep 17 00:00:00 2001
From: unkin-agent <unkin-agent@unkin.net>
Date: Wed, 12 Aug 2026 20:53:23 +1000
Subject: [PATCH] ui: add alpine local and github_alpine usage instructions
 (#116)

## Why
The alpine local repo (a real apk repo with auto-generated per-arch APKINDEX) and the new github_alpine remote (metadata-only apk index synthesized from a GitHub repo's release .apk assets) shipped without any "How do I use this?" UI guidance, unlike deb/github_deb. This adds the matching client instructions so users can consume and publish to these repos.

## How
- Extend `case 'alpine':` in `UsageInstructions.tsx` to branch on `isLocal` (mirroring rpm/deb):
  - LOCAL: "Add the apk repo" snippet appends `${url}/api/v1/local/<name>` to `/etc/apk/repositories` with `apk update/add --allow-untrusted` (served unsigned, parity with rpm gpgcheck=0), plus a "Publish a .apk" snippet uploading to the canonical `<arch>/<name>-<version>.apk` path (APKINDEX carries no filename, so path must match or install 404s).
  - REMOTE: existing caching-proxy snippet kept unchanged.
- Add `case 'github_alpine':` (always remote-class): "Add the apk repo (metadata-only, from GitHub releases)" snippet with `--allow-untrusted`; note explains the per-arch APKINDEX is synthesized from release .apk assets and downloads redirect to the backing releases remote.
- No other cases touched. `npm run build` (tsc typecheck + vite) passes; pre-commit passes.

Reviewed-on: https://git.unkin.net/unkin/artifactapi/pulls/116
Co-authored-by: unkin-agent <unkin-agent@unkin.net>
Co-committed-by: unkin-agent <unkin-agent@unkin.net>
---
 ui/src/components/UsageInstructions.tsx | 42 +++++++++++++++++++++----
 1 file changed, 36 insertions(+), 6 deletions(-)

diff --git a/ui/src/components/UsageInstructions.tsx b/ui/src/components/UsageInstructions.tsx
index 1791ced..f6ac0bd 100644
--- a/ui/src/components/UsageInstructions.tsx
+++ b/ui/src/components/UsageInstructions.tsx
@@ -176,14 +176,44 @@ helm install <release> ${name}/<chart>`,
       ];
 
     case 'alpine':
-      return [
-        {
-          title: 'Add the APK repository',
-          language: 'bash',
-          code: `echo '${proxy}/' | sudo tee -a /etc/apk/repositories
+      return isLocal
+        ? [
+            {
+              title: 'Add the apk repo (real apk repo, APKINDEX auto-generated)',
+              language: 'bash',
+              code: `echo '${url}/api/v1/local/${name}' | sudo tee -a /etc/apk/repositories
+sudo apk update --allow-untrusted
+sudo apk add --allow-untrusted <package>`,
+              note: `Served unsigned (parity with the rpm repo's gpgcheck=0) — use --allow-untrusted, or install a signing key. apk fetches <arch>/APKINDEX.tar.gz under this base.`,
+            },
+            {
+              title: 'Publish a .apk (index regenerates automatically)',
+              language: 'bash',
+              code: `curl -fsSL --upload-file ./mypkg-1.0-r0.apk \\
+  ${url}/api/v2/remotes/${name}/files/x86_64/mypkg-1.0-r0.apk`,
+              note: 'Upload each package at <arch>/<name>-<version>.apk — apk reconstructs that exact path from the index (APKINDEX carries no filename), so a mismatched path will 404 on install.',
+            },
+          ]
+        : [
+            {
+              title: 'Add the APK repository',
+              language: 'bash',
+              code: `echo '${proxy}/' | sudo tee -a /etc/apk/repositories
 sudo apk update
 sudo apk add <package>`,
-          note: 'If the index is unsigned over the proxy, add --allow-untrusted or install the signing key into /etc/apk/keys.',
+              note: 'If the index is unsigned over the proxy, add --allow-untrusted or install the signing key into /etc/apk/keys.',
+            },
+          ];
+
+    case 'github_alpine':
+      return [
+        {
+          title: 'Add the apk repo (metadata-only, from GitHub releases)',
+          language: 'bash',
+          code: `echo '${proxy}' | sudo tee -a /etc/apk/repositories
+sudo apk update --allow-untrusted
+sudo apk add --allow-untrusted <package>`,
+          note: "The per-arch APKINDEX is synthesized from the configured GitHub repo's release .apk assets; package downloads are redirected to the backing releases remote. Served unsigned, so --allow-untrusted.",
         },
       ];