gitea-ci-library/git-pages/docs/secrets.md

Secrets — git-pages

Quick Start

Vaihe 1: Secret-arkkitehtuuri

Järjestelmässä on kaksi loogista salaista arvoa. Publish-token jaetaan kahteen K8s-secretiin (Traefik-yhteensopivuus):

Looginen nimi	K8s	Gitea
report_publish_api_token (htpasswd)	git-pages-publish-auth (users)	-
report_publish_api_token (plaintext)	git-pages-publish-token (token)	Actions Secret: GIT_PAGES_PUBLISH_TOKEN
reports_retention_read_token	git-pages-retention-gitea (token)	PAT: CI-REPORTS_READ_FOR_RETENTION

Huomio: Publish-token jaetaan kahteen secretiin, koska Traefik BasicAuth middleware vaatii single-key secretin sekä on muodossa, missä sitä ei saa takaisin. Jokainen repo mikä raportteja käyttää, tarvitsee selväkielisen arvon, joka on "ylimääräisessä" secretissä.

Vaihe 2: Luo Gitea PAT (retention)

Avaa Gitea browserissa:

1. Kirjaudu Gitea-käyttäjällä, jolla on luku kaikkiin raporttirepoihin
2. Settings → Applications → Generate New Token
3. Token name: CI-REPORTS_READ_FOR_RETENTION
4. Scopes: valitse vain read:repository
5. Generate Token → kopioi token heti (näytetään vain kerran)
6. Tallenna token talteen (GITEA_RETENTION_TOKEN)

Vaihe 3: Generoi publish-token

Palaa terminaalille:

GITEA_RETENTION_TOKEN="<from Gitea>"

GIT_PAGES_PUBLISH_TOKEN="$(openssl rand -base64 24)"
echo "Publish-token generoitu. Tallennetaan K8s-secretiin Vaiheessa 4."
echo "$GIT_PAGES_PUBLISH_TOKEN"

Vaihe 4: Luo K8s secrets

NS=git-pages

# 1. Publish-auth: htpasswd (Traefik BasicAuth - vaatii single-key secretin)
kubectl create secret generic git-pages-publish-auth \
  --from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$GIT_PAGES_PUBLISH_TOKEN")" \
  -n "$NS"

# 2. Publish-token: plaintext (luetaan README:stä Giteaan viedessä)
kubectl create secret generic git-pages-publish-token \
  --from-literal=token="$GIT_PAGES_PUBLISH_TOKEN" \
  -n "$NS"

# 3. Retention (käyttää Vaiheessa 2 luotua PAT:ia)
kubectl create secret generic git-pages-retention-gitea \
  --from-literal=token="$GITEA_RETENTION_TOKEN" \
  -n "$NS"

kubectl get secrets -n "$NS"

---

Seuraava: Helm-asennus

Palaa takaisin README.md ja jatka kohdasta "Instanssin values-tiedosto".

---

Secret Arkkitehtuuri

Loogiset salaisuudet

Looginen nimi	K8s	Gitea
report_publish_api_token	git-pages-publish-auth (htpasswd)	Actions Secret: GIT_PAGES_PUBLISH_TOKEN
reports_retention_read_token	git-pages-retention-gitea (token)	PAT: CI-REPORTS_READ_FOR_RETENTION

Secret Reference Architecture

graph TD
    subgraph "Publish Flow"
        P1["Actions Secret<br/>GIT_PAGES_PUBLISH_TOKEN"]
        P2["K8s Secret<br/>git-pages-publish-auth"]
        P1 -->|token| TRAEFIK
        P2 -->|htpasswd| TRAEFIK
        TRAEFIK["Traefik BasicAuth"]
    end

    subgraph "Retention Flow"
        R1["K8s Secret<br/>git-pages-retention-gitea"]
        R2["Gitea PAT<br/>CI-REPORTS_READ_FOR_RETENTION"]
        R1 -->|token| SC["Sidecar"]
        SC -->|API auth| GITEA["Gitea API"]
        SC -->|read branches| GITEA
    end

---

Data Flow

Flow 1: Julkaisu (Publish)

sequenceDiagram
    participant Actions as Gitea Actions
    participant Traefik as Traefik
    participant K8sAuth as K8s Secret<br/>git-pages-publish-auth
    participant K8sToken as K8s Secret<br/>git-pages-publish-token
    participant GP as git-pages

    Note over Actions: 1. Lue plaintext-token
    Actions->>K8sToken: lue token-avain
    K8sToken-->>Actions: plaintext token

    Note over Actions: 2. Lähettää raportin
    Actions->>Traefik: PUT / + BasicAuth<br/>publish:TOKEN + repo-url
    Traefik->>K8sAuth: lue users (htpasswd)
    K8sAuth-->>Traefik: publish:$apr1$...
    alt Token match
        Traefik->>GP: välitä
        GP-->>Traefik: 200 OK
        Traefik-->>Actions: 200 OK
    else Token ei match
        Traefik-->>Actions: 401 Unauthorized
    end

