gitea-ci-library/README.md

# Gitea Actions CI -kirjasto

Reusable workflow -kirjasto Gitea Actionsille. Lisätietoja: [docs/](docs/)

**Consumer-käyttöönotto:** [docs/consumer-guide.md](docs/consumer-guide.md) — vaiheittainen ohje uuden projektin liittämiseen

## Provider-binding — miten consumer löytää providerin

Consumer kutsuu provideria `uses:`-viittauksella. Ei discoveryä — polku kovakoodataan consumerin
`ci.yml`:ään. Gitea hakee workflow YAML:n **samalta Gitea-palvelimelta** annetusta reposta ja tagista.

### Polun muodostus

```
{owner}/{repo}/.gitea/workflows/build-feature.yml@{ref}
```

| Osa | Mistä | Esimerkki (homelab) |
|-----|-------|---------------------|
| `owner` | Repopolun ensimmäinen osa — **käyttäjänimi tai org** | `niko` |
| `repo` | Repon nimi | `gitea-ci-library` |
| tiedosto | Providerin workflow | `.gitea/workflows/build-feature.yml` |
| `@ref` | Tag tai branch provider-repossa | `@v1` (tuotanto) |

**Owner ei ole org-pakotettu.** Homelabissa ei välttämättä ole organisaatiotasoa — silloin owner on
käyttäjänimi (`niko/...`), ei keksitty `org/`-prefiksi.

Polku löytyy repostasi:

```bash
git remote get-url origin
# → ssh://git@gitea.app.keskikuja.site:30009/niko/gitea-ci-library.git
#    owner = niko, repo = gitea-ci-library
``` 
 
Consumerin `ci.yml`:

```yaml 
jobs:
  call-engine:
    uses: niko/gitea-ci-library/.gitea/workflows/build-feature.yml@v1
    secrets: inherit
```

### Usea Gitea-palvelin

`uses:` resolvoi **vain sen Gitea-instanssin** repohakemistosta, jolla runner ajaa työn.
Toisella palvelimella oleva repo ei näy — cross-server-viittaus ei toimi.

Jokaisella Gitea-palvelimella, jossa mikropalvelut ajavat CI:tä, **tämä kirjasto-repo pitää olla
läsnä** samalla `owner/repo`-polulla:

```
Gitea A (kehitys)          Gitea B (tuotanto/homelab 2)
niko/gitea-ci-library  ←→  niko/gitea-ci-library   (mirror tai push-mirror)
         ↑                            ↑
   consumer uses:              consumer uses:
   niko/gitea-ci-library/...   niko/gitea-ci-library/...
```

Mirror pitää `build-feature.yml`:n ja tagit (`v1`) saatavilla kulloisellakin palvelimella. Tämä korvaa
provider-repon checkout-hackit workflowissa — binding hoituu Gitean natiivilla `uses:`-mekanismilla.

Periaatteet: [tmp/data-flow-design.md](tmp/data-flow-design.md)

## Main-haaran suojaus

Jokaisessa tätä kirjastoa käyttävässä repossa `main`-haara suojataan — koodi päätyy sinne vain PR:n kautta:

```
Repository → Settings → Branches → Branch Protection → Add Rule
```

| Osio | Asetus | Arvo |
|------|--------|------|
| **Patterns** | Protected Branch Name Pattern | `main` |
| **Push** | Disable Push | ✓ |
| **Force Push** | Disable Force Push | ✓ |
| **Pull Request Approvals** | Required approvals | `1` |
| | Dismiss stale approvals | ✓ |
| | Ignore stale approvals | ✓ |
| | Enable Status Check | ✓ (kun CI on olemassa) |
| **Pull Request Merge** | Block merge on rejected reviews | ✓ |
| | Block merge on official review requests | ✓ |
| | Block merge if pull request is outdated | ✓

**Merge-tyyli:** Suositellaan squashia — koko PR yhtenä commitina `main`-haaraan. Muut tyypit disabloidaan:

```
Repository → Settings → Pull Requests → Merge Styles
```

| Asetus | Arvo |
|--------|------|
| Default Merge Style | `Squash` |
| Merge Commit | ✗ (pois) |
| Rebase | ✗ (pois) |

Ilman disablointia käyttäjä voi valita merge-commitin PR:n merge-napista — squash-suositus jää pelkäksi suositukseksi.

## Gitea Actions runner (K8s / Helm)

Act runner suorittaa Gitea Actions workflowt. **IaC-lähde:** alla oleva Helm-snippet on
klusterin totuus — muutokset vain snippetiin, sitten `helm upgrade --install` (ei käsin muokattuja
arvoja klusterissa).

> HUOM! Gitea ei ole vielä kunnolla stabiilissa tilassa, ja chart default dind sekä runner versiot ovat tätä tehdessä olleet bugiset. Niistä on olemassa uudemmat versiot, mutta eivät ole chartissa. Tätyy seurata ja päivittää tarpeen tulle.

Asennus Kubernetes-klusteriin Helm chartilla:

### 1. Rekisteröi token

Hae token Giteasta:
- **Organization-taso:** Org → Settings → Actions → Runners → Create new runner
- **Globaali (site admin):** Site Admin → Actions → Runners → Create new runner

### 2. variables

```bash
GITEA_URL="https://<gitea-server-url>"
GITEA_ACTIONS_TOKEN="<registration-token>"
GITEA_ACTIONS_NAMESPACE="gitea-actions"
```

### 3. Tee secret vain init install yhteydessä

```bash
kubectl create secret generic act-runner-token \
  --from-literal=token="$GITEA_ACTIONS_TOKEN" \
  --namespace "$GITEA_ACTIONS_NAMESPACE" \
  --dry-run=client -o yaml | kubectl apply -f -

```

### 4. Helm install / upgrade

