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:**

```bash
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

```bash
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](../README.md#käyttöönotto) 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

```mermaid
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)

```mermaid
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)

```mermaid
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)

```mermaid
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:
  ```bash
  # 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):

```bash
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):

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