Windows 安裝 Gitea Runner 教學：支援 MSBuild 建置、註冊與開機自動啟動設定

本篇要解決的問題

當我們想在 Push 程式碼後自動執行建置、測試或掃描，卻發現專案依賴 Windows MSBuild、傳統 .NET Framework Web 或其他 Windows 專用環境時，就需要一台 Windows 主機來執行這些工作。

這時，我們就需要在 Windows 主機上安裝 Gitea Runner，讓 Gitea Actions 把工作交給它。

如果你要看的不是在 Windows 上安裝 Gitea Runner，而是用 Docker 安裝就可以的話，請移駕下面這篇，有開一個段落寫怎麼用 Docker 安裝：
使用 Gitea Actions 與 OpenAI 實現自動化 PR Code Review。

Gitea 負責安排工作，Runner 負責執行，本筆記文使用直接執行 gitea-runner.exe 的方式，不需要安裝 Docker。

以下以需要 MSBuild 的 .NET 專案示範，建立一個讓多個專案共用的 Windows Runner。

範例設定如下，請把 Gitea 網址換成你的實際網址：

如果主機沒有 D 槽，可改用 C:\August\GiteaRunner，然後後面寫到的指令、啟動腳本與排程中的資料夾路徑都要一起替換。

全程使用同一個 Windows 帳號註冊、啟動與設定排程，安裝工具時才使用管理員權限。

1. 準備 Windows 上的工具

Runner 只會接工作，建置工具要另外安裝在同一台 Windows 主機。

如果已有符合需求的工具，可以沿用。

PATH 是命令列用來找程式的清單，加入 PATH 後，Runner 才能用 git、node 等名稱找到程式。

舊專案要先確認 Visual Studio 版本支援目標框架，必要時使用 VS 2019 Build Tools。

例如專案目標是 .NET Framework 4.8，就需要 4.8 的 targeting pack，只有 Runtime 不夠。

安裝完成後，按 Win + R，輸入 powershell，按 Enter。

本文指令都在 PowerShell 執行。

git --version node --version $PSVersionTable.PSVersion 

Git、Node 應顯示版本，Git 至少為 2.34.1，Windows PowerShell 至少為 5.1。

若顯示找不到指令，先重新開啟 PowerShell 後再試一次，如果又找不到，要先確認該工具已安裝並加入 PATH。

同時，這台 Windows 主機也要能連到我們的 Gitea，以及 workflow 使用的 action、套件與工具下載來源。

2. 下載 Windows Runner

本文以 5.0.0 示範。

Runner 更新頻繁，部署前請到官方下載頁確認最新版本。

換版本時，下面的檔名、下載連結與校驗指令都要一起替換。

Gitea 需為 1.21 以上。

在 PowerShell 建立資料夾：

New-Item -ItemType Directory -Path 'D:\August\GiteaRunner' -Force | Out-Null Set-Location 'D:\August\GiteaRunner' 

下載以下兩個檔案，放進這個資料夾：

• Windows AMD64 Runner
• 對應的 SHA256 校驗檔

校驗檔用來比對下載內容是否完整，貼上以下的指令，完成比對後，程式會將檔案改名為 gitea-runner.exe：

& { $ErrorActionPreference = 'Stop' $expectedHash = ((Get-Content '.\gitea-runner-5.0.0-windows-amd64.exe.sha256' -Raw).Trim() -split '\s+')[0] $actualHash = (Get-FileHash '.\gitea-runner-5.0.0-windows-amd64.exe' -Algorithm SHA256).Hash if ($expectedHash -notmatch '^[0-9a-fA-F]{64}$' -or $actualHash -ine $expectedHash) { throw '校驗失敗；先停止操作，重新下載兩個官方檔案。' } if (Test-Path '.\gitea-runner.exe') { throw '已有 gitea-runner.exe；先確認既有安裝，不要覆蓋。' } Rename-Item '.\gitea-runner-5.0.0-windows-amd64.exe' 'gitea-runner.exe' .\gitea-runner.exe --version } 

最後應顯示版本 5.0.0。

如果出現紅色錯誤，先修正再繼續。

已完成校驗與改名時，直接執行 .\gitea-runner.exe --version 確認即可。

Runner 是命令列工具，雙擊 EXE 時若看到「You need to open cmd.exe」，請回到 PowerShell 執行上述指令。

3. 註冊一個多專案共用的 Runner

若要讓多個專案共用，請用 Gitea 全站管理員帳號開啟：

https://gitea.example.com/-/admin/actions/runners 

先換成自己的 Gitea 網址，再按「建立 Runner」，取得 Registration Token（註冊碼）。

註冊碼決定 Runner 的使用範圍：

• 全站管理頁取得的註冊碼可建立全站 Runner。
• 單一專案的註冊碼只供該專案使用。

若只想讓某個組織共用，也可以在該組織的 Settings → Actions → Runners 取得註冊碼。

回到 PowerShell，把 --instance 換成你的 Gitea 網址後貼上。

