init: git-pages init job, ADR 0004, docs, remove PUT fallback

- ADR 0004: commit-status-periaate (API vain tarvittaessa, natiivi riittää)
- git-pages/docs/implementation-notes.md: tekniset huomiot
- init-job.yaml: post-install hook luo placeholderin (.index olemassa)
- values.yaml: initJob.enabled default
- publish-git-pages.sh: poistettu PUT-fallback (init job hoitaa)
- README: maininta automaattisesta initistä

docs/decisions/0004-commit-status.md

@@ -0,0 +1,25 @@
+# 4. Commit-statusviestit — periaate
+
+## Päätös
+
+Gitea Actions näyttää jobien tilan (checkmark, risti, spinner) commit-näkymässä
+**automaattisesti**. Tämä on ensisijainen tapa, eikä sitä korvata.
+
+Commit-status API:a (`/api/v1/repos/{owner}/{repo}/statuses/{sha}`) käytetään
+**vain** kun natiivi toiminta ei riitä — ensisijaisesti custom-raporttilinkin
+välittämiseen commit-näkymään.
+
+## Periaatteet
+
+1. Gitea Actionsin automaattinen commit-status on ensisijainen.
+2. API:a kutsutaan vain tarpeeseen: linkki ulkoiseen raporttiin.
+3. Jokainen API-kutsussa käytettävä `context`-avain on uniikki.
+4. State-arvojen on oltava Gitea API:n valideja (`success`, `failure`,
+   `pending`, `error`, `warning`).
+
+## Tausta
+
+Jenkins-versiossa jokainen build-vaihe raportoi APIin, koska Jenkins ei
+tarjonnut natiivia commit-statusnäkymää. Gitea Actionsissa tämä tulee
+automaattisesti — sama tieto kahdesta paikasta aiheuttaa melua eikä lisää
+arvoa.

git-pages/README.md

@@ -36,6 +36,11 @@ helm upgrade --install git-pages ./git-pages \
   -f "$VALUES"
 ```
 
+Helm ajaa asennuksen jälkeen init-jobin, joka PUTtaa paikanpitäjäsivun
+git-pagesiin. Tämä luo tarvittavan `.index`-tiedoston — sen jälkeen
+Gitea Actions -scriptit voivat käyttää suoraan PATCHia ilman
+PUT-fallbackia.
+
 ---
 
 ## Vie publish-token Gitea Actions-secretiin (per repo)

git-pages/docs/implementation-notes.md

@@ -0,0 +1,43 @@
+# Implementation Notes
+
+Teknisiä huomioita git-pages 0.9.1:n käyttäytymisestä, joita ei ole ilmeistä
+dokumentaatiosta.
+
+## Storage v2 (Protobuf manifest)
+
+Git-pages 0.9.1 käyttää v2-arkkitehtuuria. Kaikki sisältö on pakattu
+Protobuf-manifestiin (`site/{host}/.index`), ei flat-FS:nä. Tästä seuraa:
+
+- Tiedostoja ei voi etsiä tai poistaa `find`/`rm`-komennoilla
+- `.git-pages/manifest.json` listaa kaikki tiedostot (ProtoJSON)
+- `.git-pages/archive.tar` antaa koko sisällön (saattaa truncata HTTP/2:ssa)
+
+## Host-header
+
+Git-pages valitsee sivuston Host-headerin perusteella. Ilman oikeaa Hostia
+palauttaa 404.
+
+- Ulkoiset requestit: Traefik välittää alkuperäisen Hostin automaattisesti
+- Sidecar/localhost: `-H "Host: ci-reports.helm-dev.keskikuja.site"`
+
+## PATCH ja directory-entryt
+
+Jos PATCH-tar sisältää directory-entryn (tyyppi directory, tar typeflag '5'),
+se **korvaa** koko hakemiston dokumentaation mukaan. Tar saa sisältää vain
+file- ja symlink-entryjä, jotta PATCH toimii odotetusti.
+
+## Whiteout — tiedostojen poisto
+
+Ainoa tapa poistaa tiedostoja ilman koko sivuston PUT-korvausta:
+
+- Tarissa character device entry (`CHRTYPE`, tar typeflag '4')
+- `devmajor=0`, `devminor=0`
+- PATCH:ataan sivuston juureen
+
+## .init — ensimmäinen julkaisu
+
+Ensimmäinen julkaisu vaatii PUTin, joka luo `.index`-tiedoston. Tämän jälkeen
+PATCH riittää.
+
+Helm-chartin post-install -job hoitaa tämän automaattisesti:
+consumerien publish-scriptien ei tarvitse tuntea asennuksen tilaa.

git-pages/templates/init-job.yaml

@@ -0,0 +1,48 @@
+{{- if .Values.initJob.enabled }}
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: {{ include "git-pages.fullname" . }}-init
+  labels:
+    {{- include "git-pages.componentLabels" . | nindent 4 }}
+  annotations:
+    "helm.sh/hook": post-install, post-upgrade
+    "helm.sh/hook-delete-policy": hook-succeeded,before-hook-creation
+spec:
+  backoffLimit: 5
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: {{ include "git-pages.name" . }}-init
+        app.kubernetes.io/instance: {{ .Release.Name }}
+    spec:
+      restartPolicy: Never
+      containers:
+        - name: init
+          image: "{{ .Values.initJob.image.repository }}:{{ .Values.initJob.image.tag }}"
+          imagePullPolicy: {{ .Values.initJob.image.pullPolicy }}
+          command:
+            - bash
+            - -c
+            - |
+              set -euo pipefail
+              apt-get update -qq && apt-get install -y -qq curl tar >/dev/null
+              echo "Init: waiting for git-pages..."
+              until curl -sf \
+                -H "Host: {{ .Values.ingress.host }}" \
+                -o /dev/null "http://git-pages:3000/.git-pages/health"
+              do sleep 2; done
+              echo "Init: creating placeholder site..."
+              WORK=$(mktemp -d)
+              mkdir -p "$WORK/__init__"
+              echo "initialized" > "$WORK/__init__/index.html"
+              tar cf /tmp/init.tar -C "$WORK" __init__
+              curl -sf -X PUT "http://git-pages:3000/" \
+                -H "Host: {{ .Values.ingress.host }}" \
+                -H "Content-Type: application/x-tar" \
+                --data-binary @/tmp/init.tar -o /dev/null
+              echo "Init: done"
+          env:
+            - name: PAGES_INSECURE
+              value: "1"
+{{- end }}

git-pages/values.yaml

@@ -37,6 +37,15 @@ ingress:
 certificate:
   enabled: true
 
+# Post-install init job: creates placeholder site so .index exists.
+# Consumers can use PATCH directly without PUT fallback.
+initJob:
+  enabled: true
+  image:
+    repository: debian
+    tag: bookworm-slim
+    pullPolicy: IfNotPresent
+
 # Optional Helm-managed secret — prefer manual create (see docs/secrets.md).
 publishAuth:
   create: false

scripts/publish-git-pages.sh

@@ -50,15 +50,6 @@ publish() {
 
 HTTP_CODE=$(publish PATCH)
 
-if [ "$HTTP_CODE" = "503" ]; then
-  HTTP_CODE=$(curl -sS -X PUT "$PUBLISH_SITE_URL" \
-    -u "${GIT_PAGES_PUBLISH_USER}:${GIT_PAGES_PUBLISH_TOKEN}" \
-    -H "Content-Type: application/x-tar" \
-    --data-binary @"$TAR" \
-    -o /tmp/git-pages-publish-response.txt \
-    -w "%{http_code}")
-fi
-
 case "$HTTP_CODE" in
   200|201|204) ;;
   *)