workers-ci-cd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare Workers CI/CD

Status: ✅ Production Ready | Last Verified: 2025-01-27 GitHub Actions: v4 | GitLab CI: Latest | Wrangler: 4.50.0

状态: ✅ 可用于生产环境 | 上次验证时间: 2025-01-27 GitHub Actions版本: v4 | GitLab CI版本: 最新版 | Wrangler版本: 4.50.0

What Is Workers CI/CD?

什么是Workers CI/CD？

Automated testing and deployment of Cloudflare Workers using GitHub Actions or GitLab CI. Enables running tests on every commit, deploying to preview/staging/production environments automatically, managing secrets securely, and implementing deployment gates for safe releases.

Key capabilities: Automated testing, multi-environment deployments, preview URLs per PR, secrets management, deployment verification, automatic rollbacks.

通过GitHub Actions或GitLab CI实现Cloudflare Workers的自动化测试与部署。支持每次提交时自动运行测试、自动部署到预览/预发/生产环境、安全管理密钥、配置部署闸门保障发布安全。

核心能力: 自动化测试、多环境部署、每个PR对应独立预览URL、密钥管理、部署验证、自动回滚。

New in 2025

2025年新特性

GitHub Actions Updates (January 2025):

NEW:
```
cloudflare/wrangler-action@v4
```
(improved caching, faster deployments)
IMPROVED: Secrets support with
```
vars
```
and
```
secrets
```
parameters
ADDED: Built-in preview environment cleanup
BREAKING:
```
apiToken
```
renamed to
```
api-token
```
(kebab-case)

Migration from v3:

yaml

undefined

GitHub Actions更新（2025年1月）:

新增:
```
cloudflare/wrangler-action@v4
```
（优化缓存，部署速度更快）
改进: 支持通过
```
vars
```
和
```
secrets
```
参数配置密钥
新增: 内置预览环境清理功能
不兼容变更:
```
apiToken
```
重命名为
```
api-token
```
（短横线命名法）

从v3版本迁移:

yaml

undefined

❌ OLD (v3)

❌ 旧版（v3）

uses: cloudflare/wrangler-action@3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

uses: cloudflare/wrangler-action@3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

✅ NEW (v4)

✅ 新版（v4）

uses: cloudflare/wrangler-action@v4 with: api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}


**Wrangler 4.50.0** (January 2025):
- **NEW**: `--dry-run` flag for deployment validation
- **IMPROVED**: Faster deployments with parallel uploads
- **ADDED**: `--keep-vars` to preserve environment variables

---

uses: cloudflare/wrangler-action@v4 with: api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}


**Wrangler 4.50.0更新**（2025年1月）:
- **新增**: `--dry-run`参数用于部署前验证
- **改进**: 并行上传能力加快部署速度
- **新增**: `--keep-vars`参数用于保留环境变量

---

Quick Start (10 Minutes)

快速上手（10分钟）

GitHub Actions Setup

GitHub Actions配置

1. Create Cloudflare API Token

Go to: https://dash.cloudflare.com/profile/api-tokens

Create token with permissions:

Account.Cloudflare Workers Scripts - Edit
Account.Cloudflare Pages - Edit (if using Pages)

2. Add Secret to GitHub

Repository → Settings → Secrets → Actions → New repository secret:

Name:
```
CLOUDFLARE_API_TOKEN
```
Value: [paste token]

3. Create
.github/workflows/deploy.yml

yaml

name: Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy to Cloudflare Workers

    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install

      - run: bun test

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy

4. Push and Verify

bash

git add .github/workflows/deploy.yml
git commit -m "Add CI/CD pipeline"
git push

Check Actions tab on GitHub to see deployment progress.

1. 创建Cloudflare API Token

访问地址: https://dash.cloudflare.com/profile/api-tokens

创建具备以下权限的令牌:

Account.Cloudflare Workers Scripts - 编辑权限
Account.Cloudflare Pages - 编辑权限（如果使用Pages）

2. 将密钥添加到GitHub

代码仓库 → 设置 → Secrets → Actions → 新建仓库密钥:

