Cloudflare CI 是什麼？用 Workflows 與 Sandbox 做 CI 前先看邊界

Cloudflare CI 的工作分界#

官方 package README 特別強調，runner command 會位於可重試的 Workflow step 中；只要 command 有外部副作用，就必須具備 idempotency。另一方面，CiRunnerResult.logs 是原始 command output，不會自動替你遮蔽 secret；只有 provider notification preview 與 failure message 會做遮蔽。

這兩個條件決定了它的使用方式：把 runner 當成受 Workflow 重試控制的建置環境，而不是把任意 shell script 原封不動搬進雲端。

先用官方 Artifacts example 理解觸發路徑#

官方的 cloudflare-artifacts example 不是「部署後自動掃描任何 Git repository」。它要求你事先建立並填入 Cloudflare Artifacts repository，pipeline 會接收 cf.artifacts.repo.pushed event；如果 namespace 或 repo name 和 wrangler.jsonc 的 trigger filter 不一致，pipeline 不會啟動。

這個邊界很適合用來做第一個 smoke test：先讓一個測試 repository 觸發 install、平行的 lint／test／typecheck／build，最後再執行 deploy。不要一開始就把 production repository、正式 deployment account 和 self-healing agent 一起接上，否則很難分辨是事件、Sandbox、Workflow 還是權限問題。

安裝與 Worker 設定不是同一個步驟#

官方 README 的安裝指令很短：

1
pnpm add @cloudflare/ci

但 package 直接發佈 Workers 取向的 TypeScript source，並不提供直接執行的 Node.js build。若 Worker 需要從 @cloudflare/ci/worker 匯入 reusable primitive，還要在 Wrangler 設定啟用 nodejs_compat。真正的 HTTP route、Queue handler、Workflow class 與 Wrangler bindings 都仍屬於你的應用程式。

一個 runner pipeline 的核心概念大致如下，實際型別參數與 bindings 應以 官方 Artifacts example 為準：

1
const deps = await ci.runner({
2
  name: 'install',
3
  command: 'npm ci',
4
  cache: { inputs: ['package.json', 'package-lock.json'] },
5
})
6

7
await Promise.all([
8
  deps.runner({ name: 'lint', command: 'npm run lint' }),
9
  deps.runner({ name: 'test', command: 'npm run test' }),
10
  deps.runner({ name: 'typecheck', command: 'npm run typecheck' }),
11
  deps.runner({ name: 'build', command: 'npm run build' }),
12
])

這個寫法表達的是「安裝完成後平行驗證」的依賴關係，不代表每個專案都應該平行執行所有步驟。若 build 會修改同一個共享目錄、test 會啟動固定 port，先在 Sandbox 裡確認隔離條件，再調整平行度。

部署前要先處理副作用與 secret#

目前適合與不適合的情境#

適合先試的情境，是你想把 Cloudflare Artifacts push event 連到一個 Workers-native pipeline，並且願意自己管理 Wrangler config、Sandbox image、資源、secret 與通知。可以從單一測試 repository 開始，先只跑 install、test 與 build，再加入 deploy。

不適合直接當成既有 CI 的無痛替換，尤其是你需要大量現成 SaaS integration、成熟的權限 UI、跨雲 runner fleet，或 pipeline 依賴 Node.js 原生環境而不是 Workers／Sandbox。官方 repository 目前仍是 0.1.0，導入前要鎖定版本、閱讀 changelog 與 example 的 lockfile，並在測試 account 先驗證重試和 log 邊界。

Cloudflare CI 的價值不在於把 YAML 換成另一套語法，而在於把 CI 的事件、可重試流程與執行環境放進 Cloudflare runtime。先把「誰觸發、哪裡執行、什麼可以重試、哪些 log 會原樣留下」回答清楚，再決定是否值得為這個邊界承擔早期元件的整合成本。

常見問題#