cloudflare-workers-ci-cd

Cloudflare Workers CI/CD

ステータス：✅ 本番環境で利用可能 | 最終確認日：2025-01-27 GitHub Actions：v4 | GitLab CI：最新 | Wrangler：4.81.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 トークンを作成する

こちらにアクセスします：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. リンティングと型チェックを実行します：

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

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

---

安全なインストール

CI/CD の依存関係をインストールする際は、サプライチェーンセキュリティのベストプラクティスに従います。

• インストール後スクリプトをブロックする — npm config set ignore-scripts true（または Bun：デフォルトで無効）
• CI ではロックファイルを固定する — 常に npm ci または bun install --frozen-lockfile を使用します
• セキュリティゲート — CI パイプラインに socket ci を追加し、セキュリティポリシーに違反する PR をブロックします

Socket CLI の統合、クールダウンの設定、ロックファイルの検証、CI での適用を含むセキュリティ設定全体については、dependency-upgrade スキルを読み込みます。

関連する Cloudflare プラグイン

デプロイのテストには、以下を読み込んでください：

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

このスキルは、バインディングの種類にかかわらず、すべての Workers のデプロイにおける CI/CD 自動化に重点を置いています。

---

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