Cloudflareプロジェクト立ち上げ

Cloudflareプロジェクト立ち上げ

Cloudflareネイティブなプロジェクトを、ローカル構築からGitHub Actionsによる検証済みデプロイまで進める。

初期構成は小さく保ち、根拠のあるbindingだけを追加する。

1. 対象を確認する

1. 対象ディレクトリ、AGENTS.md、Git状態、remote、lockfile、package scripts、Wrangler設定を確認する。
2. 未コミットの変更を利用者の作業として扱い、無関係な差分を変更しない。
3. API、静的サイト、SSR、定期実行、イベントconsumerのどれかを要求とローカル証拠から判断する。
4. 構成を変える選択だけ利用者へ確認する。指定がなければ次を採用する。

- Cloudflare Workers上のTypeScript - mainだけを本番へデプロイ - privateなGitHubリポジトリ - D1、R2、KV、Queues、Durable Objectsは必要になるまで作らない

5. scaffold前に、採用する製品と各製品が必要な理由を示す。

2. Cloudflareスタックを選ぶ

Workersを実行基盤とし、bindingを任意の能力として扱う。

| 要件 | 選択 | 避ける用途 | | --- | --- | --- | | HTTP API、webhook、edge処理 | Worker + TypeScript | routeやmiddlewareが少ないのにrouterを追加しない | | 複数route、middleware、typed RPC | Hono | 単一handlerへ理由なく導入しない | | 静的SPAまたはサイト | Workers static assetsまたはframework生成設定 | framework設定をplain Workerで上書きしない | | SSRまたはfull-stack | Cloudflare Workers対応framework | 公式adapterと生成済みWrangler設定を優先する | | relational query、transaction、構造化データ | D1 | binary objectやcache専用データ | | upload、画像、export、S3型object | R2 | relational recordや小さな設定値 | | read-heavyな設定、feature flag、cache型データ | KV | 強整合counterやtransaction | | 非同期処理、retry、流量平準化 | Queues | request中に完了必須の処理 | | entity単位の調停、強整合、WebSocket、stateful session | Durable Objects | D1で足りる通常のCRUD | | 定期処理 | Cron Trigger | idempotentでないhandler | | Worker実行時の秘密情報 | Worker secrets | GitHub ActionsのCI credential |

一つのWorkerから始める。

stagingを要求された場合は、D1、R2、KV、Queue、Durable Objectをproductionと共有せず、project-staging-*とproject-prod-*のように分ける。

3. ローカルでscaffoldする

1. 新規projectでは、対象frameworkに対応する現在のCloudflare scaffoldを使う。基本形はnpm create cloudflare@latestとする。
2. 既存projectでは生成処理を盲目的に実行せず、frameworkのCloudflare adapterと既存build構成を調べて適応する。
3. 既存lockfileが選ぶpackage managerを維持し、別形式のlockfileを作らない。
4. Wranglerをdevelopment dependencyへ固定し、次のpackage scriptsを用意する。

- dev: local development - checkまたはtypecheck: static validation - test: testがある場合 - deploy: wrangler deployまたはframework生成command - cf-typegen: binding型生成

5. 新しいWrangler設定ではcompatibility_dateを作業日へ設定する。既存projectの日付を暗黙に更新しない。
6. .dev.vars*、.env*、Wrangler state、local build outputを.gitignoreへ追加する。
7. .dev.vars.exampleまたは.env.exampleには変数名だけを残す。
8. token、production secret、秘密鍵、生成済みcredentialをcommitしない。

4. bindingを構成する

1. 外部公開または課金につながるCloudflare resourceを作る前に、resource名と実行commandを利用者へ示して確認する。
2. 承認されたresourceだけを作成し、生成されたIDをWrangler設定へ記録する。
3. binding変更後にTypeScript型を再生成する。
4. application secretはWrangler設定のvarsへ置かず、Worker secretとして登録する。
5. D1 schemaはmigrationとして管理し、scaffoldの一環でproduction schemaを直接編集しない。

5. ローカル検証を通す

次をprojectに合わせて実行する。

1. lockfileを変更しないdependency install
2. formatまたはlint
3. typecheck
4. test
5. build
6. wrangler deploy --dry-runまたはframework相当のdry run

失敗を解消してからremote resourceとrepositoryを操作する。

実行できない検証があれば、成功扱いにせず理由と未検証範囲を報告する。

6. GitHubリポジトリを接続する

remote操作前に次を確認する。

git status --short
git remote -v
gh auth status
gh repo view --json nameWithOwner,visibility,defaultBranchRef

1. 適切なremoteがあれば再利用し、上書きや重複repository作成をしない。
2. 新規repositoryが必要ならowner、名前、visibilityを示して確認してからgh repo createを実行する。
3. commit対象を限定し、利用者の無関係な変更を含めない。
4. GitHub Actionsをproduction deployの正本にする。同じbranchでCloudflare Workers Buildsも有効にして二重デプロイしない。

7. Actions credentialを設定する

GitHub Actions Secretsへ次の名前で登録する。

• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID

Global API Keyは使わない。

API tokenは対象accountへ限定し、Workers編集templateから始め、実際に使うbindingやrouteに必要な権限だけを追加する。

値をcommand引数、log、diff、回答へ出さない。

runtimeのapplication secretとCI credentialを分離する。

8. GitHub Actionsを作る

次をbaselineとし、package manager、Node version、working directory、build、deploy commandをprojectへ合わせる。

name: Deploy to Cloudflare

on:
  push:
    branches:
      - main
  workflow_dispatch:

concurrency:
  group: cloudflare-production
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Check
        run: npm run check --if-present

      - name: Test
        run: npm test --if-present

      - name: Build
        run: npm run build --if-present

      - name: Deploy
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy

monorepoではdependency install位置とworkingDirectoryを別々に確認する。

Pull Requestでpreviewを要求されていなければ、credentialを渡さずcheck、test、build、Wrangler dry runだけを行う。

9. deploy経路を実証する

1. 利用者がlive deployを依頼済みでない場合、productionをtriggerする最初のpush前に確認する。
2. 対象branchをpushし、Actions runを確認する。
3. 失敗した場合は、失敗stepとlogから原因を特定し、修正後に承認された方法で再実行する。
4. 成功後にWorkerまたはcustom domain URLへread-onlyなsmoke testを行う。
5. DNS解決だけでなく、status codeと安定したresponse propertyを確認する。

GitHub CLIが使える場合は次で確認する。

gh workflow list --repo OWNER/REPO
gh run list --repo OWNER/REPO --limit 10
gh run view RUN_ID --repo OWNER/REPO --log-failed

10. 完了報告を作る

次を簡潔に報告する。

• local project pathと採用stack
• GitHub repositoryとdefault branch
• 作成したCloudflare resourceとenvironment
• Actions workflowとrun status
• production URLとsmoke test結果
• 手作業が残るDNS、secret、billing、dashboard設定

禁止事項

• credentialをcommand引数、log、diff、回答へ出さない。
• .dev.vars、.env、秘密鍵、dashboardからコピーした値をcommitしない。
• Cloudflare製品を先回りしてすべて作らない。
• framework生成済みWrangler設定を理解せずに上書きしない。
• local scaffoldだけの依頼から、repository作成、push、resource作成、DNS変更、production deployまで権限を拡張しない。
• mutation前にread-only checkとdry runを行う。

参照先

• https://developers.cloudflare.com/workers/ci-cd/external-cicd/github-actions/
• https://developers.cloudflare.com/workers/wrangler/commands/workers/
• https://developers.cloudflare.com/workers/ci-cd/