Gitea Actions: Git platforma a pipeline na jednom serveru

Gitea Actions: Git platforma a pipeline na jednom serveru

Ve třetí a čtvrté části jsme přesunuli provádění úloh na vlastní server. Kód přitom zůstal tam, kde byl: na GitHubu nebo GitLabu. Pro většinu týmů je to správná rovnováha, protože administrovat se musí jen agent. Existují ale úlohy, kde toto rozdělení nefunguje, a pak se na váš server přestěhuje celý systém včetně repozitáře.

Tato část je o Gitea a jejím vestavěném CI. Rozjedeme Git platformu na VPS, připojíme k ní act runner, napíšeme workflow v syntaxi, kterou už znáte ze třetí části, a zakončíme stejným deployem přes SSH. Na konci rozebereme, kde formulace „plně uzavřený okruh" přestává být přesná, pokud ji vědomě nedotáhnete do konce.

1.1 Kdy self-hosted runner nestačí

Vlastní agent řeší otázku zdrojů a přístupu do uzavřené sítě, ale nemění to hlavní: repozitář, historii commitů, issues a code review žijí na cizí platformě. Situace, kde se to stává překážkou:

• Smluvní závazky. Zákazník vyžaduje, aby zdrojový kód neopustil jeho perimetr, a formulace ve smlouvě nedělá výjimku pro cloudový Git hosting.
• Práce bez přístupu k internetu. Izolovaný okruh, kde vnější připojení neexistují vůbec, ne jen jsou omezená.
• Nezávislost na dodavateli. Změna licenčních podmínek, tarifů nebo dostupnosti služby by neměla zastavit vývoj.
• Náklady u velkého týmu. Platba za uživatele u několika desítek účtů znatelně převyšuje cenu VPS.

1.2 Co dává plně uzavřený okruh

Když Git platforma i CI stojí na vašem serveru, mizí vnější závislost v každodenní práci: vývoj pokračuje, i když je vnější kanál nedostupný. Data ze soukromého repozitáře se nepředávají žádné třetí straně a omezení přístupu popisují vaše vlastní pravidla.

Cena tohoto řešení je přímá. Odpovídáte za zálohy repozitářů a databáze, za aktualizace platformy a uzavírání zranitelností, za dostupnost serveru v pracovní době. Cloudový GitHub to dělá nenápadně, váš server vyžaduje, aby se tím někdo systematicky zabýval.

1.3 Co dalšího v této oblasti existuje

Rozcestí je tady takové. Gitea a Forgejo dávají dva systémy v jednom: Git a CI se instalují společně, konfigurace je jedna, syntaxe je známá z GitHubu. Gogs ve dvojici s Woodpeckerem dává větší flexibilitu a nezávislost částí, za cenu dvou samostatných služeb, které je třeba rozjet, aktualizovat a propojit mezi sebou. Pro první vlastní okruh je jednodušší první varianta, a dál v článku jdeme právě tou cestou.

2. Architektura Gitea Actions

2.1 Gitea jako Git platforma

Gitea je jeden binární soubor v Go, který dává repozitáře, issues, pull requesty, code review, webhooky, organizace a přístupová práva. Ve své jednoduché podobě běží na SQLite a souborovém systému, tedy bez samostatné databáze a bez dalších služeb. Pro tým deseti inženýrů to stačí, pro větší instalaci se bere PostgreSQL.

Spotřeba zdrojů je znatelně nižší než u GitLabu: samotná Gitea se drží v řádu stovek megabajtů paměti. Rozdíl je v tom, že GitLab je desítka propojených služeb, zatímco Gitea je jeden proces.

2.2 Gitea Actions: známá syntaxe

Gitea Actions se objevily ve verzi 1.19 a kopírují model GitHub Actions: workflow, úlohy, kroky, akce přes uses. Soubory leží v adresáři .gitea/workflows/ a většina jednoduchých konfigurací ze třetí části se přenese bez úprav.

Kompatibilita není úplná a vyplatí se znát hranice předem:

• Akce se berou z vnějšího zdroje. Ve výchozím stavu se uses: actions/checkout@v4 stahuje z GitHubu. Pro uzavřený okruh to bude třeba změnit, a níže se k tomu vrátíme.
• Část možností chybí. Matice fungují, cache funguje, ale prostředí s potvrzením od revizora a část složitějších konstrukcí GitHubu jsou implementovány neúplně nebo se chovají jinak.
• Akce v JavaScriptu a kompozitní fungují, kontejnerové akce také. Ale vše, co volá GitHub API, v Gitea nebude fungovat.

2.3 Act runner: samostatný proces

Úlohy provádí act runner: samostatný program postavený na projektu act, který spouští workflow GitHub Actions lokálně. Logika je stejná jako v předchozích částech: runner se dotazuje Gitea, dostane úlohu, připraví prostředí, provede kroky a vrátí logy.

