cloudflare-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令牌

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

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

Account.Cloudflare Workers Scripts - 编辑
Account.Cloudflare Pages - 编辑（若使用Pages）

2. 在GitHub中添加密钥

仓库 → 设置 → 密钥 → 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
```
分支 → 生产环境
预发布环境: 拉取请求 → 预发布环境
预览环境: 每个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: 添加用户认证功能
fix: 解决速率限制问题
chore: 更新依赖

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

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

可预防的七大常见错误

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: 设置 → 密钥 → 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密钥变量
实现Review Apps

当以下场景时加载
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流水线
多阶段部署
Review App配置

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

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

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

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

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

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

Secure Installation

安全安装

When installing CI/CD dependencies, follow supply chain security best practices:

Block post-install scripts —
```
npm config set ignore-scripts true
```
(or Bun: disabled by default)
Frozen lockfiles in CI — Always use
```
npm ci
```
or
```
bun install --frozen-lockfile
```
Security gate — Add
```
socket ci
```
to your CI pipeline to block PRs that violate your security policy

Load the

dependency-upgrade

skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.

安装CI/CD依赖时，遵循供应链安全最佳实践:

阻止安装后脚本 —
```
npm config set ignore-scripts true
```
（Bun默认禁用）
CI中使用锁定的依赖文件 — 始终使用
```
npm ci
```
或
```
bun install --frozen-lockfile
```
安全闸门 — 在CI流水线中添加
```
socket ci
```
，阻止违反安全策略的PR

加载

dependency-upgrade

技能获取完整安全配置，包括Socket CLI集成、冷却期设置、锁定文件验证和CI强制执行。

cloudflare-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`