名称:
```
CLOUDFLARE_API_TOKEN
```
值: [粘贴你生成的令牌]

3. 创建
.github/workflows/deploy.yml
文件

yaml

name: Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy to Cloudflare Workers

    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install

      - run: bun test

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy

4. 提交代码并验证

bash

git add .github/workflows/deploy.yml
git commit -m "Add CI/CD pipeline"
git push

查看GitHub的Actions标签页确认部署进度。

Critical Rules

核心规则

1. Never Commit Secrets to Git

1. 永远不要将密钥提交到Git

✅ CORRECT:

yaml

undefined

✅ 正确示例:

yaml

undefined

Use GitHub Secrets

使用GitHub Secrets

api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}


**❌ WRONG**:
```yaml

api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}


**❌ 错误示例**:
```yaml

❌ NEVER hardcode tokens

❌ 永远不要硬编码令牌

api-token: "abc123def456..."


**Why**: Exposed tokens allow anyone to deploy to your account.

api-token: "abc123def456..."


**原因**: 暴露的令牌会导致任何人都可以向你的账户部署服务。

2. Always Run Tests Before Deploy

2. 部署前必须运行测试

✅ CORRECT:

yaml

- run: bun test  # ✅ Tests run first

- name: Deploy
  uses: cloudflare/wrangler-action@v4
  with:
    api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}

❌ WRONG:

yaml

undefined

✅ 正确示例:

yaml

- run: bun test  # ✅ 优先运行测试

- name: Deploy
  uses: cloudflare/wrangler-action@v4
  with:
    api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}

❌ 错误示例:

yaml

undefined

❌ Skipping tests

❌ 跳过测试

name: Deploy uses: cloudflare/wrangler-action@v4
No tests!


**Why**: Broken code shouldn't reach production.

name: Deploy uses: cloudflare/wrangler-action@v4
没有测试步骤！


**原因**: 存在问题的代码不应该发布到生产环境。

3. Use Different Environments

3. 使用多环境隔离部署

✅ CORRECT:

yaml

undefined

✅ 正确示例:

yaml

undefined

Production (main branch)

生产环境（main分支）

name: Deploy to Production if: github.ref == 'refs/heads/main' run: bunx wrangler deploy --env production

name: Deploy to Production if: github.ref == 'refs/heads/main' run: bunx wrangler deploy --env production

Staging (other branches)

预发环境（其他分支）

name: Deploy to Staging if: github.ref != 'refs/heads/main' run: bunx wrangler deploy --env staging


**❌ WRONG**:
```yaml

name: Deploy to Staging if: github.ref != 'refs/heads/main' run: bunx wrangler deploy --env staging


**❌ 错误示例**:
```yaml

❌ Always deploying to production

❌ 所有分支都直接部署到生产环境

run: bunx wrangler deploy


**Why**: Test changes in staging before production.

run: bunx wrangler deploy


**原因**: 变更需要先在预发环境验证再发布到生产。

4. Verify Deployment Success

4. 验证部署是否成功

✅ CORRECT:

yaml

- name: Deploy
  id: deploy
  uses: cloudflare/wrangler-action@v4

- name: Verify Deployment
  run: |
    curl -f https://your-worker.workers.dev/health || exit 1

❌ WRONG:

yaml

undefined

✅ 正确示例:

yaml

- name: Deploy
  id: deploy
  uses: cloudflare/wrangler-action@v4

- name: Verify Deployment
  run: |
    curl -f https://your-worker.workers.dev/health || exit 1

❌ 错误示例:

yaml

undefined

❌ No verification

❌ 没有部署验证步骤

name: Deploy uses: cloudflare/wrangler-action@v4
Assuming it worked...


**Why**: Deployments can fail silently (DNS issues, binding errors).

name: Deploy uses: cloudflare/wrangler-action@v4
默认部署成功...


**原因**: 部署可能会静默失败（比如DNS问题、绑定错误）。

5. Use Deployment Gates for Production

5. 生产环境部署配置审批闸门

✅ CORRECT:

yaml

deploy-production:
  environment:
    name: production
    url: https://your-worker.workers.dev
  # Requires manual approval

❌ WRONG:

