Documentation for Cloudflare Deployments

app/components/IntegrationsList.vue

@@ -30,6 +30,12 @@ const integrations = [
 		to: '/guides/integrations/netlify',
 		logo: '/docs/img/tutorials/netlify.png',
 	},
+	{
+		title: 'Cloudflare Workers',
+		description: 'Integrate Directus with Cloudflare Workers Builds to deploy Workers and track build status.',
+		to: '/guides/integrations/cloudflare-workers',
+		logo: '/docs/img/cloudflare.svg',
+	},
 	{
 		title: 'Framer',
 		description: 'Sync content between Directus collections and Framer\'s CMS in both directions.',

content/guides/10.deployments/0.index.md

@@ -8,7 +8,7 @@ If your frontend is statically generated or server-rendered using Directus as a
 ## Key Features
 
 - **Trigger deployments** for any connected project with one click
-- **Real-time status updates** via provider webhooks
+- **Deployment status** in Directus (Vercel and Netlify use webhooks; **Cloudflare Workers** updates via polling—use **Refresh** when needed)
 - **Build logs** with search and filtering
 - **Deployment history** with stats and duration tracking
 - **Role-based access control** using native Directus permissions
@@ -25,6 +25,10 @@ Connect Vercel projects and deploy from Directus.
 Connect Netlify sites and deploy from Directus.
 :::
 
+:::card{title="Cloudflare Workers" icon="simple-icons:cloudflare" to="/guides/integrations/cloudflare-workers"}
+Connect Cloudflare Workers (Workers Builds) and deploy from Directus.
+:::
+
 ::
 
 ## Getting Started
@@ -34,7 +38,7 @@ Connect Netlify sites and deploy from Directus.
 3. Select the projects you want to manage
 4. Start deploying
 
-For provider-specific setup instructions, see the [Vercel](/guides/integrations/vercel) or [Netlify](/guides/integrations/netlify) integration guides.
+For provider-specific setup instructions, see the [Vercel](/guides/integrations/vercel), [Netlify](/guides/integrations/netlify), or [Cloudflare Workers](/guides/integrations/cloudflare-workers) integration guides.
 
 ## Security
 

content/guides/10.deployments/1.security.md

@@ -40,13 +40,14 @@ Each permission can include access policy filters to limit what a user can see o
 For example:
 
 - Filter `provider` = `vercel` on `directus_deployments` to give a role access to Vercel deployments only
+- Filter `provider` = `cloudflare` on `directus_deployments` to give a role access to Cloudflare Workers deployments only
 - Filter `name` on `directus_deployment_projects` to limit access to specific projects by name
 
 When filtering by provider or project, apply matching filters across all three collections to keep access consistent.
 
 ## Credential Protection
 
-Provider API tokens (Vercel Personal Access Token, Netlify Personal Access Token) are:
+Provider API tokens (Vercel Personal Access Token, Netlify Personal Access Token, Cloudflare user-scoped API token) are:
 
 - **Encrypted at rest** in the database
 - **Masked in the UI** so they cannot be read back after saving
@@ -70,4 +71,8 @@ Set up and configure the Vercel integration.
 Set up and configure the Netlify integration.
 :::
 
+:::card{title="Cloudflare Workers Integration" icon="simple-icons:cloudflare" to="/guides/integrations/cloudflare-workers"}
+Set up and configure the Cloudflare Workers integration.
+:::
+
 ::

content/guides/12.integrations/6.cloudflare-workers/.navigation.yml

@@ -0,0 +1,2 @@
+title: Cloudflare Workers
+headline: Cloudflare Workers

content/guides/12.integrations/6.cloudflare-workers/0.index.md

@@ -0,0 +1,97 @@
+---
+id: cloudflare-workers-integration
+title: Cloudflare Workers
+description: Integrate Directus with Cloudflare Workers Builds to trigger deployments, track build progress, and manage Workers from within your Directus instance.
+technologies:
+  - cloudflare
+---
+
+When your frontend runs on Cloudflare Workers and pulls content from Directus, publishing a content change doesn't automatically trigger a new build. This integration adds deployment controls to Directus so your team can trigger builds, track progress, and review logs without switching to the Cloudflare dashboard.
+
+::callout{icon="heroicons-outline:rocket-launch"}
+**Quick Start**
+1. **Enable the Deployment module** in your Directus project settings (under **Modules**).
+2. **Link Cloudflare**: open the Deployment module and choose **Configure Cloudflare Workers** (or add the provider from **Settings**).
+3. **Enter credentials and Account ID** (see below), save, then **select which Workers** to manage.
+4. **Deploy** from a Worker's project view, or use an optional **Deploy Hook** action if you configured hook URLs.
+5. **Optional:** To record builds started **outside** Directus (for example CI) without relying only on opening the app, set up **Cloudflare Queues + Workers Builds event subscriptions** and paste an **Event Subscription Queue ID**. See **[Build events (queue) →](/guides/integrations/cloudflare-workers/build-events)**.
+::
+
+:partial{content="deployment-public-instance"}
+
+## Getting Started
+
+### Link Your Cloudflare Account
+
+1. In Directus, go to **Settings**.
+2. Under **Modules**, enable **Deployment**.
+3. Open the **Deployment** module from the primary navigation.
+4. Select **Configure Cloudflare Workers** (the label may appear as **Cloudflare Workers** in the provider list).
+5. Provide your credentials:
+   - **Personal Access Token**: a user-scoped Cloudflare API token (not an account token) with at least:
+     - **Workers Builds Configuration: Edit**
+     - **Workers Scripts: Read**
+   - **Account ID**: your Cloudflare account ID (the 32-character hex string shown in the dashboard URL and account overview).
+
+   If you use **[build events via a queue](/guides/integrations/cloudflare-workers/build-events)**, add **Account → Queues → Edit** to that token (read + write) so Directus can pull and acknowledge messages.
+
+   Use **Open Cloudflare Settings** in the form to create or manage tokens in the Cloudflare dashboard.
+6. Click **Save** to validate and continue to project selection.
+
+Directus stores the token encrypted. Changing the token or Account ID after setup can make previously selected Workers unavailable until you update credentials or re-select them.
+
+### Workers Builds Prerequisites
+
+For a Worker to appear as **deployable** in Directus, Cloudflare must have:
+
+- **Workers Builds** enabled for that Worker.
+- A **connected Git repository** and a **build trigger** configured.
+
+If Directus shows that a Worker is not deployable, open **Worker Settings → Builds** in the Cloudflare dashboard and complete setup (the in-app copy points you there).
+
+### Configure Workers
+
+1. From the **Cloudflare Workers** configuration screen, choose **which Workers** Directus should manage.
+2. Click **Save** to store the selection.
+3. Return to integration settings anytime to add or remove Workers.
+
+::callout{icon="material-symbols:warning" color="warning"}
+**Removing Workers**
+<br>
+Removing a Worker from this integration **permanently deletes** all deployment history stored in Directus for that Worker. This cannot be undone.
+::
+
+### Optional: Deploy Hooks
+
+In Cloudflare, create **Deploy Hook** URLs under **Worker Settings → Builds → Deploy Hooks**. In Directus, you can add each hook with a **name** and **URL**. Those hooks appear in the **Deploy** menu as extra actions (for example **Deploy via …**) alongside the default production deploy.
+
+### Optional: Build events (Cloudflare Queue)
+
+Without an **Event Subscription Queue ID**, Directus still triggers builds and updates run status when you open deployment views in the app. To **create and update runs automatically** when builds start or finish in Cloudflare, including builds started by git push or CI, configure a Cloudflare **Queue** with **HTTP pull**, add **Workers Builds event subscriptions** for each Worker, then paste the queue ID in Directus.
+
+Step-by-step guidance (Cloudflare dashboard, Wrangler, tokens, and troubleshooting) lives here:
+
+**[Build events (queue) →](/guides/integrations/cloudflare-workers/build-events)**
+
+### View Your Workers
+
+Once set up, connected Workers appear under the **Cloudflare Workers** provider. From here you can:
+
+- See selected Workers and their deployment activity.
+- Open a Worker to run deployments and browse **deployment runs**, logs, and links.
+
+::callout{icon="material-symbols:shield" color="info"}
+**Permissions**
+<br>
+The Deployment module uses Directus native permissions. See **[Deployment Security](/guides/deployments/security)** for details on configuring roles and access policies.
+::
+
+## Documentation
+
+**[Working with Deployments →](/guides/integrations/cloudflare-workers/deployments)**
+
+Trigger deployments, track build status, and view logs from within Directus.
+
+**[Build events (queue) →](/guides/integrations/cloudflare-workers/build-events)**
+
+Optional: wire Workers Builds into a Cloudflare Queue so Directus can ingest build events without a custom webhook URL.

content/guides/12.integrations/6.cloudflare-workers/build-events.md

@@ -0,0 +1,79 @@
+---
+id: cloudflare-workers-build-events
+title: Build events (queue)
+description: Optional Cloudflare Queues and Workers Builds event subscriptions so Directus can create and update deployment runs when builds run outside the app.
+technologies:
+  - cloudflare
+---
+
+::callout{icon="material-symbols:info-outline" color="info"}
+**Optional setup**
+<br>
+The Cloudflare Workers deployment provider works without a queue. Trigger builds from Directus and view run status and logs in the app. Add a **queue** when you want runs to update **automatically** for builds started elsewhere (for example git push or CI), similar to webhook-based providers, without hosting your own proxy.
+::
+
+## Before You Start
+
+- Complete the **[Cloudflare Workers](/guides/integrations/cloudflare-workers)** provider setup (token, Account ID, Worker selection).
+- In Cloudflare, enable **Workers Builds** and connect Git for each Worker you will subscribe to.
+
+**[← Back to Cloudflare Workers Integration](/guides/integrations/cloudflare-workers)**
+
+**[Working with Deployments →](/guides/integrations/cloudflare-workers/deployments)**
+
+## What you are configuring
+
+1. A **Cloudflare Queue** that receives Workers Builds events (started, succeeded, failed, canceled).
+2. **HTTP pull** enabled on that queue so the Directus API can pull and acknowledge messages from Cloudflare's queue API.
+3. An **event subscription** per Worker you care about, all writing to the **same** queue. Directus stores **one queue ID**; each message identifies the Worker so Directus can route it to the right project.
+4. In Directus, the **Event Subscription Queue ID** field on the **Cloudflare Workers** provider, plus an API token that can use **Queues** (see below).
+
+## In Cloudflare
+
+1. **Create a queue** (Workers & Pages → **Queues**).
+   - Open **Cloudflare Dashboard** → your account → **Workers & Pages** → **Queues**.
+   - Click **Create queue**.
+   - Give it a clear name (for example `directus-build-events`).
+   - Open the queue details and copy the queue **ID**. Paste this exact ID into Directus later.
+
+   You can also create queues with Wrangler (`queues create`) if your team uses CLI-first workflows.
+
+2. **Enable HTTP pull** on that queue:
+   - In the queue details, open **Consumers**.
+   - Add an **HTTP pull consumer**.
+   - Confirm the queue now shows an HTTP pull consumer as active.
+
+   Wrangler example:
+
+   ```bash
+   npx wrangler queues consumer http add <queue-name>
+   ```
+
+   If the queue already has a **push** consumer, Cloudflare may require you to remove it before HTTP pull works.
+
+3. **Create an event subscription** for each Worker Directus should track:
+   - In the same queue, open **Subscriptions** and click **Add subscription**.
+   - Source: **Workers Builds** / worker (labels in the dashboard may vary).
+   - **Worker**: the script that uses Workers Builds (the same one you deploy from Directus or CI).
+   - **Events**: include at least **started**, **succeeded**, **failed**, and **canceled** (or the subset you need).
+   - Save the subscription and confirm it appears in the queue's subscriptions list.
+
+   Use the dashboard **Subscriptions** UI on the queue, or Wrangler (`queues subscription create`) if the UI is unreliable.
+
+**Multiple Workers:** add one subscription per Worker, each targeting the **same** queue. In Directus you still paste that queue's ID only once.
+
+## In Directus
+
+1. Open **Settings** → **Deployments** (or your product's deployment settings) and edit the **Cloudflare Workers** provider.
+2. Paste the queue **ID** into **Event Subscription Queue ID** and save.
+3. Keep every Worker you want events for **selected** in the provider's project list. Directus matches Cloudflare's worker name on each message to those projects.
+
+**API token:** the token used for this provider needs **Account → Queues → Edit** (read and write) in addition to your existing Workers Builds and Scripts permissions. A single combined token is the usual approach.
+
+**Polling:** Directus pulls the queue on a timer (about **once per minute** by default). Host administrators can override the schedule with the environment variable `DEPLOYMENT_CLOUDFLARE_QUEUE_POLL_SCHEDULE` using the same cron style as other Directus scheduled jobs.
+
+
+## Next Steps
+
+- **[Working with Deployments](/guides/integrations/cloudflare-workers/deployments)**: trigger builds, status, and logs
+- **[← Back to Cloudflare Workers Integration](/guides/integrations/cloudflare-workers)**

content/guides/12.integrations/6.cloudflare-workers/deployments.md

@@ -0,0 +1,80 @@
+---
+id: cloudflare-deployments
+title: Deployments
+description: Trigger Workers Builds, track deployment status, and view logs for Cloudflare Workers from Directus.
+technologies:
+  - cloudflare
+---
+
+After linking your Cloudflare account and selecting Workers, manage deployments from the **Deployment** module.
+
+**[← Back to Cloudflare Workers Integration](/guides/integrations/cloudflare-workers)**
+
+## Triggering Deployments
+
+1. Open **Deployment**.
+2. Choose **Cloudflare Workers**.
+3. Select the Worker you want to build.
+4. Open the **Deploy** menu (top right):
+   - **Deploy**: triggers a build via the configured production flow (Workers Builds / trigger).
+   - **Deploy via …**: appears when you saved **Deploy Hook** entries; POSTs to that hook URL.
+   - **Refresh**: reloads runs and project data from Cloudflare.
+
+A new run appears in the list with the provider's build identifier when available.
+
+## Monitoring Deployment Status
+
+In the runs list, you will typically see:
+
+- **Deployment ID**: Cloudflare's identifier for the build.
+- **Status**: for example **Building**, **Ready**, **Failed**, **Canceled** (per Directus labels).
+- **Target**: for example production, when Cloudflare exposes it.
+- **Started**: when the build started.
+- **Author**: who triggered the deployment when known.
+
+**How status updates**
+
+- Whenever you open a run or list, Directus asks Cloudflare for the latest status and logs.
+- If you configured an **Event Subscription Queue ID** on the Cloudflare Workers provider, Directus also **polls Cloudflare's queue on a schedule** (about once a minute by default) and updates runs when Workers Builds events arrive. That helps when builds start outside Directus (for example CI). See **[Build events (queue)](/guides/integrations/cloudflare-workers/build-events)**.
+
+If a run still looks stale after a build finishes, reopen the run details to request the latest data from Cloudflare.
+
+## Viewing Build Logs
+
+1. Open a deployment from the Worker's run list.
+2. Review logs as Cloudflare returns them (timestamps and log levels as shown in the UI).
+3. **Search** and filter by log level where available.
+4. **Download** logs if you need a file copy.
+
+## Exporting Logs
+
+1. Open the deployment detail view.
+2. Use **Download** (or the download control shown in the toolbar) to save logs.
+
+## Visiting Builds in Cloudflare
+
+From deployment details, use **Visit** or **Open in Cloudflare Workers** (wording per Directus version) to open the build or dashboard in Cloudflare when a URL is available.
+
+## Canceling a Deployment
+
+If the run is still active and Cloudflare allows canceling it, the detail view may offer **Stop** or cancel with a confirmation. If the action is not available, cancel from the Cloudflare dashboard.
+
+## Best Practices
+
+**Deployment Workflow**
+
+- Complete Workers Builds setup (Git repository and build trigger) in Cloudflare before deploying from Directus.
+- Deploy after publishing content changes that affect your Worker or site.
+- Monitor initial deployments after setup to confirm builds complete successfully.
+
+**Troubleshooting**
+
+- For failed runs, review build logs first, then verify build settings and API token permissions in Cloudflare.
+- Rotate API tokens in Cloudflare and update Directus when you revoke old tokens.
+
+## Next Steps
+
+- **[← Back to Cloudflare Workers Integration](/guides/integrations/cloudflare-workers)**
+- **[Build events (queue)](/guides/integrations/cloudflare-workers/build-events)**: optional queue + subscriptions for automatic run updates
+- **[Deployment Security](/guides/deployments/security)**: roles and access control
+- **[Vercel Integration](/guides/integrations/vercel)** and **[Netlify Integration](/guides/integrations/netlify)**: other supported deployment providers