# Secrets — gitea-reports

## 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) | `gitea-reports-publish-auth` (users) | - |
| `report_publish_api_token` (plaintext) | `gitea-reports-publish-token` (token) | Actions Secret: `REPORTS_PUBLISH_TOKEN` |
| `reports_retention_read_token` | `gitea-reports-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>"

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

### Vaihe 4: Luo K8s secrets

```bash
NS=gitea-reports

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

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

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

kubectl get secrets -n "$NS"
```

---

### Vaihe 5: Vie publish-token Gitea Actions-secretiin

Token näkyy terminaalissa Vaiheen 3 `echo`sta. Jos se on jo kadonnut näkyvistä, hae se K8s-secretistä:

```bash
NS=gitea-reports
kubectl get secret gitea-reports-publish-token -n "$NS" -o jsonpath='{.data.token}' | base64 -d; echo
```

Vie kopioitu secret Gitea Actions Secrets:

Kannattaa viedä tämä token ORG tason secretiksi Gitea Actions. Muuten joudut tekemään tämän jokaiselle rapositorylle erikseen.

Luo `REPORTS_PUBLISH_TOKEN` secret, ja terminaalista kopioitu arvo `values` kenttään. 

Description voi olla esim: 
> Julkaisuun liittyvä salaisuus, jonka gitea-pages auth tarkistaa, että saako julkaista raporttia.


**Gitea UI:ssa:** New Secret → Name: `REPORTS_PUBLISH_TOKEN` → Value: **liitä token** → Save

Toista jokaiselle repolle, joka julkaisee raportteja.

---

### 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` | `gitea-reports-publish-auth` (htpasswd) | Actions Secret: `REPORTS_PUBLISH_TOKEN` |
| `reports_retention_read_token` | `gitea-reports-retention-gitea` (token) | PAT: `CI-REPORTS_READ_FOR_RETENTION` |

### Secret Reference Architecture

```mermaid
graph TD
    subgraph "Publish Flow"
        P1["Actions Secret<br/>REPORTS_PUBLISH_TOKEN"]
        P2["K8s Secret<br/>gitea-reports-publish-auth"]
        P1 -->|token| TRAEFIK
        P2 -->|htpasswd| TRAEFIK
        TRAEFIK["Traefik BasicAuth"]
    end

    subgraph "Retention Flow"
        R1["K8s Secret<br/>gitea-reports-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/>gitea-reports-publish-auth
    participant K8sToken as K8s Secret<br/>gitea-reports-publish-token
    participant Upload as upload-sidecar
    participant PV as PVC /app/data

    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 /{polku} + BasicAuth<br/>publish:TOKEN + tar.gz
    Traefik->>K8sAuth: lue users (htpasswd)
    K8sAuth-->>Traefik: publish:$apr1$...
    alt Token match
        Traefik->>Upload: PUT /{path}
        Upload->>PV: extract tar.gz
        PV-->>Upload: 201 Created
        Upload-->>Traefik: 201 Created
        Traefik-->>Actions: 201 Created
    else Token ei match
        Traefik-->>Actions: 401 Unauthorized
    end
```

**Kaksi secretiä (Traefik-yhteensopivuus):**
- `gitea-reports-publish-auth` = `users` (htpasswd, Traefik käyttää)
- `gitea-reports-publish-token` = `token` (plaintext, luetaan Giteaan viedessä)

---

### Flow 2: Luku (Read)

```mermaid
sequenceDiagram
    participant Browser as Selain
    participant Traefik as Traefik
    participant Nginx as nginx
    participant PV as PVC /app/data

    Browser->>Traefik: GET /OWNER/REPO/branch/SHA/suite/index.html
    Traefik->>Nginx: välitä (ei authia)
    Nginx->>PV: lue tiedosto
    PV-->>Nginx: HTML
    Nginx-->>Traefik: HTML
    Traefik-->>Browser: HTML
```

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

---

### Flow 3: Retention (Siivous)

```mermaid
sequenceDiagram
    participant CronJob as Retention CronJob
    participant K8sSecret as K8s Secret<br/>gitea-reports-retention-gitea
    participant GiteaAPI as Gitea API
    participant PV as PVC /app/data

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

    Note over CronJob: 2. Lue PV suoraan
    CronJob->>PV: ls /app/data/{owner}/{repo}/{branch}/
    PV-->>CronJob: commit-kansiot

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

    Note over CronJob: 4. Poista vanhat
    CronJob->>PV: rm -rf vanhat commit-kansiot
```

**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ä `gitea-reports-publish-auth` sisältää vain `users`-avaimen.
- **"token hukkuu"** — generoi uusi token (Vaihe 3) ja päivitä molemmat publish-secretit:
  ```bash
  # 1. Generoi uusi
  REPORTS_PUBLISH_TOKEN="$(openssl rand -base64 24)"

  # 2. Päivitä K8s secrets (molemmat)
  NS=gitea-reports
  kubectl delete secret gitea-reports-publish-auth -n "$NS"
  kubectl delete secret gitea-reports-publish-token -n "$NS"
  
  kubectl create secret generic gitea-reports-publish-auth \
    --from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$REPORTS_PUBLISH_TOKEN")" \
    -n "$NS"
  
  kubectl create secret generic gitea-reports-publish-token \
    --from-literal=token="$REPORTS_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=gitea-reports

# Lue plaintext-token erillisestä secretistä
TOKEN=$(kubectl get secret gitea-reports-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\":\"REPORTS_PUBLISH_TOKEN\",\"data\":\"$TOKEN\"}"
done
```

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

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