Spiegel de Git van de auteur, draai de tests, bouw een QPKG: CI op je NAS

Forgejo op je NAS houdt een pull-spiegel bij van de repository van een programma. Een apart inpakproject bouwt elke dag de nieuwste release van de auteur, draait de tests van de auteur en maakt er een QPKG van, op de eigen runner van de NAS. Het voorbeeld is fzy, een kleine fuzzy finder geschreven in C (MIT-licentie).

1. ModulesGit, CI, de Editor
2. Spiegelde repository van de auteur
3. ProjectNieuw project, QPKG-pakket
4. Workflowophalen, testen, bouwen
5. Runsdagelijks, bij een push, handmatig

De afbeeldingen komen uit het paneel en Forgejo van Bucket & Code Server IDE, met elk veld ingevuld zoals deze handleiding beschrijft. Het account heet ola.

01Voordat je begint

• Git, CI en de Editor moeten aan staan. Een module die uit staat, heeft een knop op zijn tegel op het Overzicht en op zijn eigen pagina: Git aanzetten, Editor aanzetten, en Git en CI aanzetten zolang Git nog uit staat.
• QDK moet geïnstalleerd zijn: installeer op de pagina Toolchains, tabblad QNAP, QNAP QDK 2.5.0.
• Je hebt de Ubuntu 24.04-buildomgeving nodig: Apps → Voorbeelden, of Een Builder-omgeving aanmaken op de pagina Nieuwe app. De workflow bouwt daarin.
• De NAS heeft internettoegang nodig: actions/checkout en actions/upload-artifact komen van data.forgejo.org, en de spiegel haalt gegevens van de server van de auteur.

De runner op de NAS neemt de taken aan waarvan runs-on een van zijn labels noemt, zoals bucketvs. Hij voert elke taak uit op de NAS zelf, als admin. Wie een workflow in een repository kan pushen, kan dus opdrachten als admin op de NAS uitvoeren: geef pushtoegang alleen aan mensen aan wie je ook het admin-wachtwoord van de NAS zou geven.

02De repository van de auteur spiegelen

1. In Forgejo (Forgejo openen op de Git-pagina) druk je op + → Nieuwe migratie → Git.
2. Plak het adres van de repository van de auteur, hier https://github.com/jhawthorn/fzy.git, vink Deze repository wordt een spiegel aan, geef een naam, bijvoorbeeld fzy-upstream, en druk op Repository migreren.
3. De spiegel haalt de commits en tags van de auteur zelf op. De Instellingen tonen het Spiegelinterval (8 uur tenzij je het wijzigt, minimaal 10 minuten) en Nu synchroniseren.

Een spiegel weigert pushes, dus je eigen workflow kan er niet in. Een synchronisatie draait alleen de workflows die de repository van de auteur zelf in .forgejo/workflows/ heeft, en fzy heeft er geen. De build staat daarom in een eigen repository die de spiegel leest.

03Een eigen inpakproject

Open Nieuw project vanaf de Git-pagina of het commandopalet (rol developer). De handleiding Je eigen App Center behandelt elke stap; voor dit voorbeeld kies je:

1. Sjabloon: QPKG-pakket.
2. Naam: fzy. Dienst: Opdrachtregelprogramma, dat het programma koppelt aan /usr/bin terwijl het pakket draait.
3. Buildomgeving: ubuntu2404-builder, de omgeving die de workflow gebruikt.
4. Druk op Project aanmaken. Het project krijgt zijn repository, de map projects/fzy en de workflow van het sjabloon; die vervang je in sectie 05.

In een repository die is gemaakt voordat CI aan stond, staan de Actions van Forgejo uit, en dan start een gepushte workflow niets. Zet ze aan in de Instellingen van de repository → Units; in repositories die zijn gemaakt terwijl CI aan stond, staan ze al aan.

04Een alleen-lezen token voor de spiegel

De taak kloont de spiegel via HTTPS. Tenzij de spiegel openbaar is en Openbaar bladeren aan staat, heeft die kloon een aanmelding nodig. De workflow geeft daarvoor een token dat alleen kan lezen.

1. In Forgejo: Instellingen → Applications → Generate new token: een naam zoals mirror-read, het recht repository: Read. Kopieer het token: Forgejo toont het maar één keer.
2. In de repository van het inpakproject: Instellingen → Acties → Secrets → Add secret: de naam MIRROR_TOKEN en het token als waarde.

05De workflow

Zet dit bestand in het project als .forgejo/workflows/build.yml, in plaats van dat van het sjabloon, en push het. De workflow draait bij elke push, eens per dag en wanneer je hem met de hand start.

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

• De tweede stap pakt de nieuwste tag van de spiegel, zodat het pakket de releases van de auteur volgt. De versie van die tag wordt de versie van het pakket (QPKG_VER).
• bvs env run ubuntu2404-builder -- … bouwt en test binnen de omgeving, met de compiler en bibliotheken ervan. Een mislukte test laat de run mislukken, en er wordt niets ingepakt.
• bvs qbuild bouwt het pakket in build/. De run bewaart het als artefact.
• De laatste stap publiceert naar de App Center-repository van de NAS, die alleen code-ondertekende pakketten accepteert. Zonder certificaat eindigt de run met een waarschuwing en blijft het pakket een artefact. De handleiding Je eigen App Center beschrijft de twee stappen die elke build ondertekenen.

06Runs, tests en het pakket

Het tabblad Acties van de repository toont elke run met wat die run heeft gestart: een push, het schema of een persoon.

Een run toont elke stap met de tijd die de stap duurde. De stap met de tests toont de uitvoer van de eigen tests van de auteur.

Run workflow start hem met de hand, bijvoorbeeld direct na Synchronize now van de spiegel. Het pakket staat onder Artifacts op de pagina van de run.