Gitea Actions CI -kirjasto

Reusable workflow -kirjasto Gitea Actionsille. Lisätietoja: 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:

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:

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

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

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

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 (owner/repo, @ref pushattu, Repo → Settings → Actions enabled).

Lisätietoa runnerin toiminnasta, konteista ja DinD:stä: 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