Provádění existuje ve dvou typech. V režimu docker běží každá úloha v kontejneru z image uvedeného ve štítku runneru. V režimu host se příkazy provádějí přímo na serveru, bez izolace, a pak musí být všechno potřebné pro sestavení nainstalováno předem.

2.4 Schéma spojení

vývojář
   │ git push (SSH nebo HTTPS)
   ↓
┌─────────────────────────────┐
│  Gitea                      │
│  repozitář + webové rozhraní│
│  fronta úloh Actions        │
└─────────────────────────────┘
   ↑ dotazování fronty přes HTTP
   │ logy a stav
┌─────────────────────────────┐
│  act runner                 │
│  docker: kontejner na úlohu │
│  host: příkazy na serveru   │
└─────────────────────────────┘
   │ SSH
   ↓
produkční server

Obě komponenty mohou žít na jednom VPS, a pro malý tým se to tak i dělá. Rozdělení na dva stroje má smysl, když jsou sestavení náročná: rozhraní Gitu by nemělo brzdit jen proto, že vedle běží kompilace.

3. Instalace Gitea na VPS

3.1 Zdroje

Minimum pro provoz je 1 vCPU a 1 GB RAM, a v takové konfiguraci Gitea skutečně funguje. Ale samostatně počítejte s runnerem: sestavení spotřebují víc než samotná platforma. Pracovní orientační hodnoty:

• Jen Gitea, malý tým: 1 vCPU, 1 GB RAM, 20 GB disku.
• Gitea a act runner na jednom stroji: 2 vCPU, 4 GB RAM, od 40 GB disku.
• Sestavení s Dockerem: 4 vCPU, 8 GB RAM a samostatný pohled na disk, protože image a vrstvy rostou rychle.

3.2 Instalace

Varianta s binárkou je přehlednější, když se se systémem seznamujete poprvé:

sudo apt update && sudo apt install git sqlite3 -y

# verzi a odkaz vezměte ze stránky ke stažení Gitea
sudo wget -O /usr/local/bin/gitea "<odkaz na binárku linux-amd64>"
sudo chmod +x /usr/local/bin/gitea
gitea --version

# uživatel a adresáře
sudo adduser --system --group --disabled-password --home /home/git git
sudo mkdir -p /var/lib/gitea/{custom,data,log} /etc/gitea
sudo chown -R git:git /var/lib/gitea /etc/gitea
sudo chmod 750 /var/lib/gitea
sudo chmod 770 /etc/gitea

Práva na /etc/gitea jsou záměrně volná jen do konce instalace: webový instalátor tam zapíše app.ini, po čemž se adresář uzavře.

Varianta s Dockerem je kratší a pohodlnější pro aktualizace:

# compose.yaml
services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
    volumes:
      - ./gitea-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"

3.3 Systemd služba

Tento krok je potřeba jen pro variantu instalace binárkou výše. Pokud jste Gitea rozjeli přes Docker Compose, samostatná systemd jednotka není potřeba: restart a automatické spuštění kontejneru už zajišťuje parametr restart: always přímo v compose souboru.

# /etc/systemd/system/gitea.service
[Unit]
Description=Gitea
After=network.target

[Service]
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now gitea
sudo systemctl status gitea

3.4 První spuštění

Rozhraní se otevírá na portu 3000. Webový instalátor se ptá na typ databáze, cesty k adresářům, doménu a adresu instance, a dole na stránce, v sekci s nepovinným nastavením, se vytváří administrátor.

Čtyři věci, které se vyplatí udělat hned po instalaci:

• Vytvořte administrátora na stránce instalátoru. Jinak se jím stane první zaregistrovaný uživatel.
• Vypněte volnou registraci. V app.ini je to DISABLE_REGISTRATION = true v sekci [service].
• Nastavte HTTPS. Funkční varianta je Nginx nebo Caddy před Gitea, s certifikátem od Let's Encrypt a ROOT_URL, který odpovídá vnější adrese.
• Uzavřete práva na konfiguraci. sudo chmod 750 /etc/gitea && sudo chmod 640 /etc/gitea/app.ini

4. Instalace act runneru

4.1 Binárka

Act runner se distribuuje samostatně od Gitea, odkaz vezměte ze stránky releasů projektu:

sudo wget -O /usr/local/bin/act_runner "<odkaz na act_runner linux-amd64>"
sudo chmod +x /usr/local/bin/act_runner
act_runner --version

Pro režim docker je potřeba nainstalovaný Docker a uživatel, pod kterým runner běží, musí být ve skupině docker.

4.2 Registrace

Token se bere na jednom ze tří míst, podle toho, jak široce má runner obsluhovat systém:

• Repozitář: Settings → Actions → Runners → Create new runner.
• Organizace: stejná cesta v nastavení organizace.
• Celá instalace: Site Administration → Actions → Runners.

sudo mkdir -p /etc/act_runner && cd /etc/act_runner
act_runner generate-config > config.yaml

act_runner register --no-interactive \
  --instance https://git.example.com \
  --token <token z rozhraní> \
  --name vps-runner-01 \
  --labels ubuntu-latest:docker://gitea/runner-images:ubuntu-latest,deploy:host

Štítky tady fungují jinak než v předchozích částech, a právě tady se nejčastěji plete. Štítek se skládá ze tří částí: jméno, způsob provedení a image. Zápis ubuntu-latest:docker://gitea/runner-images:ubuntu-latest znamená: úloha s runs-on: ubuntu-latest se provede v kontejneru z tohoto image. Zápis deploy:host znamená: úloha s runs-on: deploy se provede přímo na serveru.

Schéma se dvěma štítky opakuje řešení ze čtvrté části: sestavení jsou izolovaná v kontejneru, deploy dostává přístup ke klíčům a síti hostu.

4.3 Systemd služba

# /etc/systemd/system/act_runner.service
[Unit]
Description=Gitea Act Runner
After=docker.service

[Service]
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
WorkingDirectory=/etc/act_runner
User=act_runner
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now act_runner
journalctl -u act_runner -f

4.4 Ověření a zapnutí Actions

V seznamu runnerů (Settings → Actions → Runners) se agent musí objevit se stavem Idle a seznamem štítků. Pokud tam není, podívejte se do logů služby: typické příčiny jsou nedostupná adresa instance, zastaralý token nebo chybějící práva na socket Dockeru.

Samostatně ověřte, že jsou Actions zapnuté na úrovni instalace. V současných verzích je to výchozí stav, ve starších je potřeba explicitní zápis v app.ini:

[actions]
ENABLED = true

Po změně konfigurace se služba Gitea restartuje. Pro konkrétní repozitář se Actions zapínají samostatně, v Settings → Repository → Advanced Settings.

5. První workflow

5.1 Kde leží konfigurace

Soubory workflow se ukládají do .gitea/workflows/. Adresář .github/workflows/ Gitea také čte, což je pohodlné při přechodu z GitHubu: repozitář se přenese tak, jak je, a spustí se bez úprav cest.

5.2 Základní příklad

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npm run lint
      - run: npm test -- --ci

Soubor je identický s tím, co by fungovalo na GitHub Actions. Hodnota runs-on tady není název cloudového stroje, ale štítek vašeho runneru, který jste zadali při registraci.

5.3 Triggery

Fungují push, pull_request, schedule a workflow_dispatch, a také události specifické pro Gitea, jako issues a release.

on:
  push:
    branches: [main]
    paths-ignore: ['**.md', 'docs/**']
  pull_request:
  schedule:
    - cron: '0 3 * * *'
  workflow_dispatch:

Rozvrh v Gitea má výhodu oproti cloudové variantě: schedule se provádí na vašem serveru bez front, takže spuštění probíhá včas.

5.4 První spuštění a logy

Po push otevřete záložku Actions v repozitáři: je tam seznam spuštění, úlohy a logy kroků v reálném čase. Rozhraní je poznatelné z GitHubu, i když jednodušší.

Dva typické problémy prvního spuštění:

• Úloha visí ve stavu Waiting. Není online runner se štítkem uvedeným v runs-on. Porovnejte řádek ve workflow se seznamem štítků na stránce Runners.
• Krok s uses spadne při stahování. Akce se táhne z GitHubu a server tam nemá přístup. Víc o tom dál.

6. Praktický příklad: deploy přes SSH

6.1 Secrets v Gitea

Mechanismus kopíruje GitHub: Settings → Actions → Secrets pro hodnoty, které se maskují v logách, a Variables pro běžná nastavení. Secrets se nastavují na úrovni repozitáře, organizace nebo celé instalace.

Přidáme tři hodnoty:

• SSH_PRIVATE_KEY — celý obsah soukromého klíče, včetně řádků BEGIN a END.
• SSH_KNOWN_HOSTS — výstup ssh-keyscan -H your-server.example.com.
• DEPLOY_HOST — adresa produkčního serveru.

Podmínky na produkčním serveru jsou stejné jako ve třetí části: uživatel deploy bez práv root, klíč v authorized_keys s parametrem from a cílené oprávnění na restart služby přes sudoers.

6.2 Kompletní workflow

