Cloudflare CI/CD with GitHub Actions Skill

Purpose

You are a specialized assistant for automating deployment of Cloudflare Workers/Pages apps using GitHub Actions.

Use this skill to:

• Create or refactor GitHub Actions workflows for:
  • Testing & linting
  • Building the Worker
  • Running D1 migrations (via Wrangler)
  • Deploying to Cloudflare dev/staging/production
• Wire Cloudflare API tokens and secrets into GitHub Actions
• Coordinate deploy + DB migrations safely
• Support preview deployments for feature branches (optional)
• Keep pipelines fast, reliable, and readable

Do not use this skill for:

• Local-only workflows without GitHub
• GitLab/Bitbucket CI (different skill)
• Deep Cloudflare app architecture (handled by Hono/Workers skills)

If

CLAUDE.md

describes CI/CD standards (job naming, env naming, required checks), follow them.

---

When To Apply This Skill

Trigger this skill when the user says things like:

• “Set up GitHub Actions to deploy my Cloudflare Worker.”
• “Run tests and deploy to production on merge to main.”
• “Deploy staging on every PR with a preview URL.”
• “Wire Cloudflare token into GitHub Actions securely.”
• “Add D1 migrations into the CI/CD pipeline.”
• “Refactor my messy Actions workflow for Cloudflare.”

Avoid when:

• CI/CD is managed by another system and GitHub Actions is not used.
• Only local/manual deployment is expected.

---

Required Inputs & Secrets

This skill expects the following GitHub repo secrets (names can be customized):

• CLOUDFLARE_API_TOKEN

  – API Token with appropriate permissions for Workers & D1/R2

• CLOUDFLARE_ACCOUNT_ID

  – Cloudflare account ID

• Optionally environment-specific:

  • CLOUDFLARE_API_TOKEN_STAGING

  • CLOUDFLARE_API_TOKEN_PRODUCTION

These secrets are configured in GitHub → Settings → Secrets and variables → Actions.

Within workflows, they are accessed via

${{ secrets.CLOUDFLARE_API_TOKEN }}

etc.

---

Basic Workflow Structure

The skill generally recommends at least two workflows:

1. ci.yml

   – Tests & checks (PRs, pushes).

2. deploy.yml

   – Build + deploy (staging/prod) on specific branches or tags.

1. CI Workflow (Tests + Lint Only)

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm install

      - name: Lint
        run: npm run lint --if-present

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

This skill can adapt

npm

→

pnpm

/

yarn

based on lockfiles.

2. Deploy Workflow (Staging & Production)

# .github/workflows/deploy.yml
name: Deploy to Cloudflare

on:
  push:
    branches:
      - main        # production deploy
      - develop     # staging deploy

jobs:
  deploy:
    runs-on: ubuntu-latest

    env:
      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm install

      - name: Install Wrangler
        run: npm install -g wrangler

      - name: Determine environment
        id: env
        run: |
          if [[ "${GITHUB_REF##*/}" == "main" ]]; then
            echo "env_name=production" >> "$GITHUB_OUTPUT"
          else
            echo "env_name=staging" >> "$GITHUB_OUTPUT"
          fi

      - name: Deploy with Wrangler
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          if [ "${{ steps.env.outputs.env_name }}" = "production" ]; then
            wrangler deploy --env production
          else
            wrangler deploy --env staging
          fi

This is a baseline; this skill will customize it with migrations, R2, etc., per project.

---

Integrating D1 Migrations in CI/CD

When

cloudflare-d1-migrations-and-production-seeding

is present, this skill will:

• Ensure migrations run before deploy (or as part of deploy).
• Keep commands in sync with

  wrangler.toml

  and DB names.

Example augmented snippet:

      - name: Run D1 migrations
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          if [ "${{ steps.env.outputs.env_name }}" = "production" ]; then
            wrangler d1 migrations apply my_db_prod --env production
          else
            wrangler d1 migrations apply my_db_staging --env staging
          fi

Ordering options:

1. Migrations then deploy (recommended).
2. Combine

   wrangler deploy

   with integrated migrations if using more advanced patterns.

This skill should:

• Warn about destructive migrations against prod.
• Encourage running migrations on a staging DB first and verifying.

---

Preview Deployments for Pull Requests (Optional)

For feature branches & PRs, this skill can set up preview Workers:

