這篇用 GitHub Actions 從零做到「推 code 到 main → 自動 build → 自動部署」。概念的部分可以先看 What is CI/CD?；GitLab 的做法我另外寫在 GitLab CI/CD 實作，兩篇可以對照著看。

重點會放在 self-hosted runner——也就是把 job 跑在你自己的機器上。因為很多實際場景（部署目標在內網 / 校內網路、需要 GPU、要碰私有資源）下，GitHub 的雲端 runner 根本連不進去，一定得自架 runner。這也是我在一個部署到內網主機的專案裡實際採用的方式，過程踩到的坑一併記下來。

一、GitHub Actions 的組成

一個 workflow 就是一個 YAML 檔，放在 repo 的 .github/workflows/ 底下（可以有很多份，各自獨立觸發）。階層是：

• on：什麼事件會觸發（push、pull_request、排程、手動…）。
• jobs：一個 workflow 底下的工作；每個 job 用 runs-on 指定跑在哪種 runner。
• steps：job 內依序執行的步驟。run: 執行 shell 指令；uses: 套用別人寫好的 Action（例如 actions/checkout 幫你 clone 程式碼）。
• Action：可重用的封裝步驟，是 GitHub Actions 生態的核心（相當於把常見動作模組化）。

二、GitHub-hosted vs self-hosted runner

Job 一定要有 runner 來執行，有兩種：

• GitHub-hosted：GitHub 提供的雲端機器（runs-on: ubuntu-latest）。免安裝、用完即丟，適合純測試 / build / 公開部署。
• self-hosted：你自己的機器上跑一個 runner agent，runs-on: [self-hosted, <label>]。

三、安裝並註冊 self-hosted runner

到 repo 的 Settings → Actions → Runners → New self-hosted runner，選對 OS 與架構（x64 或 ARM64——ARM 機器一定要選 ARM64，抓錯版本會跑不起來），GitHub 會給你一段安裝指令。核心就三步：

# 1) 下載並解壓 runner（版本 / 架構依頁面提供的為準）
mkdir actions-runner && cd actions-runner
curl -o runner.tar.gz -L https://github.com/actions/runner/releases/download/vX.Y.Z/actions-runner-linux-arm64-X.Y.Z.tar.gz
tar xzf runner.tar.gz

# 2) 註冊到這個 repo（token 從上面那頁複製，短效約 1 小時）
./config.sh --url https://github.com/OWNER/REPO \
  --token YOUR_REGISTRATION_TOKEN \
  --labels my-runner \
  --unattended

# 3) 先手動跑跑看
./run.sh

• --labels：自訂標籤，workflow 用 runs-on: [self-hosted, my-runner] 指定要用它。
• 註冊成功後，Runners 頁面會出現一個 Idle（綠色） 的 runner，代表已上線待命。
• checkout 用的是 GitHub 自動注入的 GITHUB_TOKEN，所以 runner 不需要另外設 SSH key 就能 clone 私有 repo。

把 runner 設成常駐服務

./run.sh 一關掉就停了。要讓它開機自啟、登出不死，得設成服務。官方提供 svc.sh，但它會裝系統層級的 systemd 服務、需要 root：

sudo ./svc.sh install    # 安裝成系統服務
sudo ./svc.sh start      # 啟動
sudo ./svc.sh status

# 讓自己的 user services 在登出後仍常駐（開機自動起）
loginctl enable-linger "$USER"

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/gh-runner.service <<'EOF'
[Unit]
Description=GitHub Actions self-hosted runner
After=network-online.target

[Service]
WorkingDirectory=%h/actions-runner
ExecStart=%h/actions-runner/run.sh
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now gh-runner.service

# gh-runner.service 的 ExecStart 改成：
ExecStart=/usr/bin/sg docker -c "%h/actions-runner/run.sh"

四、撰寫 workflow

在 repo 根目錄建立 .github/workflows/deploy.yml，GitHub 偵測到就會依 on 的事件自動驅動。基本結構：

name: Deploy

on:
  push:
    branches: [main]      # 只在推到 main 時觸發
  workflow_dispatch: {}   # 也允許在網頁上手動按一下觸發

jobs:
  deploy:
    runs-on: [self-hosted, my-runner]   # 指定用我們的 runner
    steps:
      - uses: actions/checkout@v4       # 現成 Action：clone 程式碼
      - run: echo "hello CI"            # 一行指令

五、實作範例：push → build → deploy

以「把服務容器化、在 self-hosted runner 上直接 build 並用 Docker Compose 重啟」為例。因為 runner 就跑在部署主機上（且在 docker 群組裡），可以直接操作本機 Docker，連推 registry、SSH 都免了：

name: Deploy to server

on:
  push:
    branches: [main]
  workflow_dispatch: {}

# 同時只跑一個部署，後到的排隊、不互相打架
concurrency:
  group: deploy
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: [self-hosted, my-runner]
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Provide production env
        # 機密放在部署主機上（見下一節），部署時才複製進工作目錄
        run: cp "$HOME/.config/myapp/env.prod" .env

      - name: Build & deploy
        run: docker compose -f docker-compose.prod.yml --env-file .env up -d --build --remove-orphans

      - name: Prune old images
        run: docker image prune -f

name: myapp        # 固定專案名稱
services:
  db:
    # ...

六、Secrets 管理

機密（DB 密碼、API key…）絕對不要寫進 workflow 或 commit 進 repo。兩種常見做法：

      - name: Deploy
        run: |
          echo "DB_PASSWORD=${{ secrets.DB_PASSWORD }}" >> .env
          docker compose --env-file .env up -d --build

      - name: Provide env
        run: cp "$HOME/.config/myapp/env.prod" .env

# 主機上（只做一次）：產生機密檔並收好權限
mkdir -p ~/.config/myapp
umask 077
cat > ~/.config/myapp/env.prod <<'EOF'
DB_PASSWORD=一組夠強的隨機密碼
DJANGO_SECRET_KEY=一長串隨機字串
EOF
chmod 600 ~/.config/myapp/env.prod

七、保護 main 分支

和 GitLab 一樣，實務上讓 main 只能透過 Pull Request 合併：開發者在自己分支開發 → 開 PR → 通過 review / 檢查才 merge → 觸發部署。到 Settings → Branches 加一條 branch protection rule（要求 PR、要求檢查通過），就能避免把有問題的 code 直接推上線。

小結

GitHub Actions 的最大優勢是 uses: 的 Action 生態（很多事有現成模組），而 self-hosted runner 讓你能把 CI/CD 延伸到內網、私有硬體的環境——runner 主動對外連 GitHub，不必為內網開任何 inbound 埠，這點對校內 / 公司內部的部署特別實用。核心心智模型和 GitLab 幾乎一樣，遷移成本不高。