yaml

undefined

✅ 正确示例:

yaml

deploy-production:
  environment:
    name: production
    url: https://your-worker.workers.dev
  # 需要人工审批

❌ 错误示例:

yaml

undefined

❌ Auto-deploy to production without review

❌ 生产环境无需审核自动部署

deploy-production: runs-on: ubuntu-latest


**Why**: Human review catches issues automation misses.

---

deploy-production: runs-on: ubuntu-latest


**原因**: 人工审核可以发现自动化遗漏的问题。

---

Core Concepts

核心概念

Multi-Environment Strategy

多环境策略

Recommended setup:

Production:
```
main
```
branch → production environment
Staging: Pull requests → staging environment
Preview: Each PR → unique preview URL

wrangler.jsonc:

jsonc

{
  "name": "my-worker",
  "main": "src/index.ts",

  "env": {
    "production": {
      "name": "my-worker-production",
      "vars": {
        "ENVIRONMENT": "production"
      }
    },
    "staging": {
      "name": "my-worker-staging",
      "vars": {
        "ENVIRONMENT": "staging"
      }
    }
  }
}

推荐配置:

生产环境:
```
main
```
分支 → 对应production环境
预发环境: 拉取请求 → 对应staging环境
预览环境: 每个PR → 对应独立的预览URL

wrangler.jsonc配置示例:

jsonc

{
  "name": "my-worker",
  "main": "src/index.ts",

  "env": {
    "production": {
      "name": "my-worker-production",
      "vars": {
        "ENVIRONMENT": "production"
      }
    },
    "staging": {
      "name": "my-worker-staging",
      "vars": {
        "ENVIRONMENT": "staging"
      }
    }
  }
}

Secrets Management

密钥管理

Types of configuration:

Public variables (wrangler.jsonc) - Non-sensitive config
Secrets (wrangler secret) - API keys, tokens
CI variables (GitHub Secrets) - Deployment credentials

Setting secrets:

bash

undefined

配置类型:

公开变量（wrangler.jsonc） - 非敏感配置项
密钥（wrangler secret） - API密钥、令牌等敏感信息
CI变量（GitHub Secrets） - 部署凭证

设置密钥方法:

bash

undefined

Local development

本地开发环境

wrangler secret put DATABASE_URL

CI/CD (via GitHub Actions)

CI/CD环境（通过GitHub Actions）

bunx wrangler secret put DATABASE_URL --env production <<< "${{ secrets.DATABASE_URL }}"

undefined

bunx wrangler secret put DATABASE_URL --env production <<< "${{ secrets.DATABASE_URL }}"

undefined

Preview Deployments

预览部署

Automatically deploy each PR to a unique URL for testing:

yaml

- name: Deploy Preview
  uses: cloudflare/wrangler-action@v4
  with:
    api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    command: deploy --env preview-${{ github.event.number }}

Each PR gets URL like:

my-worker-preview-42.workers.dev

自动将每个PR部署到独立URL用于测试:

yaml

- name: Deploy Preview
  uses: cloudflare/wrangler-action@v4
  with:
    api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    command: deploy --env preview-${{ github.event.number }}

每个PR会生成类似如下的URL:

my-worker-preview-42.workers.dev

Top 5 Use Cases

五大使用场景

1. Deploy on Push to Main

1. 推送到main分支时自动部署

yaml

name: Deploy Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test
      - run: bun run build

      - name: Deploy to Production
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env production

yaml

name: Deploy Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test
      - run: bun run build

      - name: Deploy to Production
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env production

2. Preview Deployments for PRs

2. PR自动生成预览部署

yaml

name: Preview

on:
  pull_request:
    branches: [main]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test

      - name: Deploy Preview
        id: deploy
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env preview-${{ github.event.number }}

      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '✅ Preview deployed to: https://my-worker-preview-${{ github.event.number }}.workers.dev'
            })

yaml

name: Preview

on:
  pull_request:
    branches: [main]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test

      - name: Deploy Preview
        id: deploy
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env preview-${{ github.event.number }}

      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '✅ Preview deployed to: https://my-worker-preview-${{ github.event.number }}.workers.dev'
            })

