secondsky/claude-skills / plugins/cloudflare-workers/skills/cloudflare-workers-ci-cd
cloudflare-workers-ci-cd
VerifiedComplete CI/CD guide for Cloudflare Workers using GitHub Actions and GitLab CI. Use for automated testing, deployment pipelines, preview environments, secrets management, or encountering deployment failures, workflow errors, environment configuration issues.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.8 KB |
| references/deployment-strategies.md | markdown | 8.7 KB |
| references/github-actions.md | markdown | 10.0 KB |
| references/gitlab-ci.md | markdown | 3.4 KB |
| references/secrets-management.md | markdown | 7.6 KB |
| scripts/verify-deployment.sh | script | 4.7 KB |
| templates/github-actions-full.yml | config | 4.5 KB |
| templates/gitlab-ci-full.yml | config | 5.3 KB |
| templates/preview-deployment.yml | config | 6.9 KB |
| templates/rollback-workflow.yml | config | 8.7 KB |
references/github-actions.md
View on GitHub# GitHub Actions for Cloudflare Workers
Complete guide for setting up GitHub Actions CI/CD pipelines for Workers.
## Basic Workflow Structure
```yaml
name: Deploy Workers
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
deployments: write
pull-requests: write
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: latest
- name: Install Dependencies
run: bun install
- name: Run Tests
run: bun test
- name: Deploy
uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: deploy
```
## Multi-Environment Deployments
### Separate Workflows Approach
**`.github/workflows/deploy-staging.yml`**:
```yaml
name: Deploy Staging
on:
push:
branches: [develop, 'feature/**']
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: staging
url: https://my-worker-staging.workers.dev
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun test
- name: Deploy to Staging
uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: deploy --env staging
```
**`.github/workflows/deploy-production.yml`**:
```yaml
name: Deploy Production
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: production
url: https://my-worker.workers.dev
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: Verify Deployment
run: |
sleep 5
curl -f https://my-worker.workers.dev/health || exit 1
```
### Single Workflow with Conditions
```yaml
name: Deploy
on:
push:
branches: [main, develop]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun test
- name: Deploy to Production
if: github.ref == 'refs/heads/main'
uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: deploy --env production
- name: Deploy to Staging
if: github.ref == 'refs/heads/develop'
uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: deploy --env staging
```
## Preview Deployments for Pull Requests
```yaml
name: Preview Deployment
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
preview:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
deployments: write
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 Preview URL
uses: actions/github-script@v7
with:
script: |
const prNumber = context.issue.number;
const previewUrl = `https://my-worker-preview-${prNumber}.workers.dev`;
github.rest.issues.createComment({
issue_number: prNumber,
owner: context.repo.owner,
repo: context.repo.repo,
body: `β
**Preview Deployment**\n\nπ ${previewUrl}\n\nDeployed commit: ${context.sha.substring(0, 7)}`
});
```
### Cleanup Preview on PR Close
```yaml
name: Cleanup Preview
on:
pull_request:
types: [closed]
jobs:
cleanup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Delete Preview Deployment
uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: delete --name my-worker-preview-${{ github.event.number }}
```
## Deployment Approvals
### GitHub Environments
Configure in: Settings β Environments β New environment
**Create "production" environment with:**
- Required reviewers: Team leads, DevOps
- Wait timer: 5 minutes (optional)
- Deployment branches: Only `main`
**Workflow**:
```yaml
jobs:
deploy-production:
runs-on: ubuntu-latest
environment:
name: production # Requires approval
url: https://my-worker.workers.dev
steps:
- uses: actions/checkout@v4
- uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: deploy --env production
```
## Matrix Builds
Test across multiple Node versions:
```yaml
name: Test
on: [push, pull_request]
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
bun-version: [latest, '1.1.0']
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
with:
bun-version: ${{ matrix.bun-version }}
- run: bun install
- run: bun test
```
## Secrets Management
### Setting Secrets
1. Go to: Repository β Settings β Secrets β Actions
2. Click "New repository secret"
3. Add:
- `CLOUDFLARE_API_TOKEN`
- `DATABASE_URL`
- `STRIPE_SECRET_KEY`
- etc.
### Using Secrets in Workflows
```yaml
- name: Deploy with Secrets
uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
- name: Set Environment Variables
run: |
echo "${{ secrets.DATABASE_URL }}" | bunx wrangler secret put DATABASE_URL --env production
echo "${{ secrets.STRIPE_SECRET_KEY }}" | bunx wrangler secret put STRIPE_SECRET_KEY --env production
```
### Environment-Specific Secrets
**Organization/Repository Secrets** (Settings β Secrets):
- `CLOUDFLARE_API_TOKEN` (used in all workflows)
**Environment Secrets** (Settings β Environments β production β Secrets):
- `DATABASE_URL_PRODUCTION`
- `STRIPE_SECRET_KEY_PRODUCTION`
**Usage**:
```yaml
jobs:
deploy:
environment: production # Automatically loads environment secrets
steps:
- run: |
echo "${{ secrets.DATABASE_URL_PRODUCTION }}" | \
bunx wrangler secret put DATABASE_URL --env production
```
## Caching Strategies
### Bun Cache (Automatic)
```yaml
- uses: oven-sh/setup-bun@v2
with:
bun-version: latest
# Bun automatically caches dependencies
```
### Manual Caching
```yaml
- name: Cache Dependencies
uses: actions/cache@v4
with:
path: |
~/.bun/install/cache
node_modules
key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
restore-keys: |
${{ runner.os }}-bun-
```
## Notifications
### Slack Notifications
```yaml
- name: Notify Slack on Success
if: success()
uses: slackapi/slack-github-action@v1
with:
webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
payload: |
{
"text": "β
Deployment successful: ${{ github.sha }}"
}
- name: Notify Slack on Failure
if: failure()
uses: slackapi/slack-github-action@v1
with:
webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
payload: |
{
"text": "β Deployment failed: ${{ github.sha }}"
}
```
### Discord Notifications
```yaml
- name: Discord Notification
# NOTE: `Ilshidur/action-discord@master` is unmaintained and should not be
# pinned to a mutable `@master` tag in any case. `sarisia/actions-status-discord`
# is a maintained drop-in replacement that uses the same DISCORD_WEBHOOK secret.
uses: sarisia/actions-status-discord@v1
env:
DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
with:
args: 'Deployed {{ EVENT_PAYLOAD.repository.full_name }} to production'
```
## Advanced Patterns
### Conditional Deployment Based on Changed Files
```yaml
- name: Check for Worker Changes
id: changes
uses: dorny/paths-filter@v3
with:
filters: |
worker:
- 'src/**'
- 'wrangler.jsonc'
- name: Deploy if Worker Changed
if: steps.changes.outputs.worker == 'true'
uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: deploy
```
### Deployment with Retries
```yaml
- name: Deploy with Retry
uses: nick-fields/retry-action@v3
with:
timeout_minutes: 10
max_attempts: 3
retry_wait_seconds: 30
command: bunx wrangler deploy --env production
```
### Parallel Deployments
```yaml
jobs:
deploy-multiple-workers:
runs-on: ubuntu-latest
strategy:
matrix:
worker: [api, frontend, worker3]
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- run: bun install
- name: Deploy ${{ matrix.worker }}
working-directory: workers/${{ matrix.worker }}
uses: cloudflare/wrangler-action@v4
with:
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: deploy
```
## Troubleshooting
### Debug Mode
```yaml
- name: Enable Wrangler Debug
run: WRANGLER_LOG=debug bunx wrangler deploy
```
### View Full Logs
Enable debug logging for GitHub Actions:
1. Repository β Settings β Secrets β New secret
2. Name: `ACTIONS_STEP_DEBUG`, Value: `true`
### Common Issues
**Error: "Repository not found"**
- Fix: Add `contents: read` permission to job
**Error: "Resource not accessible by integration"**
- Fix: Add `pull-requests: write` permission
**Deployment hangs**
- Fix: Add timeout: `timeout-minutes: 10`
## Resources
- GitHub Actions Docs: https://docs.github.com/actions
- Wrangler Action: https://github.com/cloudflare/wrangler-action
- Cloudflare Workers Docs: https://developers.cloudflare.com/workers/
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |