鏡像作者的 Git、執行測試、建置 QPKG：您的 NAS 上的 CI

Forgejo 在您的 NAS 上保存一份程式儲存庫的拉取鏡像。另一個獨立的打包專案每天都會在 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 上執行每個工作。因此，能把工作流程推送到儲存庫的人，就能以管理員身分在 NAS 上執行指令：請只把推送權限交給您放心告知 NAS 管理員密碼的人。

02鏡像作者的儲存庫

1. 在 Forgejo 中（Git 頁面上的 開啟 Forgejo）按 + → 新增遷移 → Git。
2. 貼上作者儲存庫的位址，此處為 https://github.com/jhawthorn/fzy.git；勾選 This repository will be a mirror，將其命名為例如 fzy-upstream，然後按下 Migrate repository。
3. 鏡像會自行拉取作者的提交與標籤。鏡像的 設定 中有 鏡像間隔（預設 8 小時，最短 10 分鐘）與 立即同步。

鏡像不接受推送，所以您無法把自己的工作流程放進去。同步時只會執行作者儲存庫本身在 .forgejo/workflows/ 中附帶的工作流程，而 fzy 沒有。因此，建置要放在您自己的另一個儲存庫中，由它讀取鏡像。

03您自己的打包專案

從 Git 頁面或命令面板（開發者角色）開啟 新專案。指南 您自己的 App Center 會逐步說明每個步驟；這個範例的設定如下：

1. 範本：QPKG 套件。
2. 名稱：fzy。服務：命令列工具，套件執行時會將程式連結到 /usr/bin。
3. 建置環境：ubuntu2404-builder，即工作流程所用的環境。
4. 按 建立專案。專案會取得其儲存庫、資料夾 projects/fzy，以及範本的工作流程（第 05 節會將其取代）。

在啟用 CI 之前建立的儲存庫，其 Forgejo Actions 是關閉的，推送的工作流程不會啟動任何工作。請在儲存庫的 設定 → 單元 中開啟它們；CI 開啟期間建立的儲存庫，Actions 已經是開啟的。

04鏡像的唯讀權杖

工作會透過 HTTPS 複製鏡像。除非鏡像是公開的，且已開啟公開瀏覽，否則這次複製需要登入，而工作流程會給它一個只能讀取的權杖。

1. 在 Forgejo 中：設定 → Applications → Generate new token：名稱例如 mirror-read，權限 套件庫：Read。複製權杖：Forgejo 只會顯示一次。
2. 在打包儲存庫中：設定 → 動作 → Secrets → Add secret：名稱為 MIRROR_TOKEN，值為該權杖。

05工作流程

把這個檔案存成專案中的 .forgejo/workflows/build.yml，取代範本的檔案，然後推送。它會在每次推送時、每天一次，以及手動觸發時執行。

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

• 第二個步驟會取得鏡像最新的標籤，所以套件會跟著作者的發行版走，標籤的版本也會成為套件的版本（QPKG_VER）。
• bvs env run ubuntu2404-builder -- … 會在環境中用它的編譯器與程式庫建置並測試。測試失敗時，這次執行就會失敗，也不會打包任何東西。
• bvs qbuild 會在 build/ 中建置套件。這次執行會把套件保存為產出物。
• 最後一個步驟會發佈到 NAS 的 App Center 儲存庫，該儲存庫只接受經程式碼簽署的套件。沒有憑證時，執行會以警告結束，套件則保留為產出物。指南 您自己的 App Center 說明了讓每次建置都簽章的兩個步驟。

06執行、測試與套件

儲存庫的 動作 分頁會列出每次執行，以及是什麼啟動了它：推送、排程，或某個人。

每次執行會顯示各步驟及其耗時。含測試的步驟會印出作者自己的測試結果。

Run workflow 會手動啟動執行，例如在鏡像的 Synchronize now 之後立即執行。套件位於該次執行頁面的 Artifacts 下。