workers-ci-cd by secondsky/claude-skills
npx skills add https://github.com/secondsky/claude-skills --skill workers-ci-cd状态 : ✅ 生产就绪 | 最后验证:2025-01-27 GitHub Actions : v4 | GitLab CI : 最新 | Wrangler : 4.50.0
使用 GitHub Actions 或 GitLab CI 实现 Cloudflare Workers 的自动化测试和部署。支持在每次提交时运行测试、自动部署到预览/预演/生产环境、安全地管理密钥,并为安全发布实施部署门控。
关键能力 : 自动化测试、多环境部署、每个 PR 的预览 URL、密钥管理、部署验证、自动回滚。
GitHub Actions 更新 (2025 年 1 月):
cloudflare/wrangler-action@v4 (改进的缓存,更快的部署)vars 和 secrets 参数管理密钥广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
apiToken 重命名为 api-token (kebab-case)从 v3 迁移 :
# ❌ 旧版 (v3)
- uses: cloudflare/wrangler-action@3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
# ✅ 新版 (v4)
- uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
Wrangler 4.50.0 (2025 年 1 月):
--dry-run 标志--keep-vars 以保留环境变量1. 创建 Cloudflare API 令牌
创建具有以下权限的令牌:
2. 将密钥添加到 GitHub
仓库 → 设置 → 密钥 → Actions → 新建仓库密钥:
CLOUDFLARE_API_TOKEN3. 创建.github/workflows/deploy.yml
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. 推送并验证
git add .github/workflows/deploy.yml
git commit -m "Add CI/CD pipeline"
git push
在 GitHub 的 Actions 标签页中查看部署进度。
✅ 正确 :
# 使用 GitHub Secrets
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
❌ 错误 :
# ❌ 切勿硬编码令牌
api-token: "abc123def456..."
原因 : 暴露的令牌允许任何人部署到您的账户。
✅ 正确 :
- run: bun test # ✅ 先运行测试
- name: Deploy
uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
❌ 错误 :
# ❌ 跳过测试
- name: Deploy
uses: cloudflare/wrangler-action@v4
# 没有测试!
原因 : 损坏的代码不应进入生产环境。
✅ 正确 :
# 生产环境 (main 分支)
- name: Deploy to Production
if: github.ref == 'refs/heads/main'
run: bunx wrangler deploy --env production
# 预演环境 (其他分支)
- name: Deploy to Staging
if: github.ref != 'refs/heads/main'
run: bunx wrangler deploy --env staging
❌ 错误 :
# ❌ 总是部署到生产环境
- run: bunx wrangler deploy
原因 : 在投入生产前,先在预演环境测试变更。
✅ 正确 :
- name: Deploy
id: deploy
uses: cloudflare/wrangler-action@v4
- name: Verify Deployment
run: |
curl -f https://your-worker.workers.dev/health || exit 1
❌ 错误 :
# ❌ 没有验证
- name: Deploy
uses: cloudflare/wrangler-action@v4
# 假设它成功了...
原因 : 部署可能会静默失败(DNS 问题、绑定错误)。
✅ 正确 :
deploy-production:
environment:
name: production
url: https://your-worker.workers.dev
# 需要手动批准
❌ 错误 :
# ❌ 未经审查自动部署到生产环境
deploy-production:
runs-on: ubuntu-latest
原因 : 人工审查能发现自动化遗漏的问题。
推荐设置 :
main 分支 → 生产环境wrangler.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"
}
}
}
}
配置类型 :
设置密钥 :
# 本地开发
wrangler secret put DATABASE_URL
# CI/CD (通过 GitHub Actions)
bunx wrangler secret put DATABASE_URL --env production <<< "${{ secrets.DATABASE_URL }}"
自动将每个 PR 部署到唯一的 URL 进行测试:
- 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
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
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'
})
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
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
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)
使用语义化提交信息 :
feat: add user authentication fix: resolve rate limiting issue chore: update dependencies
运行代码检查和类型检查 :
缓存依赖项 :
将不同分支部署到不同环境 :
监控部署 :
Error: A valid Cloudflare API token is required原因 : 缺少或无效的 CLOUDFLARE_API_TOKEN 密钥。
修复方法 :
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}Error: Not enough permissions to deploy原因 : API 令牌缺少所需权限。
修复方法 : 使用以下权限重新创建令牌:
Error: wrangler.toml not found原因 : 缺少 wrangler 配置。
修复方法 : 确保 wrangler.jsonc 存在于仓库根目录。
原因 : 缺少密钥或环境变量。
修复方法 : 在 CI 中设置密钥:
- name: Set Secrets
run: |
echo "${{ secrets.DATABASE_URL }}" | bunx wrangler secret put DATABASE_URL --env production
原因 : 环境差异(Node 版本、缺少依赖项)。
修复方法 :
- uses: oven-sh/setup-bun@v2
with:
bun-version: latest # 锁定版本
- run: bun install --frozen-lockfile # 使用精确版本
原因 : 多个 PR 部署到同一个预览环境。
修复方法 : 在环境名称中使用 PR 编号:
command: deploy --env preview-${{ github.event.number }}
原因 : 在工作流中回显密钥。
修复方法 :
# ❌ 错误
- run: echo "Token: ${{ secrets.API_TOKEN }}"
# ✅ 正确
- run: echo "Deploying..." # 输出中不包含密钥
加载参考文件以获取详细、专业的内容:
在以下情况加载references/github-actions.md:
在以下情况加载references/gitlab-ci.md:
在以下情况加载references/deployment-strategies.md:
在以下情况加载references/secrets-management.md:
在以下情况加载templates/github-actions-full.yml:
在以下情况加载templates/gitlab-ci-full.yml:
在以下情况加载templates/preview-deployment.yml:
在以下情况加载templates/rollback-workflow.yml:
在以下情况加载scripts/verify-deployment.sh:
用于部署测试,加载:
此技能专注于 CI/CD 自动化,适用于所有 Workers 部署,无论使用何种绑定。
有问题吗? 加载 references/secrets-management.md 或使用 /workers-deploy 命令获取引导式部署。
每周安装次数
76
仓库
GitHub 星标数
93
首次出现
2026 年 1 月 25 日
安全审计
安装于
claude-code67
codex61
cursor61
opencode60
gemini-cli60
github-copilot57
Status : ✅ Production Ready | Last Verified: 2025-01-27 GitHub Actions : v4 | GitLab CI : Latest | Wrangler : 4.50.0
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 Updates (January 2025):
cloudflare/wrangler-action@v4 (improved caching, faster deployments)vars and secrets parametersapiToken renamed to api-token (kebab-case)Migration from v3 :
# ❌ OLD (v3)
- uses: cloudflare/wrangler-action@3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
# ✅ NEW (v4)
- uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
Wrangler 4.50.0 (January 2025):
--dry-run flag for deployment validation--keep-vars to preserve environment variables1. Create Cloudflare API Token
Go to: https://dash.cloudflare.com/profile/api-tokens
Create token with permissions:
2. Add Secret to GitHub
Repository → Settings → Secrets → Actions → New repository secret:
CLOUDFLARE_API_TOKEN3. Create.github/workflows/deploy.yml
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
git add .github/workflows/deploy.yml
git commit -m "Add CI/CD pipeline"
git push
Check Actions tab on GitHub to see deployment progress.
✅ CORRECT :
# Use GitHub Secrets
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
❌ WRONG :
# ❌ NEVER hardcode tokens
api-token: "abc123def456..."
Why : Exposed tokens allow anyone to deploy to your account.
✅ CORRECT :
- run: bun test # ✅ Tests run first
- name: Deploy
uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
❌ WRONG :
# ❌ Skipping tests
- name: Deploy
uses: cloudflare/wrangler-action@v4
# No tests!
Why : Broken code shouldn't reach production.
✅ CORRECT :
# Production (main branch)
- 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 :
# ❌ Always deploying to production
- run: bunx wrangler deploy
Why : Test changes in staging before production.
✅ CORRECT :
- name: Deploy
id: deploy
uses: cloudflare/wrangler-action@v4
- name: Verify Deployment
run: |
curl -f https://your-worker.workers.dev/health || exit 1
❌ WRONG :
# ❌ No verification
- name: Deploy
uses: cloudflare/wrangler-action@v4
# Assuming it worked...
Why : Deployments can fail silently (DNS issues, binding errors).
✅ CORRECT :
deploy-production:
environment:
name: production
url: https://your-worker.workers.dev
# Requires manual approval
❌ WRONG :
# ❌ Auto-deploy to production without review
deploy-production:
runs-on: ubuntu-latest
Why : Human review catches issues automation misses.
Recommended setup :
main branch → production environmentwrangler.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"
}
}
}
}
Types of configuration :
Setting secrets :
# Local development
wrangler secret put DATABASE_URL
# CI/CD (via GitHub Actions)
bunx wrangler secret put DATABASE_URL --env production <<< "${{ secrets.DATABASE_URL }}"
Automatically deploy each PR to a unique URL for testing:
- 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
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
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'
})
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
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
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)
Use semantic commit messages :
feat: add user authentication fix: resolve rate limiting issue chore: update dependencies
Run linting and type checking :
Cache dependencies :
Deploy different branches to different environments :
Monitor deployments :
Error: A valid Cloudflare API token is requiredCause : Missing or invalid CLOUDFLARE_API_TOKEN secret.
Fix :
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}Error: Not enough permissions to deployCause : API token lacks required permissions.
Fix : Recreate token with:
Error: wrangler.toml not foundCause : Missing wrangler configuration.
Fix : Ensure wrangler.jsonc exists in repository root.
Cause : Missing secrets or environment variables.
Fix : Set secrets in CI:
- name: Set Secrets
run: |
echo "${{ secrets.DATABASE_URL }}" | bunx wrangler secret put DATABASE_URL --env production
Cause : Environment differences (Node version, missing dependencies).
Fix :
- uses: oven-sh/setup-bun@v2
with:
bun-version: latest # Lock version
- run: bun install --frozen-lockfile # Use exact versions
Cause : Multiple PRs deploying to same preview environment.
Fix : Use PR number in environment name:
command: deploy --env preview-${{ github.event.number }}
Cause : Echoing secrets in workflow.
Fix :
# ❌ WRONG
- run: echo "Token: ${{ secrets.API_TOKEN }}"
# ✅ CORRECT
- run: echo "Deploying..." # No secrets in output
Load reference files for detailed, specialized content:
Loadreferences/github-actions.md when:
Loadreferences/gitlab-ci.md when:
Loadreferences/deployment-strategies.md when:
Loadreferences/secrets-management.md when:
Loadtemplates/github-actions-full.yml for:
Loadtemplates/gitlab-ci-full.yml for:
Loadtemplates/preview-deployment.yml for:
Loadtemplates/rollback-workflow.yml for:
Loadscripts/verify-deployment.sh for:
For deployment testing, load:
This skill focuses on CI/CD automation for ALL Workers deployments regardless of bindings used.
Questions? Load references/secrets-management.md or use /workers-deploy command for guided deployment.
Weekly Installs
76
Repository
GitHub Stars
93
First Seen
Jan 25, 2026
Security Audits
Gen Agent Trust HubFailSocketPassSnykPass
Installed on
claude-code67
codex61
cursor61
opencode60
gemini-cli60
github-copilot57