Git des Autors spiegeln, Tests ausführen, QPKG bauen: CI auf Ihrem NAS

Forgejo auf Ihrem NAS hält einen Pull-Spiegel des Repositorys eines Programms. Ein eigenes Paketierungsprojekt baut jeden Tag die neueste Version des Autors, führt die Tests des Autors aus und erstellt daraus ein QPKG, und zwar auf dem eigenen Runner des NAS. Das Beispiel ist fzy, ein kleiner Fuzzy-Finder in C (MIT-Lizenz).

1. ModuleGit, CI, der Editor
2. Spiegeldas Repository des Autors
3. ProjektNeues Projekt, QPKG-Paket
4. Workflowabrufen, testen, bauen
5. Läufetäglich, bei einem Push, auf Anforderung

Die Bilder stammen aus dem Panel und aus Forgejo von Bucket & Code Server IDE; jedes Feld ist so ausgefüllt, wie diese Anleitung es beschreibt. Das Konto heißt ola.

01Bevor Sie anfangen

• Git, CI und der Editor müssen eingeschaltet sein. Für ein ausgeschaltetes Modul gibt es eine Schaltfläche auf seiner Kachel in der Übersicht und auf seiner eigenen Seite: Git einschalten, Editor einschalten und Git und CI einschalten, solange Git noch aus ist.
• QDK muss installiert sein: Installieren Sie auf der Seite Toolchains, Reiter QNAP, QNAP QDK 2.5.0.
• Sie brauchen die Build-Umgebung Ubuntu 24.04: Apps → Beispiele oder Builder-Umgebung anlegen auf der Seite „Neue App“. Der Workflow baut darin.
• Das NAS braucht Zugang zum Internet: actions/checkout und actions/upload-artifact kommen von data.forgejo.org, und der Spiegel holt die Daten vom Server des Autors.

Der Runner auf dem NAS übernimmt die Jobs, deren runs-on eines seiner Labels nennt, etwa bucketvs. Er führt jeden Job direkt auf dem NAS aus, und zwar als Administrator. Wer einen Workflow in ein Repository pushen darf, kann daher Befehle als Administrator auf dem NAS ausführen. Geben Sie Push-Zugriff nur Personen, denen Sie auch das Administratorpasswort des NAS geben würden.

02Das Repository des Autors spiegeln

1. In Forgejo (Forgejo öffnen auf der Seite Git) drücken Sie + → New migration → Git.
2. Fügen Sie die Adresse des Repositorys des Autors ein, hier https://github.com/jhawthorn/fzy.git, setzen Sie den Haken bei This repository will be a mirror, geben Sie ihm einen Namen, zum Beispiel fzy-upstream, und drücken Sie Migrate repository.
3. Der Spiegel holt die Commits und Tags des Autors selbstständig. In seinen Einstellungen sehen Sie das Mirror interval (8 Stunden, sofern Sie es nicht ändern; mindestens 10 Minuten) und Synchronize now.

Ein Spiegel nimmt keine Pushes an, deshalb können Sie Ihren eigenen Workflow nicht dort ablegen. Eine Synchronisierung führt nur die Workflows aus, die das Repository des Autors selbst in .forgejo/workflows/ mitbringt, und fzy hat keine. Der Build liegt daher in einem eigenen Repository, das den Spiegel liest.

03Ein eigenes Paketierungsprojekt

Öffnen Sie Neues Projekt auf der Seite Git oder über die Befehlspalette (Rolle developer). Die Anleitung Ihr eigenes App Center führt durch jeden Schritt; für dieses Beispiel gilt:

1. Vorlage: QPKG-Paket.
2. Name: fzy. Dienst: Kommandozeilenwerkzeug, das das Programm nach /usr/bin verlinkt, solange das Paket läuft.
3. Build-Umgebung: ubuntu2404-builder, die Umgebung, die der Workflow verwendet.
4. Drücken Sie Projekt anlegen. Das Projekt erhält sein Repository, den Ordner projects/fzy und den Workflow der Vorlage, den Abschnitt 05 ersetzt.

Bei einem Repository, das vor dem Einschalten von CI angelegt wurde, sind die Actions von Forgejo ausgeschaltet; ein gepushter Workflow startet dann nichts. Schalten Sie sie in den Einstellungen des Repositorys unter Units ein; Repositories, die bei eingeschalteter CI angelegt wurden, haben sie bereits eingeschaltet.

04Ein Nur-Lese-Token für den Spiegel

Der Job klont den Spiegel über HTTPS. Nur wenn der Spiegel öffentlich ist und Öffentliches Durchsuchen eingeschaltet ist, klappt dieser Klon ohne Anmeldung. Sonst braucht er eine, und der Workflow gibt ihm dafür ein Token, das nur lesen darf.

1. Öffnen Sie in Forgejo Einstellungen → Anwendungen → Neues Token generieren. Geben Sie einen Namen wie mirror-read ein und wählen Sie die Berechtigung Repository: Lesen. Kopieren Sie das Token: Forgejo zeigt es nur einmal an.
2. Öffnen Sie im Paketierungs-Repository Einstellungen → Aktionen → Secrets → Secret hinzufügen. Tragen Sie als Namen MIRROR_TOKEN und als Wert das Token ein.

05Der Workflow

Legen Sie diese Datei als .forgejo/workflows/build.yml ins Projekt, anstelle der Datei aus der Vorlage, und pushen Sie sie. Der Workflow läuft bei jedem Push, einmal täglich und wenn Sie ihn von Hand starten.

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

• Der zweite Schritt nimmt das neueste Tag des Spiegels; so folgt das Paket den Releases des Autors, und die Version dieses Tags wird zur Version des Pakets (QPKG_VER).
• bvs env run ubuntu2404-builder -- … baut und testet innerhalb der Umgebung mit deren Compiler und Bibliotheken. Ein fehlschlagender Test lässt den Lauf scheitern, und es wird nichts gepackt.
• bvs qbuild baut das Paket in build/. Der Lauf bewahrt es als Artefakt auf.
• Der letzte Schritt veröffentlicht in das App-Center-Repository des NAS, das nur code-signierte Pakete annimmt. Ohne Zertifikat endet der Lauf mit einer Warnung, und das Paket bleibt ein Artefakt. Der Leitfaden Ihr eigenes App Center zeigt die zwei Schritte, mit denen jeder Build signiert wird.

06Läufe, Tests und das Paket

Der Tab Aktionen des Repositorys listet jeden Lauf auf, zusammen mit seinem Auslöser: ein Push, der Zeitplan oder eine Person.

Ein Lauf zeigt jeden Schritt mit seiner Dauer. Der Schritt mit den Tests zeigt die Ergebnisse der Tests des Autors.

Workflow ausführen startet ihn von Hand, etwa direkt nach Jetzt synchronisieren beim Spiegel. Das Paket finden Sie unter Artefakte auf der Seite des Laufs.