Zrcadlo autorova Gitu, spuštění testů, sestavení QPKG: CI na vašem NASu

Forgejo na vašem NASu udržuje pull zrcadlo repozitáře programu. Samostatný balicí projekt každý den sestaví nejnovější vydání autora, spustí autorovy testy a vytvoří z něj QPKG, a to na vlastním runneru NASu. Příkladem je fzy, malý fuzzy vyhledávač napsaný v C (licence MIT).

1. ModulyGit, CI, Editor
2. Zrcadlorepozitář autora
3. ProjektNový projekt, balíček QPKG
4. Workflowstažení, testy, sestavení
5. Běhydenně, při push, ručně

Obrázky pocházejí z panelu a z Forgejo aplikace Bucket & Code Server IDE, kde je každé pole vyplněné podle tohoto návodu. Účet se jmenuje ola.

01Než začnete

• Git, CI a Editor musí být zapnuté. Vypnutý modul má tlačítko na své dlaždici na Overview i na vlastní stránce: Turn on Git, Turn on Editor a, dokud je Git ještě vypnutý, Turn on Git and CI.
• QDK musí být nainstalovaný: na stránce Toolchains, na záložce QNAP, nainstalujte QNAP QDK 2.5.0.
• Potřebujete sestavovací prostředí Ubuntu 24.04: Apps → Examples, nebo Create a Builder environment na stránce New app. Workflow v něm sestavuje.
• NAS potřebuje přístup k internetu: actions/checkout a actions/upload-artifact pocházejí z data.forgejo.org a zrcadlo stahuje z autorova serveru.

Runner na NASu přebírá úlohy, jejichž runs-on uvádí jeden z jeho štítků, například bucketvs. Každou úlohu spouští přímo na NASu, jako admin. Kdo může do repozitáře nahrát workflow, může tedy na NASu spouštět příkazy jako admin: přístup pro push dávejte jen lidem, kterým byste svěřili heslo správce NASu.

02Zrcadlení repozitáře autora

1. Ve Forgejo (Open Forgejo na stránce Git) stiskněte + → New migration → Git.
2. Vložte adresu repozitáře autora, zde https://github.com/jhawthorn/fzy.git, zaškrtněte This repository will be a mirror, pojmenujte jej, například fzy-upstream, a stiskněte Migrate repository.
3. Zrcadlo stahuje commity a tagy autora samo. Jeho Settings ukazují Mirror interval (8 hodin, pokud ho nezměníte; nejméně 10 minut) a Synchronize now.

Zrcadlo odmítá pushe, takže váš vlastní workflow se do něj nedostane. Synchronizace spouští jen workflow, která autorův repozitář sám obsahuje v .forgejo/workflows/, a fzy žádné nemá. Sestavení proto patří do vašeho vlastního repozitáře, který ze zrcadla čte.

03Váš vlastní balicí projekt

Otevřete New project ze stránky Git nebo z příkazové palety (role developer). Návod Vlastní App Center vás provede každým krokem; pro tento příklad:

1. Template: QPKG package.
2. Name: fzy. Service: Command-line tool, který po dobu běhu balíčku vytvoří odkaz na program v /usr/bin.
3. Build environment: ubuntu2404-builder, prostředí, které workflow používá.
4. Stiskněte Create project. Projekt dostane svůj repozitář, složku projects/fzy a workflow šablony, který v sekci 05 nahradíte.

Repozitář vytvořený dříve, než bylo CI zapnuté, má Forgejo Actions vypnuté a workflow, který do něj pošlete, nic nespustí. Zapněte je v Settings repozitáře → Units; repozitáře vytvořené při zapnutém CI je mají zapnuté od začátku.

04Token jen pro čtení pro zrcadlo

Úloha klonuje zrcadlo přes HTTPS. Pokud zrcadlo není veřejné nebo není zapnutá volba Public browsing, klonování vyžaduje přihlášení. Workflow mu proto předá token, který umí jen číst.

1. Ve Forgejo: Settings → Applications → Generate new token: název například mirror-read, oprávnění repository: Read. Token si zkopírujte: Forgejo ho zobrazí jen jednou.
2. V repozitáři s balíčkem: Settings → Actions → Secrets → Add secret: název MIRROR_TOKEN a token jako hodnota.

05Pracovní postup

Uložte tento soubor do projektu jako .forgejo/workflows/build.yml místo souboru ze šablony a pošlete ho pushem. Spouští se při každém pushi, jednou denně a ručně.

# .forgejo/workflows/build.yml: fzy from the author's newest release, tested, as a QPKG
name: build
on:
  push:
  schedule:
    - cron: '30 4 * * *'
  workflow_dispatch:
jobs:
  build:
    runs-on: bucketvs
    steps:
      - uses: actions/checkout@v4
      - name: The author's newest release, from the mirror
        run: |
          git -c http.extraHeader="Authorization: token $MIRROR_TOKEN" clone --quiet \
            "${{ github.server_url }}/${{ github.repository_owner }}/fzy-upstream.git" upstream
          tag=$(git -C upstream describe --tags --abbrev=0)
          git -C upstream checkout --quiet "$tag"
          echo "VERSION=${tag#v}" >> "$GITHUB_ENV"
        env:
          MIRROR_TOKEN: ${{ secrets.MIRROR_TOKEN }}
      - name: Build and run the author's tests
        run: |
          bvs env run ubuntu2404-builder -- make -C upstream
          bvs env run ubuntu2404-builder -- make -C upstream check
      - name: Put the program into the package
        run: |
          rm -f shared/bin/fzy
          install -D -m 755 upstream/fzy x86_64/bin/fzy
          sed -i "s/^QPKG_VER=.*/QPKG_VER=\"$VERSION\"/" qpkg.cfg
      - name: Build the QPKG
        run: bvs qbuild
      - uses: actions/upload-artifact@v3
        with:
          name: fzy-qpkg
          path: build/*.qpkg
      - name: Publish into this NAS's App Center repository
        run: |
          for f in build/*.qpkg; do
            if out=$(bvs repo publish "$f" --arch x86_64 --latest 2>&1); then
              echo "$out"
            elif printf '%s' "$out" | grep -q 'carries no code signature'; then
              echo "::warning::$f is built but not published: it carries no code signature"
            else
              echo "$out" >&2
              exit 1
            fi
          done

• Druhý krok převezme nejnovější tag zrcadla, takže balíček sleduje vydání autora, a jeho verze se stane verzí balíčku (QPKG_VER).
• bvs env run ubuntu2404-builder -- … sestaví a otestuje v prostředí s jeho kompilátorem a knihovnami. Neúspěšný test ukončí běh a nic se nezabalí.
• bvs qbuild sestaví balíček do build/. Běh si ho ponechá jako artefakt.
• Poslední krok publikuje do repozitáře App Center na NASu, který přijímá jen balíčky podepsané kódem. Bez certifikátu běh skončí varováním a balíček zůstane jako artefakt. Návod Vlastní App Center ukazuje dva kroky, které podepíší každé sestavení.

06Běhy, testy a balíček

Karta Actions v repozitáři vypisuje každý běh a to, co ho spustilo: push, plán nebo člověk.

Běh ukazuje každý krok s časem. Krok s testy vypisuje vlastní výsledky autora.

Run workflow spustí běh ručně, například hned po Synchronize now zrcadla. Balíček najdete v sekci Artifacts na stránce běhu.