3. Run Tests on Every Commit

3. 每次提交自动运行测试

yaml

name: Test

on:
  push:
    branches: ['**']
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test --coverage

      - name: Upload Coverage
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage/lcov.info

yaml

name: Test

on:
  push:
    branches: ['**']
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test --coverage

      - name: Upload Coverage
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage/lcov.info

4. Deploy with Approval Gate

4. 带审批闸门的部署

yaml

name: Deploy Production (Manual Approval)

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://my-worker.workers.dev
    # Requires manual approval in GitHub Settings

    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env production

yaml

name: Deploy Production (Manual Approval)

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://my-worker.workers.dev
    # 需要在GitHub设置中开启人工审批

    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env production

5. Staged Rollout (Canary)

5. 灰度发布（金丝雀发布）

yaml

name: Canary Deployment

on:
  workflow_dispatch:
    inputs:
      percentage:
        description: 'Traffic percentage to new version'
        required: true
        default: '10'

jobs:
  canary:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install

      # Deploy to canary environment
      - name: Deploy Canary
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env canary

      # Configure traffic split via Cloudflare API
      # (See references/deployment-strategies.md for full example)

yaml

name: Canary Deployment

on:
  workflow_dispatch:
    inputs:
      percentage:
        description: 'Traffic percentage to new version'
        required: true
        default: '10'

jobs:
  canary:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install

      # 部署到金丝雀环境
      - name: Deploy Canary
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env canary

      # 通过Cloudflare API配置流量切分
      # 完整示例参考references/deployment-strategies.md

Best Practices

最佳实践

✅ DO

✅ 推荐做法

Use semantic commit messages:

feat: add user authentication
fix: resolve rate limiting issue
chore: update dependencies

Run linting and type checking:

yaml

- run: bun run lint
- run: bun run type-check
- run: bun test

Cache dependencies:

yaml

- uses: oven-sh/setup-bun@v2
  with:
    bun-version: latest
# Bun automatically caches dependencies

Deploy different branches to different environments:

yaml

- name: Deploy
  run: |
    if [ "${{ github.ref }}" == "refs/heads/main" ]; then
      bunx wrangler deploy --env production
    else
      bunx wrangler deploy --env staging
    fi

Monitor deployments:

yaml

- name: Notify Slack
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {"text": "Deployment failed: ${{ github.sha }}"}

使用语义化提交信息:

feat: add user authentication
fix: resolve rate limiting issue
chore: update dependencies

运行代码检查和类型校验:

yaml

- run: bun run lint
- run: bun run type-check
- run: bun test

缓存依赖:

yaml

- uses: oven-sh/setup-bun@v2
  with:
    bun-version: latest
# Bun会自动缓存依赖

不同分支部署到不同环境:

yaml

- name: Deploy
  run: |
    if [ "${{ github.ref }}" == "refs/heads/main" ]; then
      bunx wrangler deploy --env production
    else
      bunx wrangler deploy --env staging
    fi

部署状态监控:

yaml

- name: Notify Slack
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {"text": "Deployment failed: ${{ github.sha }}"}

❌ DON'T

❌ 禁止做法

Don't skip tests
Don't deploy without verification
Don't hardcode secrets
Don't deploy to production from feature branches
Don't ignore deployment failures

不要跳过测试
不要不做验证直接部署
不要硬编码密钥
不要从功能分支直接部署到生产环境
不要忽略部署失败的情况

Top 7 Errors Prevented

可规避的7大常见错误

1. ❌

Error: A valid Cloudflare API token is required

1. ❌

Error: A valid Cloudflare API token is required

Cause: Missing or invalid

CLOUDFLARE_API_TOKEN

secret.

Fix:

Create API token: https://dash.cloudflare.com/profile/api-tokens
Add to GitHub Secrets: Settings → Secrets → Actions

Use in workflow:

api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}

原因: 缺失或无效的

CLOUDFLARE_API_TOKEN

密钥。

修复方案:

创建API令牌: https://dash.cloudflare.com/profile/api-tokens
添加到GitHub Secrets: 设置 → Secrets → Actions

在工作流中使用:

