workers-ci-cd

Cloudflare Workers CI/CD

ステータス: ✅ 本番環境対応 | 最終確認日: 2025-01-27 GitHub Actions: v4 | GitLab CI: 最新 | Wrangler: 4.50.0

目次

• Workers CI/CD とは？
• 2025 年の新機能
• クイックスタート（10 分）
• 重要なルール
• 基本概念
• 主な 5 つのユースケース
• ベストプラクティス
• 防止できる主な 7 つのエラー
• リファレンスを読み込むタイミング

---

Workers CI/CD とは？

GitHub Actions または GitLab CI を使用した、Cloudflare Workers のテストとデプロイの自動化です。コミットごとのテスト実行、プレビュー／ステージング／本番環境への自動デプロイ、シークレットの安全な管理、安全なリリースのためのデプロイゲートの実装が可能になります。

主な機能: テストの自動化、複数環境へのデプロイ、PR ごとのプレビュー URL、シークレット管理、デプロイの検証、自動ロールバック。

---

2025 年の新機能

GitHub Actions の更新（2025 年 1 月）:

• 新機能: cloudflare/wrangler-action@v4（キャッシュの改善、デプロイの高速化）
• 改善: vars および secrets パラメーターによるシークレットのサポート
• 追加: プレビュー環境のクリーンアップ機能を内蔵
• 破壊的変更: apiToken の名前を api-token（ケバブケース）に変更

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（2025 年 1 月）:

• 新機能: デプロイ検証用の --dry-run フラグ
• 改善: 並列アップロードによるデプロイの高速化
• 追加: 環境変数を保持する --keep-vars

---

クイックスタート（10 分）

GitHub Actions のセットアップ

1. Cloudflare API トークンを作成する

次の URL にアクセスします：https://dash.cloudflare.com/profile/api-tokens

次の権限を持つトークンを作成します：

• Account.Cloudflare Workers Scripts - 編集
• Account.Cloudflare Pages - 編集（Pages を使用する場合）

2. シークレットを GitHub に追加する

リポジトリ → Settings → Secrets → Actions → New repository secret：

• 名前：CLOUDFLARE_API_TOKEN
• 値：[トークンを貼り付け]

3. .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 タブでデプロイの進行状況を確認します。

---

重要なルール

1. シークレットを Git にコミットしない

✅ 正しい例:

# Use GitHub Secrets
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}

❌ 誤った例:

# ❌ NEVER hardcode tokens
api-token: "abc123def456..."

理由: トークンが漏洩すると、誰でもあなたのアカウントにデプロイできるようになります。

2. デプロイ前に必ずテストを実行する

✅ 正しい例:

- run: bun test  # ✅ Tests run first

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

❌ 誤った例:

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

理由: 不具合のあるコードを本番環境に反映してはいけません。

3. 環境を分ける

✅ 正しい例:

# 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

❌ 誤った例:

# ❌ Always deploying to production
- run: bunx wrangler deploy

理由: 本番環境に反映する前に、ステージング環境で変更をテストします。

4. デプロイの成功を確認する

✅ 正しい例:

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

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

❌ 誤った例:

# ❌ No verification
- name: Deploy
  uses: cloudflare/wrangler-action@v4
  # Assuming it worked...

理由: DNS の問題やバインディングエラーなどにより、デプロイがエラーを通知せずに失敗することがあります。

5. 本番環境ではデプロイゲートを使用する

✅ 正しい例:

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

❌ 誤った例:

# ❌ Auto-deploy to production without review
deploy-production:
  runs-on: ubuntu-latest

理由: 人によるレビューで、自動化では見逃される問題を検出できます。

---

基本概念

複数環境の戦略

推奨セットアップ:

• 本番環境: main ブランチ → 本番環境
• ステージング: プルリクエスト → ステージング環境
• プレビュー: PR ごとに固有のプレビュー URL

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"
      }
    }
  }
}

シークレット管理

設定の種類:

1. 公開変数（wrangler.jsonc）- 機密ではない設定
2. シークレット（wrangler secret）- API キー、トークン
3. CI 変数（GitHub Secrets）- デプロイ認証情報

シークレットの設定:

# Local development
wrangler secret put DATABASE_URL

# CI/CD (via 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

---

主な 5 つのユースケース

1. main へのプッシュ時にデプロイする

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. PR のプレビューデプロイ

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. すべてのコミットでテストを実行する

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. 承認ゲートを設けてデプロイする

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

5. 段階的なロールアウト（カナリア）

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)

---

ベストプラクティス

✅ DO

1. セマンティックなコミットメッセージを使用する：

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

2. Lint と型チェックを実行する：

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

3. 依存関係をキャッシュする：

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

4. ブランチごとに異なる環境へデプロイする：

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

5. デプロイを監視する：

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

❌ DON'T

1. テストを省略しない
2. 検証せずにデプロイしない
3. シークレットをハードコードしない
4. フィーチャーブランチから本番環境へデプロイしない
5. デプロイの失敗を無視しない

---

防止できる主なエラー 7 件

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

原因：CLOUDFLARE_API_TOKEN シークレットがないか、無効です。

修正方法：

1. API トークンを作成します：https://dash.cloudflare.com/profile/api-tokens
2. GitHub Secrets に追加します：Settings → Secrets → Actions
3. ワークフローで使用します：api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}

---

2. ❌ Error: Not enough permissions to deploy

原因：API トークンに必要な権限がありません。

修正方法：以下の権限を設定してトークンを再作成します：

• Account.Cloudflare Workers Scripts - 編集
• Account settings - 読み取り

---

3. ❌ Error: wrangler.toml not found

原因：wrangler の設定がありません。

修正方法：リポジトリのルートに wrangler.jsonc があることを確認します。

---

4. ❌ デプロイは成功するが、Worker が動作しない

原因：シークレットまたは環境変数がありません。

修正方法：CI でシークレットを設定します：

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

---

5. ❌ ローカルではテストが通るが、CI では失敗する

原因：環境の違い（Node のバージョン、依存関係の不足）です。

修正方法：

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

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

---

6. ❌ プレビューのデプロイが競合する

原因：複数の PR が同じプレビュー環境にデプロイされています。

修正方法：環境名に PR 番号を使用します：

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

---

7. ❌ ログでシークレットが漏えいする

原因：ワークフローでシークレットを echo しています。

修正方法：

# ❌ WRONG
- run: echo "Token: ${{ secrets.API_TOKEN }}"

# ✅ CORRECT
- run: echo "Deploying..." # No secrets in output

---

リファレンスを読み込むタイミング

詳細な専門情報については、リファレンスファイルを読み込みます。

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 を読み込む場合：

• デプロイの自動検証
• ヘルスチェックの実装
• デプロイ後のスモークテスト

---

関連する Cloudflare プラグイン

デプロイのテストには、以下を読み込みます：

• cloudflare-workers-testing - デプロイ前に Workers をテストします
• cloudflare-manager - Cloudflare API を介してデプロイを管理します

このスキルは、使用するバインディングに関係なく、すべての Workers デプロイに対する CI/CD 自動化に重点を置いています。

---

ご質問はありますか？ references/secrets-management.md を読み込むか、/workers-deploy コマンドを使用して、ガイドに沿ってデプロイしてください。