作者のGitをミラーし、テストを実行し、QPKGをビルドする:NAS上のCI

NAS上のForgejoは、あるプログラムのリポジトリのプルミラーを保持します。それとは別のパッケージング用プロジェクトが、NAS自身のランナーで、作者の最新リリースを毎日ビルドし、作者のテストを実行して、QPKGを作ります。例はfzyで、C言語で書かれた小さなファジーファインダー(MITライセンス)です。

1. モジュールGit、CI、エディター
2. ミラー作者のリポジトリ
3. プロジェクト新しいプロジェクト、QPKGパッケージ
4. ワークフロー取得、テスト、ビルド
5. 実行毎日、プッシュ時、手動

画像は、このガイドの説明どおりに各欄を入力した Bucket & Code Server IDE のパネルと Forgejo から取ったものです。アカウント名は ola です。

01始める前に

• Git、CI、エディターがオンになっている必要があります。オフのモジュールには、概要 のタイルと、そのモジュール自身のページにボタンがあります: 「Git」をオンにする、「エディター」をオンにする、Git がまだオフのときは 「Git」と「CI」をオンにする。
• QDK がインストールされている必要があります。ツールチェーン ページの QNAP タブで QNAP QDK 2.5.0 をインストールしてください。
• Ubuntu 24.04 のビルダー環境が必要です。アプリ → 例 か、新しいアプリのページの Builder 環境を作成 で用意します。ワークフローはこの環境でビルドします。
• NAS がインターネットに接続できる必要があります。actions/checkout と actions/upload-artifact は data.forgejo.org から取得され、ミラーは作者のサーバーから取得します。

NAS上のランナーは、runs-on に自分のラベル(例:bucketvs)が指定されたジョブを受け取ります。ランナーは、すべてのジョブを NAS 上で直接、管理者 (admin) として実行します。そのため、リポジトリにワークフローをプッシュできる人は、NAS 上で管理者としてコマンドを実行できます。NAS の管理者パスワードを渡してもよい人にだけプッシュ権限を与えてください。

02作者のリポジトリをミラーする

1. Forgejo で(Git ページの Forgejo を開く)、+ → New migration → Git を押します。
2. 作者のリポジトリのアドレス（この例では https://github.com/jhawthorn/fzy.git）を貼り付け、This repository will be a mirror にチェックを入れ、例えば fzy-upstream と名付けて Migrate repository を押します。
3. ミラーは作者のコミットとタグを自動的に取得します。設定 には Mirror interval(変更しない場合は 8 時間、最短 10 分)と Synchronize now が表示されます。

ミラーはプッシュを拒否するため、自分のワークフローをそこに入れることはできません。同期で実行されるのは、作者のリポジトリ自体の .forgejo/workflows/ にあるワークフローだけで、fzy にはありません。そのため、ビルドは、ミラーを読み込む自分のリポジトリに置きます。

03自分用のパッケージングプロジェクト

Git ページまたはコマンドパレット(developer ロール)から 新しいプロジェクト を開きます。ガイド 独自の App Center で各手順を説明しています。この例では次のとおりです:

1. テンプレート:QPKG パッケージ。
2. 名前:fzy。サービス:コマンドラインツール(パッケージの実行中、プログラムを /usr/bin にリンクします)。
3. ビルド環境:ubuntu2404-builder、ワークフローが使う環境です。
4. プロジェクトを作成 を押します。プロジェクトには、リポジトリ、フォルダ projects/fzy、テンプレートのワークフローが作られます。ワークフローは 05 節で置き換えます。

CI をオンにする前に作られたリポジトリでは、Forgejo の Actions がオフになっており、プッシュしたワークフローは何も起動しません。リポジトリの 設定 → Units でオンにしてください。CI をオンにした状態で作られたリポジトリでは、すでにオンになっています。

04ミラー用の読み取り専用トークン

ジョブはHTTPSでミラーをクローンします。ミラーが公開されていて、しかも公開閲覧がオンになっている場合を除き、このクローンにはサインインが必要です。そのため、ワークフローは読み取りしかできないトークンをクローンに渡します。

1. Forgejo で 設定 → Applications → Generate new token：名前は mirror-read など、権限は リポジトリ：Read。トークンをコピーしてください。Forgejo はこれを一度しか表示しません。
2. パッケージング用リポジトリで 設定 → アクション → Secrets → Add secret：名前は MIRROR_TOKEN、値にはトークンを入力します。

05ワークフロー

このファイルを、テンプレートのファイルの代わりに、プロジェクトの .forgejo/workflows/build.yml として置き、プッシュしてください。このワークフローは、プッシュのたびと 1 日 1 回自動で実行され、手動でも実行できます。

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

• 2番目のステップではミラーの最新タグを取得するので、パッケージは作者のリリースに追従し、そのバージョンがパッケージのバージョン（QPKG_VER）になります。
• bvs env run ubuntu2404-builder -- … は、コンパイラとライブラリを備えた環境の中でビルドとテストを実行します。テストが失敗すると実行全体が失敗し、何もパックされません。
• bvs qbuild は build/ にパッケージをビルドします。実行は、そのパッケージをアーティファクトとして保存します。
• 最後のステップは、NASのApp Centerリポジトリへの公開です。このリポジトリはコード署名済みのパッケージしか受け付けません。証明書がなければ、実行は警告付きで終わり、パッケージはアーティファクトとして残ります。ガイド 独自の App Center では、すべてのビルドに署名する2つの手順を紹介しています。

06実行、テスト、パッケージ

リポジトリの アクション タブには、すべての実行と、そのきっかけ（プッシュ、スケジュール、または人）が一覧表示されます。

実行の画面には各ステップと所要時間が表示されます。テストのステップでは、作者自身のテスト結果が出力されます。

Run workflow で手動で開始できます。たとえばミラーの Synchronize now の直後などに使います。パッケージは実行のページの Artifacts にあります。