Menee samalla komennolla. 

> Muista asettaa variables ennen ajoa.

Päivittää olemassa olevan installaation, käyttää olemassa olevaa secret
ja sitä kautta Gitea ei tarvitse päivityksessä mitään temppuja.

Päivityksen jälkeen muista tappaa pod (käynnistyy automaattisesti uudelleen), että lataa varmasti kaikki uudesta. Sillä ConfigMap tms eivät lataudu
mikäli pod jatkaa ajamista.

```bash
helm repo add gitea https://dl.gitea.com/charts
helm repo update

helm upgrade --install act-runner gitea/actions \
  --set enabled=true \
  --set giteaRootURL="$GITEA_URL" \
  --set existingSecret=act-runner-token \
  --set existingSecretKey=token \
  --set statefulset.runner.tag=1.0.8 \
  --set statefulset.dind.tag=29.5.2-dind \
  --set-string 'statefulset.runner.config=log:
  level: info
cache:
  enabled: false
container:
  require_docker: true
  docker_timeout: 300s' \
  --namespace "$GITEA_ACTIONS_NAMESPACE" \
  --create-namespace
```

path escapes from parent -bugi korjattiin Docker 29.5.2:ssa. Tämän teko aikana default on 29.5.1 — juuri tämän alle jäävä versio.

Oletus-lokitaso on `debug` — suositeltu `info`. Näkee jobien aloitukset ja valmistumiset ilman konttikerrosten purkua (Downloading/Extracting-spämmiä). `debug` on tarpeen vain vianselvityksessä.

#### Docker (DinD)

Helm chart deployaa DinD:n init-sidecarina (`docker:dind` samassa podissa).
`require_docker: true` kytkee jobit siihen — erillistä DinD-asennusta ei tarvita.

**DinD-tag pinottu:** `29.5.2-dind` (ei chart-oletusta). Docker 29.5.1 aiheuttaa act-runnerissa
`path escapes from parent` -virheen job-kontin käynnistyksessä.

Maven/npm-ajot käyttävät vain workflow'n `container:`-imagea; DinD tarvitaan vasta Docker-buildissä.

### 3. Varmista

```bash
kubectl get pods -n gitea-actions
# → act-runner-runner-0  Running

kubectl exec -n gitea-actions act-runner-runner-0 -c dind -- docker version
# → Server Version: 29.5.2 (tai uudempi)
```

Gitean puolella runner ilmestyy Active-tilaan pienellä viiveellä:

```
Site Admin → Actions → Runners  (tai Org → Settings → Actions → Runners)
# → act-runner-runner-0  Active  ubuntu-latest
```

Tämän jälkeen `.gitea/workflows/ci.yml` triggeröityy automaattisesti pushista.

Tarkista ennen ensimmäistä ajoa: [Provider-binding](#provider-binding--miten-consumer-löytää-providerin)
(owner/repo, `@ref` pushattu, Repo → Settings → Actions enabled).

Lisätietoa runnerin toiminnasta, konteista ja DinD:stä: [docs/runner.md](docs/runner.md)

## Vaaditut secretit ja muuttujat

Consumer-repossa on oltava seuraavat asetukset:

### Repo Actions Secrets (`{repo} → Settings → Actions → Secrets`)

| Secret | Kuvaus |
|--------|--------|
| `GIT_PAGES_PUBLISH_TOKEN` | Git-pages-palvelimen BasicAuth-token. Nimi on lukittu — tämä tarkka nimi vaaditaan. |

`GITEA_TOKEN` on Gitean sisäinen secret (`secrets.GITEA_TOKEN`), joka on automauttisesti saatavilla — sitä ei tarvitse erikseen luoda.

### Config-tiedosto (`.gitea/workflows/gitea-env.conf`)

Tiedoston **nimi ja polku on lukittu**: `.gitea/workflows/gitea-env.conf` consumer-repon juuressa.
Tämän tiedoston perusteella `config-provider.yml` tuottaa `env_json`-outputin, joka välitetään
workflowille.

Tiedosto on `key=value`-muotoinen (kuten `.env`). Kommentit ja tyhjät rivit sallittuja.

**Vaaditut avaimet:**

| Avain | Kuvaus |
|-------|--------|
| `GITEA_API_URL` | Gitea-palvelimen base URL (esim. `https://gitea.app.example.com`) |
| `GIT_PAGES_URL` | Git-pages-palvelimen URL ilman trailing slash (esim. `https://ci-reports.example.com`) |

**Validointisäännöt:**
- Arvot eivät saa olla tyhjiä
- Jos avaimen nimessä on `URL`, arvon on alettava `http://` tai `https://`
- Tiedoston on oltava olemassa (muuten job keskeytyy)

Esimerkki:
```
GITEA_API_URL=https://gitea.app.example.com
GIT_PAGES_URL=https://ci-reports.example.com
```

### Validaatio

Jokaisen jobin alussa `ci-validate.sh` tarkistaa:
- `.gitea/workflows/gitea-env.conf` on olemassa ja sen arvot ovat validit
- `GITEA_TOKEN` ja `GIT_PAGES_PUBLISH_TOKEN` on asetettu

Jos validointi epäonnistuu, job keskeytyy exit-koodilla 1 ja Gitean commit-status näyttää epäonnistumisen linkkinä lokiin.

### Muuta

| Muuttuja | Kuvaus |
|----------|--------|
| `giteaRootURL` | Gitea-palvelimen osoite (esim. `https://gitea.example.com`) |
| `existingSecret` | Kubernetes secretin nimi, jossa token |
| `existingSecretKey` | Avain secretin sisällä |
| `statefulset.dind.tag` | DinD-image tag (`29.5.2-dind` minimi) |
| `statefulset.runner.labels` | Mukautetut labelit |