Build watch paths example: exclude directory
To trigger a build for any changes but exclude a docs/ directory, set Include paths to '*' and Exclude paths to 'docs/*'.
Cloudflare Workers · all subjects
configuration
366 notes in this subject, read out of this brain and free to use. This is page 2 of 7.
Build watch paths use case for monorepos
Build watch paths can be especially helpful when using a monorepo project structure to limit the number of builds being kicked off by specifying which paths should trigger builds.
Build watch paths bypass conditions
Workers will bypass path matching for a push event and default to building the project if: a push event contains 0 file changes (in case a user pushes an empty push event to trigger a build), or a push event contains 3000+ file changes or 20+ commits.
Build watch paths wildcard syntax
You can use wildcard syntax to match multiple path directories. A wildcard (*) matches zero or more characters and can be placed alone to match anything, or placed at the start or end of a rule for better control. For example, fix/* matches strings like fix/1, fix/bugs, or fix/.
Build watch paths static filepaths configuration
You can configure static filepaths by entering the precise name of the file you want to include or exclude, such as docs/README.md.
Build watch paths evaluation order
For each path in a push event, build watch paths are evaluated as follows: paths satisfying excludes conditions are ignored first, any remaining paths are checked against includes conditions, and if any matching path is found, a build is triggered. Otherwise the build is skipped.
Build watch paths configuration location
To configure build watch paths for a Workers project, navigate to the project Overview, then go to Settings > Build > Build watch paths.
Build settings apply to next build, not retries
When you update and save build settings, the updated settings will be applied to your next build. When you retry a build, the build configurations that exist when the build is retried will be applied.
Custom Builds not honored in Workers Builds
Workers Builds does not currently honor the configurations set in Custom Builds within your Wrangler configuration file.
Automatic configuration for projects without Wrangler config
If your repository does not have a Wrangler configuration file, the deploy command (wrangler deploy) will trigger automatic project configuration, which detects your framework, creates necessary configuration, and opens a pull request for review. Once merged, your project is configured and future builds will deploy normally.
Non-production branch deploy command customization examples
Non-production branch deploy command examples include: yarn exec wrangler versions upload (customize package manager used to run Wrangler), and npx wrangler versions upload --env staging (if using a Wrangler environment Worker, add environment flag; see Advanced Setups for details).
Default system environment variables in Workers Builds
The following system environment variables are injected by default (but can be overridden): CI (value: true; use case: changing build behaviour when run on CI versus locally), WORKERS_CI (value: 1; use case: changing build behaviour when run on Workers Builds versus locally), WORKERS_CI_BUILD_UUID (value: build-uuid-of-current-build; use case: passing the Build UUID to custom workflows), WORKERS_CI_COMMIT_SHA (value: sha1-hash-of-current-commit; use case: passing current commit ID to error reporting like Sentry), and WORKERS_CI_BRANCH (value: branch-name-from-push-event; use case: customizing build based on branch, e.g., disabling debug logging on production).
Build settings configuration table
Build settings are located at Settings > Build within your Worker and include: Git account (select Git account to use; reusable for future projects), Git repository (choose repository to connect), Git branch (branch to listen for commits; defaults to main), Build command (optional; e.g., npm run build for frameworks), Deploy command (customize specific Wrangler command; defaults to npx wrangler deploy), Non-production branch deploy command (defaults to npx wrangler versions upload), Root directory (optional; specify project path for monorepos), API token (optional; used to authenticate builds; auto-generated by default), and Build variables and secrets (optional; environment variables accessible only to build, not at runtime).
Deploy command customization examples
Deploy command examples include: npx wrangler deploy --assets ./public/ (deploy Worker with static assets from specified directory, or use assets binding instead), and npx wrangler deploy --env staging (if using a Wrangler environment Worker, add environment flag; see Advanced Setups for details).
Deploy Hook creation prerequisites
Before creating a Deploy Hook, ensure your Worker is connected to a Git repository.
Deploy Hook use cases
Deploy Hooks provide a way to trigger manual builds outside of git commits. Use Deploy Hooks to: rebuild automatically when content changes in a headless CMS, build on a schedule using an external cron service, or trigger deployments from custom CI/CD pipelines based on specific conditions.
Deploy Hook URL triggering
Send an HTTP POST request to a Deploy Hook URL to start a build. The request format is: curl -X POST "https://api.cloudflare.com/client/v4/workers/builds/deploy_hooks/<DEPLOY_HOOK_ID>". No Authorization header is needed; the unique identifier embedded in the URL acts as the authentication credential.
GitLab build watch paths affect commit status generation
When using build watch paths, only projects that trigger a build will generate a commit status.
GitLab commit status for monorepos
When you have one or multiple Workers connected to a repository in a monorepo setup, you can check the status of each build within GitLab via GitLab commit status. Commit statuses can be viewed by selecting the status icon next to a commit or by going to Build > Pipelines within your GitLab repository.
Enable GitLab merge request events for existing connections
New GitLab connections are automatically configured to receive merge request events for commenting functionality. For existing connections, you must manually enable 'Merge request events' in the Webhooks tab of your project's settings.
GitLab merge request comments for builds
When a commit is on a merge request, Cloudflare automatically posts a comment on the merge request with the status of the build. A preview URL is provided for builds that perform wrangler versions upload, allowing comparison of code changes alongside an updated version of the Worker.
Reinstall Cloudflare GitHub App procedure
To reinstall the Cloudflare GitHub App: 1) Go to installation settings page on GitHub by navigating to Settings > Builds for the Workers or Pages project and selecting Manage under Git Repository, or visit https://github.com/settings/installations (individual) or https://github.com/organizations/<YOUR_ORGANIZATION_NAME>/settings/installations (organization). 2) Select Uninstall "Cloudflare Workers and Pages" and confirm uninstall. 3) Go to Workers & Pages overview page, select Create application > Pages > Connect to Git. 4) Select + Add account, select the GitHub account, then select Install & Authorize. 5) You should be redirected to the create project page with your GitHub account or organization in the account list. 6) Attempt to make a new deployment with your project.
Effect of removing GitHub access on deployments
Removing access to GitHub will disable new builds for Workers and Pages projects that were connected to those repositories, though your previous deployments will continue to be hosted by Cloudflare Workers.
Remove Cloudflare access from entire GitHub account
To remove Cloudflare Workers and Pages access to your entire GitHub account, navigate to Uninstall "Cloudflare Workers and Pages" in the app settings and select Uninstall. This will revoke Cloudflare's access to all repositories from that GitHub account.
GitHub integration automatic deployment
Cloudflare supports connecting your GitHub repository to your Cloudflare Worker and will automatically deploy your code every time you push a change.
Remove Cloudflare access from individual GitHub repository
To remove access to an individual GitHub repository, navigate to Repository access in the GitHub app settings, select the Only select repositories option, and configure which repositories you would like Cloudflare to have access to.
Cloudflare Workers & Pages GitHub App
You can deploy projects to Cloudflare Workers from your company or side project on GitHub using the Cloudflare Workers & Pages GitHub App.
Build watch paths and check runs
When using build watch paths, only projects that trigger a build will generate a check run.
How to manage Git integration in Cloudflare dashboard
To manage your Git installation, go to the Workers & Pages page in the Cloudflare dashboard, select your Worker, then navigate to Settings > Builds, and select Manage under Git Repository. This allows you to manage repository access or troubleshoot installation issues by reinstalling.
Where to verify Git integration installation
You can verify that your Git integration has been installed by checking the GitHub Applications page at https://github.com/settings/installations (switch settings context to access organization settings if needed) or the GitLab Authorized Applications page at https://gitlab.com/-/profile/applications.
Git integration account types supported
Workers Builds provides direct integration with GitHub and GitLab accounts that are not self-hosted, including both individual and organization accounts.
Git integration build status monitoring
Git integration allows you to monitor build statuses directly in your Git provider. For GitHub, you can view build status through pull request comments and check runs. For GitLab, you can view build status through commit statuses.
Git integration automatic deployment
When you add a Git integration to your Cloudflare Worker, the Worker will automatically deploy your code every time you push a change to the connected repository.
Supported Git providers for Workers Builds
Cloudflare Workers Builds supports connecting to GitHub and GitLab repositories (cloud-hosted only). Self-hosted instances of GitHub or GitLab are not currently supported. For other Git providers like Bitbucket, you can use an external CI/CD provider such as GitHub Actions and deploy using Wrangler CLI.
Disable auto-deployment while keeping automatic builds as versions
To disable automatic deployments while still allowing builds to run automatically and save as versions without promoting them to active deployment, update the deploy command to: npx wrangler versions upload
Autoconfig automatically detects framework and creates PR
When connecting a repository without a Wrangler configuration file, autoconfig runs to detect your framework and creates a pull request with necessary configuration changes. A preview deployment is generated for testing before merge. Once merged, the project is ready for deployment.
Disconnect Worker from Git repository
To disconnect a Worker from GitHub or GitLab: (1) Go to Workers & Pages in Cloudflare dashboard, (2) Select the Worker to disconnect, (3) Select Settings then Builds, (4) Select Disconnect. To switch to a different repository, first disable builds, then reconnect to select the new repository.
Connect existing Worker to Git repository
To connect an existing Worker to GitHub or GitLab: (1) Go to Workers & Pages in Cloudflare dashboard, (2) Select the Worker to connect, (3) Select Settings then Builds, (4) Select Connect and follow prompts to configure build settings, (5) Push a commit to trigger build and deploy.
Create and connect a new Worker to Git repository
To create a new Worker and connect it to Git: (1) Go to Workers & Pages in Cloudflare dashboard, (2) Select Create application, (3) Select Get started next to Import a repository, (4) Select a Git account, (5) Select the repository to import, (6) Configure project and select Save and Deploy, (7) Preview Worker at its workers.dev subdomain.
Cloudflare wrangler-action for GitHub Actions
Cloudflare provides an official GitHub Action called cloudflare/wrangler-action for deploying Workers. It accepts apiToken and accountId as inputs, which should be passed from GitHub secrets.
GitHub Actions workflow to deploy a Worker
Example GitHub Actions workflow that deploys a Worker on push to the main branch: ```yaml name: Deploy Worker on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest timeout-minutes: 60 steps: - uses: actions/checkout@v6 - name: Build & Deploy Worker uses: cloudflare/wrangler-action@v3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} ``` This workflow uses the official Cloudflare wrangler-action@v3.
API token permissions for GitHub Actions deployment
To create an API token for deploying Workers via GitHub Actions, go to the Cloudflare dashboard Account API tokens page, select Create Token, open the Custom dropdown under Permission policies, and select Edit Cloudflare Workers. You should scope the token down to only the specific Cloudflare account where you will deploy the Worker.
Incorrect account_id in Wrangler configuration
If you see the error 'Could not route to /client/v4/accounts/<Account ID>/workers/services/<Worker name>, perhaps your object identifier is invalid? [code: 7003]', the Wrangler configuration file likely has an account_id for a different account. Remove the account_id argument or update it with your account's account_id, available in Workers & Pages Overview under Account Details.
Git integration troubleshooting
If you are running into errors associated with your Git integration, you can try removing access to your GitHub or GitLab integration from Cloudflare, then reinstalling the GitHub or GitLab integration.
Stale API token error during build
If you encounter an error stating 'Failed: The build token selected for this build has been deleted or rolled and cannot be used for this build', the API Token dropdown in Build Configuration settings may show stale tokens that were edited, deleted, or rolled. Create a new API Token and select it for the build.
Missing Wrangler configuration file error
If you see the error 'Missing entry-point: The entry-point should be specified via the command line (e.g. wrangler deploy path/to/script) or the main config field', a Wrangler configuration file is likely missing from the root directory. Navigate to Settings > Build > Build Configuration to update the root directory, or add a Wrangler configuration file to the specified directory.
WRANGLER_CI_OVERRIDE_NAME environment variable
On Wrangler v3 and up, Workers Builds automatically matches the name of the connected Worker by overriding it with the WRANGLER_CI_OVERRIDE_NAME environment variable.
Worker name matching with Wrangler Environments
The Worker name requirement does not apply to Wrangler Environments if the Worker name before the -<env_name> suffix matches the name in the Wrangler configuration file. For example, a Worker named my-worker-staging on the dashboard can be deployed from a repository containing a Wrangler configuration file with name = my-worker and [env.staging] using the deploy command npx wrangler deploy --env staging.
Worker name must match Wrangler configuration
When connecting a Git repository to your Workers project, the specified name for the Worker on the Cloudflare dashboard must match the name argument in the Wrangler configuration file located in the specified root directory. The build system uses the name argument in the Wrangler configuration file to determine which Worker to deploy. This requirement ensures consistency between the Worker's name on the dashboard and the deployed Worker.
Accessing build history in Cloudflare dashboard
To view your build history, go to your Worker project in the Cloudflare dashboard, select Deployment, select View Build History at the bottom of the page, and select the build you want to view. To retry a build, select the ellipses next to the build and select Retry build, or select Retry build on the Build Details page.
External CI/CD providers for Workers deployment
Cloudflare Workers can be deployed using external CI/CD providers as an alternative to Workers Builds. Popular supported providers include GitHub Actions and GitLab CI/CD. Other options including Terraform, CircleCI, and Jenkins can also be used to deploy Workers following a similar setup process.
Find Cloudflare account ID location
To find your Cloudflare account ID, refer to the Find account and zone IDs documentation.
Use npx wrangler deploy in GitLab Pipelines
For GitLab CI/CD pipelines, run `npx wrangler deploy` under the script key to deploy your Worker.
Wrangler authentication in CI/CD requires API token and account ID
In CI/CD environments, Wrangler cannot use the interactive `wrangler login` command. Instead, you must provide a Cloudflare API token and account ID to authenticate with the Cloudflare API.
Update database credentials in secrets
When you rotate or update database credentials, you must update the corresponding secrets in your Worker. Use the 'wrangler secret put' command to update secrets securely or update the secret directly in the Cloudflare dashboard.
Add Neon connection string as a secret in Wrangler
Add your Neon database connection string as a secret to your Worker using Wrangler. Get your connection string from the Neon Console under Connection Details, then run: npx wrangler secret put DATABASE_URL and paste your Neon database connection string when prompted.
PlanetScale connection methods for Workers
PlanetScale can be connected to Cloudflare Workers using either Hyperdrive (recommended) or the PlanetScale serverless driver (@planetscale/database). Both methods provide connection pooling and reduce round trips for secure connections. Hyperdrive offers lower latencies because it performs database connection setup and pooling across Cloudflare's network, supports native database drivers and ORMs, and is included in all Workers plans.
PlanetScale serverless driver fetch workaround
When using the @planetscale/database driver, the fetch configuration must delete the cache property from init before calling fetch due to a workerd limitation. This is done by setting fetch: (url, init) => { delete init['cache']; return fetch(url, init); } in the connection config.
PlanetScale serverless driver setup
To connect to PlanetScale using the @planetscale/database driver: (1) Create or import a PlanetScale database, (2) Create a products table with id, name, image_url, and category_id columns, (3) Insert test data, (4) Add DATABASE_HOST, DATABASE_USERNAME, and DATABASE_PASSWORD as secrets using 'npx wrangler secret put', (5) Install @planetscale/database package, (6) Use the connect() function with host, username, and password configuration.
PlanetScale serverless driver example
import { connect } from "@planetscale/database"; export default { async fetch(request, env) { const config = { host: env.DATABASE_HOST, username: env.DATABASE_USERNAME, password: env.DATABASE_PASSWORD, fetch: (url, init) => { delete init["cache"]; return fetch(url, init); }, }; const conn = connect(config); const data = await conn.execute("SELECT * FROM products;"); return new Response(JSON.stringify(data.rows), { status: 200, headers: { "Content-Type": "application/json", }, }); }, };