name: Build and deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npm run lint
      - run: npm test -- --ci
      - run: npm run build

      - uses: actions/upload-artifact@v3
        with:
          name: dist
          path: dist/

  deploy:
    needs: build
    runs-on: deploy          # štítek host režimu
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: dist
          path: dist/

      - name: Připravit SSH
        run: |
          install -m 700 -d ~/.ssh
          install -m 600 /dev/null ~/.ssh/deploy_key
          echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/deploy_key
          echo "${{ secrets.SSH_KNOWN_HOSTS }}" > ~/.ssh/known_hosts

      - name: Nahrát soubory
        run: |
          rsync -az --delete \
            -e "ssh -i ~/.ssh/deploy_key" \
            dist/ deploy@${{ secrets.DEPLOY_HOST }}:/var/www/app/

      - name: Restartovat službu
        run: |
          ssh -i ~/.ssh/deploy_key deploy@${{ secrets.DEPLOY_HOST }} \
            "sudo systemctl restart app.service"

      - name: Ověřit, že služba naběhla
        run: |
          for i in $(seq 1 10); do
            code=$(curl -s -o /dev/null -w "%{http_code}" https://app.example.com/health || true)
            [ "$code" = "200" ] && exit 0
            sleep 3
          done
          echo "Služba po deployi neodpovídá"
          exit 1

      - name: Uklidit klíč
        if: always()
        run: rm -f ~/.ssh/deploy_key

Porovnejte tento soubor s konfigurací ze třetí části: rozdíly se scvrkávají na verze akcí a název štítku. To je hlavní praktická hodnota Gitea Actions, protože zkušenost s GitHubem se přenáší téměř celá.

Verze akcí jsou tady záměrně nižší než na GitHubu. Akce upload-artifact a download-artifact verze v4 spoléhají na GitHub API, které Gitea nemá, takže funguje právě v3. Je to typický případ: nekontrolujte samotnou akci, ale to, zda se obrací na platformu.

6.3 Nakolik je okruh uzavřený

Teď k místu, kde formulace „ani jeden bajt neopustí server" přestává být přesná. Kód, historie, secrets a logy skutečně zůstávají u vás. Ale řádek uses: actions/checkout@v4 ve výchozím stavu táhne akci z github.com, a bez přístupu tam se úloha nespustí.

Tři funkční řešení:

• Zrcadlo akcí uvnitř Gitea. Vytvoříte organizaci, například actions, a zkopírujete do ní potřebné repozitáře akcí. V app.ini nastavíte DEFAULT_ACTIONS_URL = self, po čemž uses hledá akce ve vaší instalaci.
• Explicitní adresa ve workflow. Zdroj se zapisuje přímo v uses, když je část akcí lokální a část ne.
• Zřeknutí se uses. Místo actions/checkout obyčejný git clone, místo setup-node potřebný image kontejneru. Upovídanější, zato úplně bez vnějších závislostí.

První varianta je pohodlnější v každodenní práci, třetí je nejjednodušší na ověření souladu s požadavky. Zrcadlo akcí potřebuje aktualizace, takže je třeba ho také hlídat.

7. Závěr

7.1 Gitea Actions a GitHub Actions

Syntaxe je stejná, rozdíl je v tom, kde se uchovává kód a kdo odpovídá za chod systému. Praktické rozdíly, které stojí za zapamatování:

• Štítky popisují způsob provedení. Ne jen jméno agenta, ale kombinaci „jméno : docker nebo host : image".
• Ne všechny akce fungují. Vše, co volá GitHub API, v Gitea selhává, takže verze akcí se vybírají podle platformy.
• Image jsou lehčí. Nástroje, které jsou v cloudu výchozí, se tady instalují samostatně.
• Akce se ve výchozím stavu táhnou zvenčí. Pro skutečně uzavřený okruh je potřeba zrcadlo nebo zřeknutí se uses.

7.2 Kdy zvolit Gitea

Gitea je namístě, když kód nesmí opustit vaši infrastrukturu: smluvní požadavky, izolovaný okruh, plná kontrola nad daty. Druhý scénář je cena: vlastní VPS je levnější než platba za několik desítek účtů. Třetí je nezávislost na rozhodnutích dodavatele.

Proti ní mluví totéž co pro ni: všechno administrujete vy. Zálohy, aktualizace, dostupnost, HTTPS certifikáty, zrcadlo akcí. Pokud se tím v týmu nikdo nebude systematicky zabývat, cloudová platforma se self-hosted runnerem ze třetí nebo čtvrté části dá lepší výsledek za menší úsilí.

7.3 Co bude dál v sérii

Teď máme tři funkční varianty, postavené vlastníma rukama: GitHub Actions s vlastním agentem, GitLab CI s vlastním runnerem a úplně lokální okruh na Gitea. V šesté části je shrneme do jedné tabulky a rozebereme volbu podle konkrétních podmínek: velikost týmu, požadavky na uložení kódu, složitost pipeline, rozpočet a to, kolik času je tým ochoten věnovat administraci.

Časté dotazy