Runner 進階應用與虛擬機實戰

# 1. 建立目錄並下載
$ mkdir actions-runner && cd actions-runner
$ curl -o actions-runner-osx-x64.tar.gz -L \
  https://github.com/actions/runner/releases/download/v2.x.x/actions-runner-osx-x64-2.x.x.tar.gz
$ tar xzf ./actions-runner-osx-x64.tar.gz

# 2. 設定
$ ./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO \
              --token YOUR_TOKEN \
              --labels macos,self-hosted

# 3. 安裝為 launchd 服務
$ ./svc.sh install
$ ./svc.sh start

# 1. 在 PowerShell 中下載並解壓縮
mkdir actions-runner; cd actions-runner
Invoke-WebRequest -Uri https://github.com/actions/runner/releases/download/v2.x.x/actions-runner-win-x64-2.x.x.zip -OutFile actions-runner-win-x64.zip
Add-Type -AssemblyName System.IO.Compression.FileSystem
[System.IO.Compression.ZipFile]::ExtractToDirectory("$PWD\actions-runner-win-x64.zip", "$PWD")

# 2. 設定
.\config.cmd --url https://github.com/YOUR_ORG/YOUR_REPO --token YOUR_TOKEN

# 3. 安裝為 Windows 服務
.\svc.cmd install
.\svc.cmd start

Service Container 可以在 Job 旁邊啟動資料庫、快取等服務。服務名稱就是 hostname，無需額外設定。

name: Service Container 範例
on: push

jobs:
  integration-test:
    runs-on: ubuntu-latest

    services:
      postgres:                    # hostname = "postgres"
        image: postgres:16
        env:
          POSTGRES_USER: testuser
          POSTGRES_PASSWORD: testpass
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

      redis:                       # hostname = "redis"
        image: redis:7-alpine
        ports:
          - 6379:6379

    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run test:integration
        env:
          DATABASE_URL: postgres://testuser:testpass@localhost:5432/testdb
          REDIS_URL: redis://localhost:6379

將所有專案依賴預裝在自製 Image 中，大幅縮短每次 CI 的安裝時間。

步驟 1：撰寫 Dockerfile

# .docker/ci.Dockerfile
FROM node:20-slim

# 安裝系統依賴
RUN apt-get update && apt-get install -y \
    python3 make g++ \
    && rm -rf /var/lib/apt/lists/*

# 預裝全域工具
RUN npm install -g typescript eslint

WORKDIR /app

步驟 2：在 Workflow 中使用

name: 使用自製 Image
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/my-org/ci-image:latest   # 從 Container Registry 拉取
      credentials:
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}

    steps:
      - uses: actions/checkout@v4
      - run: npm ci                # 系統依賴已預裝，安裝極快
      - run: npm run build
      - run: npm test

Artifact 用於在不同 Job 之間傳遞檔案，或保存建置產物供事後下載。

name: Artifact 跨 Job 傳遞
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build

      # 上傳建置產物
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/
          retention-days: 7        # 保留 7 天

  deploy:
    needs: build                    # 等 build 完成才執行
    runs-on: ubuntu-latest
    steps:
      # 下載前一個 Job 的產物
      - uses: actions/download-artifact@v4
        with:
          name: build-output
          path: dist/

      - run: echo "部署 dist/ 內容到伺服器..."

Workflow 出問題時，以下技巧能幫你快速定位問題：

① 啟用 Step Debug Logging

# 在 Repo → Settings → Secrets → Actions 中新增：
#   Name:  ACTIONS_STEP_DEBUG
#   Value: true
# 重新執行 Workflow，每個 Step 會顯示詳細的除錯資訊。

② SSH 進入 Runner 互動除錯

# 在 Workflow 中加入此 Step，執行時會暫停並提供 SSH 連線
- name: 互動除錯（SSH）
  uses: mxschmitt/action-tmate@v2
  if: failure()                # 只在失敗時啟動
  with:
    limit-access-to-actor: true   # 僅允許觸發者連線

③ 寫入 Step Summary

# 用 $GITHUB_STEP_SUMMARY 在 Actions 頁面顯示自訂 Markdown 摘要
- name: 產生測試報告摘要
  run: |
    echo "## 🧪 測試結果" >> $GITHUB_STEP_SUMMARY
    echo "| 類別 | 通過 | 失敗 |" >> $GITHUB_STEP_SUMMARY
    echo "|------|------|------|" >> $GITHUB_STEP_SUMMARY
    echo "| 單元測試 | 42 | 0 |" >> $GITHUB_STEP_SUMMARY
    echo "| 整合測試 | 18 | 1 |" >> $GITHUB_STEP_SUMMARY