From b841496717b2acec7bde4d47d666efd93e80a8ea Mon Sep 17 00:00:00 2001 From: moilanik Date: Fri, 12 Jun 2026 08:10:37 +0300 Subject: [PATCH] init: git-pages init job, ADR 0004, docs, remove PUT fallback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 | 25 ++++++++++++++ git-pages/README.md | 5 +++ git-pages/docs/implementation-notes.md | 43 +++++++++++++++++++++++ git-pages/templates/init-job.yaml | 48 ++++++++++++++++++++++++++ git-pages/values.yaml | 9 +++++ scripts/publish-git-pages.sh | 9 ----- 6 files changed, 130 insertions(+), 9 deletions(-) create mode 100644 docs/decisions/0004-commit-status.md create mode 100644 git-pages/docs/implementation-notes.md create mode 100644 git-pages/templates/init-job.yaml diff --git a/docs/decisions/0004-commit-status.md b/docs/decisions/0004-commit-status.md new file mode 100644 index 0000000..8084eb3 --- /dev/null +++ b/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. diff --git a/git-pages/README.md b/git-pages/README.md index 70b8714..9b47223 100644 --- a/git-pages/README.md +++ b/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) diff --git a/git-pages/docs/implementation-notes.md b/git-pages/docs/implementation-notes.md new file mode 100644 index 0000000..c980080 --- /dev/null +++ b/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. diff --git a/git-pages/templates/init-job.yaml b/git-pages/templates/init-job.yaml new file mode 100644 index 0000000..ef6403b --- /dev/null +++ b/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 }} diff --git a/git-pages/values.yaml b/git-pages/values.yaml index 0187f1b..29f4ede 100644 --- a/git-pages/values.yaml +++ b/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 diff --git a/scripts/publish-git-pages.sh b/scripts/publish-git-pages.sh index 2e3fca3..e6c3456 100755 --- a/scripts/publish-git-pages.sh +++ b/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) ;; *)