api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}

2. ❌

Error: Not enough permissions to deploy

2. ❌

Error: Not enough permissions to deploy

Cause: API token lacks required permissions.

Fix: Recreate token with:

Account.Cloudflare Workers Scripts - Edit
Account settings - Read

原因: API令牌权限不足。

修复方案: 重新创建令牌并赋予以下权限:

Account.Cloudflare Workers Scripts - 编辑权限
Account settings - 读取权限

3. ❌

Error: wrangler.toml not found

3. ❌

Error: wrangler.toml not found

Cause: Missing wrangler configuration.

Fix: Ensure

wrangler.jsonc

exists in repository root.

原因: 缺失wrangler配置文件。

修复方案: 确认仓库根目录存在

wrangler.jsonc

文件。

4. ❌ Deployment succeeds but worker doesn't work

4. ❌ 部署成功但Worker无法正常运行

Cause: Missing secrets or environment variables.

Fix: Set secrets in CI:

yaml

- name: Set Secrets
  run: |
    echo "${{ secrets.DATABASE_URL }}" | bunx wrangler secret put DATABASE_URL --env production

原因: 缺失密钥或环境变量。

修复方案: 在CI中设置密钥:

yaml

- name: Set Secrets
  run: |
    echo "${{ secrets.DATABASE_URL }}" | bunx wrangler secret put DATABASE_URL --env production

5. ❌ Tests pass locally but fail in CI

5. ❌ 本地测试通过但CI中测试失败

Cause: Environment differences (Node version, missing dependencies).

Fix:

yaml

- uses: oven-sh/setup-bun@v2
  with:
    bun-version: latest # Lock version

- run: bun install --frozen-lockfile # Use exact versions

原因: 环境差异（Node版本、缺失依赖）。

修复方案:

yaml

- uses: oven-sh/setup-bun@v2
  with:
    bun-version: latest # 锁定版本

- run: bun install --frozen-lockfile # 使用精确的依赖版本

6. ❌ Preview deployments conflict

6. ❌ 预览部署冲突

Cause: Multiple PRs deploying to same preview environment.

Fix: Use PR number in environment name:

yaml

command: deploy --env preview-${{ github.event.number }}

原因: 多个PR部署到同一个预览环境。

修复方案: 在环境名称中使用PR编号:

yaml

command: deploy --env preview-${{ github.event.number }}

7. ❌ Secrets exposed in logs

7. ❌ 密钥暴露在日志中

Cause: Echoing secrets in workflow.

Fix:

yaml

undefined

原因: 在工作流中打印了密钥内容。

修复方案:

yaml

undefined

❌ WRONG

❌ 错误示例

run: echo "Token: ${{ secrets.API_TOKEN }}"

run: echo "Token: ${{ secrets.API_TOKEN }}"

✅ CORRECT

✅ 正确示例

run: echo "Deploying..." # No secrets in output

---

run: echo "Deploying..." # 输出中不包含任何密钥

---

When to Load References

何时加载参考文档

Load reference files for detailed, specialized content:

Load
references/github-actions.md
when:

Setting up GitHub Actions from scratch
Configuring matrix builds (multiple Node versions)
Using GitHub environments and deployment protection
Implementing deployment gates and approvals

Load
references/gitlab-ci.md
when:

Setting up GitLab CI pipelines
Configuring GitLab environments
Using GitLab secret variables
Implementing review apps

Load
references/deployment-strategies.md
when:

Implementing blue-green deployments
Setting up canary releases
Configuring traffic splitting
Planning rollback procedures

Load
references/secrets-management.md
when:

Managing secrets across environments
Rotating API tokens
Using external secret providers (Vault, 1Password)
Implementing least-privilege access

Load
templates/github-actions-full.yml
for:

Complete production-ready GitHub Actions workflow
Multi-environment deployment example
All deployment gates configured

Load
templates/gitlab-ci-full.yml
for:

Complete GitLab CI pipeline
Multi-stage deployment
Review app configuration

Load
templates/preview-deployment.yml
for:

PR preview deployment setup
Automatic cleanup on PR close
Comment with preview URL

