@appwarden/build-cloudflare-action

Overview

@appwarden/build-cloudflare-action is open source software that provides an easy-to-use GitHub Action for building and deploying Appwarden middleware to your Cloudflare domain. It generates a single Cloudflare Worker that protects all configured hostnames based on your Appwarden domain configuration.

For the product guide, start with Protect your Cloudflare project with Appwarden. If you still need to define the hostnames and settings the action will deploy, use the domain configuration guide. For CSP-specific behavior after deployment, see Managing your Content Security Policy.

Easy-to-use GitHub Action to build Appwarden for deployment to your Cloudflare project.

Read the docs to get started

Features

🚀 Automated Middleware Generation: Generates Cloudflare middleware populated with your Appwarden domain configuration compatible with any website
🛡️ Security Configuration: Configures Content Security Policy (CSP) and lock page settings
🧪 Debug Mode: Built-in debug mode for troubleshooting deployments
📦 Zero Configuration: Works out of the box with minimal setup required

Why Use This Action?

This GitHub Action is the official and recommended way to install Appwarden on any website deployed on Cloudflare.

Automatic Updates

The action automatically deploys the most up-to-date version of Appwarden without requiring any additional configuration. Your middleware stays current with the latest security features and improvements.

Configuration Management

Your middleware configuration is automatically applied from your domain configuration file. Simply define your settings once, and the action handles the rest.

Full CSP Support

This action fully supports Appwarden’s nonce-based Content Security Policy (CSP) functionality, enabling robust protection against browser-based attacks while maintaining compatibility with your application.

How It Works

The action builds a Cloudflare Worker script that runs on every request to the hostnames listed in the middleware section of your domain configuration files.

For example, given this domain configuration:

1
hostname: appwarden.cc
2
version: 1
3
websites:
4
  middleware:
5
    - url: appwarden.cc
6
      options:
7
        lock-page-slug: /maintenance
8
        csp-mode: report-only
9
        csp-directives:
10
          script-src:
11
            - "self"
12
            - "{{nonce}}"
13
    - url: tanstack.appwarden.cc
14
      options:
15
        lock-page-slug: /maintenance
16
        csp-mode: enforced
17
        csp-directives:
18
          img-src:
19
            - "self"

Deploying the Cloudflare Worker script generated by this action will include a route for each configured hostname:

Appwarden Middleware Routes

Inputs

Input	Description	Required	Default
`cloudflare-account-id`	Cloudflare account id	✅	-
`appwarden-api-token`	Appwarden API token	✅	-
`debug`	Enable debug mode	❌	`false`

Outputs

Output	Description
`middlewareVersion`	The version of @appwarden/middleware that was deployed
`hostnames`	Comma-separated list of hostnames the middleware was deployed to

Configuration

1
name: 🤖 Deploy Appwarden on Cloudflare
2
  on:
3
    push:
4
      branches:
5
        - main
6
env:
7
  CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
8
  APPWARDEN_API_TOKEN: ${{ secrets.APPWARDEN_API_TOKEN }}
9
  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
10
jobs:
11
  deploy-appwarden:
12
    name: Deploy Appwarden
13
    runs-on: ubuntu-latest
14
    steps:
15
      - uses: actions/checkout@v4
16
      - name: Setup node
17
        uses: actions/setup-node@v4
18
      - name: Setup npm
19
        run: npm ci --ignore-scripts
20
      # This builds the Appwarden middleware for Cloudflare
21
      - name: Build @appwarden/middleware
22
        id: build
23
        uses: appwarden/build-cloudflare-action@v3
24
        with:
25
          debug: true
26
          cloudflare-account-id: ${{ env.CLOUDFLARE_ACCOUNT_ID }}
27
          appwarden-api-token: ${{ env.APPWARDEN_API_TOKEN }}
28
      # This deploys the Appwarden middleware to Cloudflare
29
      - name: Deploy to Cloudflare
30
        uses: cloudflare/wrangler-action@v3.14.1
31
        env:
32
          APPWARDEN_API_TOKEN: ${{ env.APPWARDEN_API_TOKEN }}
33
        with:
34
          packageManager: npm # 4️⃣ add your package manager (e.g. npm, yarn, or pnpm)
35
          workingDirectory: .appwarden/generated-middleware
36
          environment: production
37
          accountId: ${{ env.CLOUDFLARE_ACCOUNT_ID }}
38
          apiToken: ${{ env.CLOUDFLARE_API_TOKEN }}
39
          secrets: |
40
            APPWARDEN_API_TOKEN
41
      - name: Deployment successful
42
        run: |
43
          echo "::notice::✅ Appwarden middleware v${{ steps.build.outputs.middlewareVersion }} deployed successfully to: ${{ steps.build.outputs.hostnames }} | View in Cloudflare dashboard: https://dash.cloudflare.com/${{ env.CLOUDFLARE_ACCOUNT_ID }}/workers-and-pages"

Read the docs to learn more

Development

Prerequisites

Node.js 22+
npm

Setup

1
# Clone the repository
2
git clone https://github.com/appwarden/build-cloudflare-action.git
3
cd build-cloudflare-action
4

5
# Install dependencies
6
npm install

Testing

This project uses Vitest for testing with comprehensive unit tests:

1
# Run tests in watch mode
2
npm test
3

4
# Run tests once
5
npm run test:run
6

7
# Run tests with coverage
8
npm run test:coverage

The test suite includes:

Unit tests for the main action logic
Template tests for Wrangler configuration generation
Validation tests for input schemas and domain validation
Mock tests for external API calls and file system operations

Code Quality

1
# Format code
2
npm run format
3

4
# Check formatting
5
npm run check:prettier
6

7
# Type checking
8
npm run check:types
9

10
# Build the action
11
npm run build

License

MIT