Kaksi secretiä (Traefik-yhteensopivuus):

• git-pages-publish-auth = users (htpasswd, Traefik käyttää)
• git-pages-publish-token = token (plaintext, luetaan Giteaan viedessä)

---

Flow 2: Luku (Read)

sequenceDiagram
    participant Browser as Selain
    participant Traefik as Traefik
    participant GP as git-pages

    Browser->>Traefik: GET /OWNER/REPO/commit/SHA/raportti/index.html
    Traefik->>GP: välitä (ei authia)
    GP-->>Traefik: HTML
    Traefik-->>Browser: HTML

GET/HEAD-reitillä ei ole Middlewarea. Luku on julkinen, jos URL tunnetaan.

---

Flow 3: Retention (Siivous)

sequenceDiagram
    participant Sidecar as Retention Sidecar
    participant K8sSecret as K8s Secret<br/>git-pages-retention-gitea
    participant GiteaAPI as Gitea API
    participant GP as git-pages (localhost:3000)

    Note over Sidecar: 1. Lue PAT
    Sidecar->>K8sSecret: lue token
    K8sSecret-->>Sidecar: Gitea PAT

    Note over Sidecar: 2. Lue manifest
    Sidecar->>GP: GET .git-pages/manifest.json
    GP-->>Sidecar: sisällysluettelo

    Note over Sidecar: 3. Kysy branch
    Sidecar->>GiteaAPI: GET /api/v1/repos/OWNER/REPO/branches/BRANCH
    GiteaAPI-->>Sidecar: 200 / 404

    Note over Sidecar: 4. Luo whiteout-tar + PATCH
    Sidecar->>GP: PATCH / (whiteout)
    GP-->>Sidecar: 200 OK

Huomio: Retention-PAT:in omistajalla on oltava lukuoikeus KAIKKIIN repoihin, joista raportteja on PVC:llä.

---

Troubleshooting

• "secret not found" — luiko secretit ennen Helm-asennusta?
• "401 Unauthorized" — onko Gitea Actions secret oikea?
• "found 2 elements for secret" — Traefik vaatii single-key secretin. Varmista että git-pages-publish-auth sisältää vain users-avaimen.
• "token hukkuu" — generoi uusi token (Vaihe 3) ja päivitä molemmat publish-secretit:

  # 1. Generoi uusi
  GIT_PAGES_PUBLISH_TOKEN="$(openssl rand -base64 24)"
  
  # 2. Päivitä K8s secrets (molemmat)
  NS=git-pages
  kubectl delete secret git-pages-publish-auth -n "$NS"
  kubectl delete secret git-pages-publish-token -n "$NS"
  
  kubectl create secret generic git-pages-publish-auth \
    --from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$GIT_PAGES_PUBLISH_TOKEN")" \
    -n "$NS"
  
  kubectl create secret generic git-pages-publish-token \
    --from-literal=token="$GIT_PAGES_PUBLISH_TOKEN" \
    -n "$NS"
  
  # 3. Päivitä Gitea Actions secret jokaisessa repoissa (luke README:stä)
  

Automatisointi: useamman repon salaisuuden lisääminen

Jos repoja on monta, voit käyttää Gitea API:ta (vaatii admin-tokenin):

ADMIN_TOKEN="<gitea-admin-token>"
NS=git-pages

# Lue plaintext-token erillisestä secretistä
TOKEN=$(kubectl get secret git-pages-publish-token -n "$NS" -o jsonpath='{.data.token}' | base64 -d)

for repo in "owner/repo1" "owner/repo2" "owner/repo3"; do
  curl -X POST "https://gitea.example.com/api/v1/repos/$repo/actions/secrets" \
    -H "Authorization: token $ADMIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"name\":\"GIT_PAGES_PUBLISH_TOKEN\",\"data\":\"$TOKEN\"}"
done

Tai tea CLI:lla (Gitea:n virallinen CLI):

tea actions secrets add --repo owner/repo1 GIT_PAGES_PUBLISH_TOKEN "$TOKEN"
tea actions secrets add --repo owner/repo2 GIT_PAGES_PUBLISH_TOKEN "$TOKEN"