Load
templates/rollback-workflow.yml
for:

Manual rollback workflow
Deployment history tracking
Automated rollback on health check failure

Load
scripts/verify-deployment.sh
for:

Automated deployment verification
Health check implementation
Smoke tests after deployment

加载参考文档获取详细的专项内容:

在以下场景加载
references/github-actions.md
:

从零开始配置GitHub Actions
配置矩阵构建（多Node版本）
使用GitHub环境和部署保护
实现部署闸门和审批流程

在以下场景加载
references/gitlab-ci.md
:

配置GitLab CI流水线
配置GitLab环境
使用GitLab密钥变量
实现审查应用功能

在以下场景加载
references/deployment-strategies.md
:

实现蓝绿部署
配置金丝雀发布
配置流量切分
规划回滚流程

在以下场景加载
references/secrets-management.md
:

跨环境管理密钥
轮换API令牌
使用外部密钥提供商（Vault、1Password）
实现最小权限访问

加载
templates/github-actions-full.yml
获取:

完整可用于生产的GitHub Actions工作流
多环境部署示例
全部部署闸门配置

加载
templates/gitlab-ci-full.yml
获取:

完整的GitLab CI流水线
多阶段部署配置
审查应用配置

加载
templates/preview-deployment.yml
获取:

PR预览部署配置
PR关闭时自动清理资源
自动评论预览URL

加载
templates/rollback-workflow.yml
获取:

手动回滚工作流
部署历史追踪
健康检查失败自动回滚

加载
scripts/verify-deployment.sh
获取:

自动化部署验证脚本
健康检查实现
部署后冒烟测试

workers-ci-cd

Original

Translation

Cloudflare Workers CI/CD

Cloudflare Workers CI/CD

Table of Contents

目录

What Is Workers CI/CD?

什么是Workers CI/CD？

New in 2025

2025年新特性

❌ OLD (v3)

❌ 旧版（v3）

✅ NEW (v4)

✅ 新版（v4）

Quick Start (10 Minutes)

快速上手（10分钟）

GitHub Actions Setup

GitHub Actions配置

Critical Rules

核心规则

1. Never Commit Secrets to Git

1. 永远不要将密钥提交到Git

Use GitHub Secrets

使用GitHub Secrets

❌ NEVER hardcode tokens

❌ 永远不要硬编码令牌

2. Always Run Tests Before Deploy

2. 部署前必须运行测试

❌ Skipping tests

❌ 跳过测试

No tests!

没有测试步骤！

3. Use Different Environments

3. 使用多环境隔离部署

Production (main branch)

生产环境（main分支）

Staging (other branches)

预发环境（其他分支）

❌ Always deploying to production

❌ 所有分支都直接部署到生产环境

4. Verify Deployment Success

4. 验证部署是否成功

❌ No verification

❌ 没有部署验证步骤

Assuming it worked...

默认部署成功...

5. Use Deployment Gates for Production

5. 生产环境部署配置审批闸门

❌ Auto-deploy to production without review

❌ 生产环境无需审核自动部署

Core Concepts

核心概念

Multi-Environment Strategy

多环境策略

Secrets Management

密钥管理

Local development

本地开发环境

CI/CD (via GitHub Actions)

CI/CD环境（通过GitHub Actions）

Preview Deployments

预览部署

Top 5 Use Cases

五大使用场景

1. Deploy on Push to Main

1. 推送到main分支时自动部署

2. Preview Deployments for PRs

2. PR自动生成预览部署

3. Run Tests on Every Commit

3. 每次提交自动运行测试

4. Deploy with Approval Gate

4. 带审批闸门的部署

5. Staged Rollout (Canary)

5. 灰度发布（金丝雀发布）

Best Practices

最佳实践

✅ DO

✅ 推荐做法

❌ DON'T

1. ❌
`Error: A valid Cloudflare API token is required`

1. ❌
`Error: A valid Cloudflare API token is required`

2. ❌
`Error: Not enough permissions to deploy`

2. ❌
`Error: Not enough permissions to deploy`

3. ❌
`Error: wrangler.toml not found`

3. ❌
`Error: wrangler.toml not found`