出現「貼上註冊碼後按 Enter」時，貼上剛取得的註冊碼：

& { $ErrorActionPreference = 'Stop' Set-Location 'D:\August\GiteaRunner' if (Test-Path '.\.runner') { throw '這個資料夾已經註冊過；先確認既有 Runner。' } $env:GITEA_RUNNER_REGISTRATION_TOKEN = Read-Host '貼上註冊碼後按 Enter' try { .\gitea-runner.exe register --no-interactive `  --instance 'https://gitea.example.com' `  --name 'letswrite-windows-runner' `  --labels 'windows:host' } finally { Remove-Item Env:GITEA_RUNNER_REGISTRATION_TOKEN -ErrorAction SilentlyContinue } } 

5.0.0 只執行 register、不帶參數時，不會詢問註冊碼，而是直接顯示 missing token, token-file argument, or GITEA_RUNNER_REGISTRATION_TOKEN environment variable 並結束。

所以這裡改用環境變數傳入註冊碼，其他設定直接寫在指令裡。

註冊碼只存在這次執行中，不會留在指令紀錄。

畫面出現 WARN Runner in user-mode. 是正常訊息，表示用一般帳號執行。

看到 Runner registered successfully. 就是註冊成功。

註冊成功後，資料夾會出現 .runner。它可能是隱藏檔，裡面含憑證，請保留在本機、限制讀取權限，不要提交到 Git 或貼出內容。

如果之前註冊成單一專案 Runner，只改名稱不會變成全站共用。

要先停止 Runner 與排程、在 Gitea 移除舊 Runner，再把本機 .runner 改名備份，使用新的全站註冊碼重新註冊。

4. 找到建置工具，再啟動 Runner

先在 PowerShell 查詢 VsDevCmd.bat 的路徑，它會準備 Visual Studio 的命令列建置環境：

& "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -latest -products '*' -requires Microsoft.Component.MSBuild -find 'Common7\Tools\VsDevCmd.bat' 

路徑會依安裝的版本與版次而不同，例如 VS 2022 Build Tools 會是：

C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\Common7\Tools\VsDevCmd.bat 

請使用你查到的實際路徑，若沒有輸出，要確認 Build Tools 已安裝。

若專案限定 VS 2019，可在查詢中加入 -version '[16.0,17.0)'，避免選到其他版本。

用記事本建立 D:\August\GiteaRunner\run-runner.cmd，儲存類型選「所有檔案」，避免存成 .cmd.txt。

貼入以下內容，將 call 那行換成剛才查到的路徑，保留雙引號：

@echo off setlocal cd /d "D:\August\GiteaRunner" if errorlevel 1 exit /b 1 call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\Common7\Tools\VsDevCmd.bat" if errorlevel 1 exit /b 1 "D:\August\GiteaRunner\gitea-runner.exe" daemon >> "D:\August\GiteaRunner\runner.log" 2>&1 exit /b %errorlevel% 

回到 PowerShell 啟動：

Set-Location 'D:\August\GiteaRunner' .\run-runner.cmd 

這個視窗會持續執行，回到 Gitea 管理頁，確認 letswrite-windows-runner 顯示 Online，Label 為 windows。

若程式立即結束，先確認 VsDevCmd.bat 路徑，再另開 PowerShell 查看紀錄：

Get-Content 'D:\August\GiteaRunner\runner.log' -Tail 30 

排查時，不要公開 .runner 或含憑證的紀錄。

共用 Runner 會直接執行專案程式碼，請用一般帳號運行，並只供可信任的專案使用。

5. 設定開機自動啟動

先在手動啟動的視窗按 Ctrl + C 停止 Runner，避免同一份註冊資料同時執行兩次。

開啟 Windows「工作排程器」→「建立工作」，依下表設定：

儲存時，在 Windows 提示視窗輸入該帳號的密碼。不要勾「不儲存密碼／僅能存取本機資源」，讓排程可以使用該帳號的網路資源。

右鍵執行工作，確認 Runner 回到 Online。

安排時間重新開機，再確認尚未登入時也能 Online。

若帳號權限導致排程失敗，請管理員檢查「作為批次工作登入」權限。

主機保持開機且不休眠時，Runner 才能接工作。

後續各專案的 Windows 工作指定 runs-on: windows，並使用 shell: powershell。

例如下面是一段 job 設定，放進你既有 workflow 的 jobs 底下：

windows-check: runs-on: windows steps: - name: 確認 Windows 執行環境 shell: powershell run: | $PSVersionTable.PSVersion git --version node --version 

Runner Online 表示已經能接工作。

Push 何時觸發、要建置或掃描哪個專案，仍由各專案 .gitea/workflows/ 裡的 workflow 決定。

共用 Runner 只需安裝一次，各專案各自保留自己的指令與 Secrets。

本文示範直接在 Windows 主機執行的工作。

若 workflow 另外使用 container、services 或 docker:// action，仍須準備對應的 Docker 環境。