Gitea Actions CI -kirjasto

Reusable workflow -kirjasto Gitea Actionsille. Lisätietoja: docs/

Consumer-käyttöönotto: skills/consumer-pipelines/SKILL.md — pipeline-standardit ja säännöt consumer-projekteille

GitOps-päivitys: skills/gitops-update/SKILL.md — GitOps-repon job-template, dispatch ja token-ohjeet

Single repo & monorepo: Kirjasto toimii molemmissa. Monorepo-tuki polkusuodatuksella, komponenttikohtaisilla versioilla ja git-tägien etuliitteillä — jokainen komponentti julkaistaan itsenäisesti omassa tahdissaan. Katso skills/consumer-pipelines/SKILL.md.

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

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

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

3. Tee secret vain init install yhteydessä

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.

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.replicas=3 \
  --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

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 automaattisesti jokaiselle workflow-runille generoima token (secrets.GITEA_TOKEN). Se on scopeutettu siihen repoon, jossa workflow ajaa — ei toimi toiseen repoon dispatchaukseen eikä toisen repon commit-statusin asettamiseen. Ei tarvitse erikseen luoda.

Jos workflow tarvitsee oikeuksia toiseen repoon (esim. dispatch GitOps-repoon), tarvitaan manuaalinen token. Katso skills/gitops-update/SKILL.md.

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.

GitOps-päivitys

Artifact buildin jälkeen voidaan dispatchata GitOps-repoon, joka päivittää konfiguraatiotiedoston (esim. Chart.yaml version) ja pushaa muutoksen.

Kaksi skriptiä:

• scripts/dispatch-workflow.sh — lähettää workflow_dispatch-pyynnön ja pollaa valmistumista
• scripts/gitops-update.sh — kloonaa, päivittää yq:llä, committaa ja pushaa

Tarkka asennus: skills/gitops-update/SKILL.md

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