gitea-ci-library/README.md

# Gitea Actions CI -kirjasto

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

## 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).

Asennus Kubernetes-klusteriin Helm chartilla:

### 1. Rekisteröintitoken

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

### 2. Asenna runner

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

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

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 -

helm upgrade --install act-runner gitea/actions \
  --set enabled=true \
  --set giteaRootURL="$GITEA_URL" \
  --set existingSecret=act-runner-token \
  --set existingSecretKey=token \
  --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 |