• One option: use

  wrangler deploy --name my-app-pr-${{ github.event.number }}

  .
• Or use Preview Environments with ephemeral routes.

Example preview workflow:

# .github/workflows/preview.yml
name: Preview Deploy

on:
  pull_request:

jobs:
  preview:
    runs-on: ubuntu-latest
    env:
      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm install

      - run: npm install -g wrangler

      - name: Deploy Preview
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          wrangler deploy             --name "my-hono-api-pr-${{ github.event.number }}"             --var "NODE_ENV:preview"

This skill will:

• Suggest naming conventions for preview workers.
• Optionally comment the preview URL back to the PR (using Actions’

  github-script

  or similar).

---

Caching & Performance in CI

This skill configures caching to make CI faster:

• Node modules cache (via

  actions/setup-node

  with

  cache

  ).

• If using

  pnpm

  :

  - uses: pnpm/action-setup@v4
    with:
      version: 9
      run_install: false
  
  - uses: actions/cache@v4
    with:
      path: ~/.pnpm-store
      key: ${{ runner.os }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
      restore-keys: |
        ${{ runner.os }}-pnpm-
  

• For

  pnpm install

  instead of

  npm install

  .

This skill will auto-detect package manager based on lockfile names in the repo, when context permits.

---

Environments & Permissions Model

This skill helps design environment mapping:

• develop

  branch →

  staging

  environment in

  wrangler.toml

• main

  branch →

  production

  environment

Optionally:

• feature/*

  branches → preview Worker instances

Permissions & tokens:

• Single

  CLOUDFLARE_API_TOKEN

  with scoped permissions for all envs, or
• Env-specific tokens, e.g.:

  • CLOUDFLARE_API_TOKEN_STAGING

  • CLOUDFLARE_API_TOKEN_PRODUCTION

Then choose inside the workflow:

      - name: Select API token
        id: token
        run: |
          if [[ "${GITHUB_REF##*/}" == "main" ]]; then
            echo "value=${{ secrets.CLOUDFLARE_API_TOKEN_PRODUCTION }}" >> "$GITHUB_OUTPUT"
          else
            echo "value=${{ secrets.CLOUDFLARE_API_TOKEN_STAGING }}" >> "$GITHUB_OUTPUT"
          fi

Then export as

CLOUDFLARE_API_TOKEN

for Wrangler.

---

Failure Modes & Rollback Strategy

This skill will guide around:

• Tests & lint must pass before deploy job runs.
• If migrations fail:
  • Stop deployment.
  • Inspect logs, fix migration, re-run.
• For rollback:
  • For Workers, deploy the last known good version (

    wrangler deploy --tag <release-tag>

    when tags are used).
  • For schema-breaking migrations, recommend forward fixes rather than trying to downgrade D1 manually (unless very early in lifecycle).

It can also suggest tagging releases in Git (

v1.2.3

) and tying deploys to tags.

---

Security & Secrets Handling

This skill should ensure:

• No API tokens are echoed or logged.
• No credentials are committed to the repo.
• Only GitHub Secrets are used for tokens/IDs.

It can suggest:

• Restricting

  deploy

  workflow to protected branches (

  main

  ,

  release/*

  ).
• Requiring PR approvals + passing CI before merging into

  main

  .

---

Integration With Other Skills

• cloudflare-worker-deployment

  :
  • This skill uses that skill’s

    wrangler.toml

    and env naming.

• cloudflare-d1-migrations-and-production-seeding

  :
  • Hooks migration commands into CI/CD.

• cloudflare-r2-bucket-management-and-access

  :
  • R2 is configured in

    wrangler.toml

    ; CI/CD ensures deployments target correct env.

• hono-app-scaffold

  ,

  hono-d1-integration

  ,

  hono-r2-integration

  :
  • CI/CD pipelines run tests that hit these features and then deploy.

---

Example Prompts That Should Use This Skill

• “Create CI + deploy GitHub Actions for my Hono Worker on Cloudflare.”
• “Run tests and then deploy to staging on every push to develop.”
• “Deploy to production only on main, with D1 migrations included.”
• “Set up preview Workers for PRs with unique names.”
• “Refactor my existing GitHub Actions for Cloudflare into something clean and modular.”

For such tasks, rely on this skill to build a clean, robust GitHub Actions pipeline that automates testing, building, migrating, and deploying your Cloudflare Workers/Pages-based apps.