Deploy hooks

Create the Deploy Hook in Cloudflare and the webhook in the source repository specified by DOCS_REPO. Once connected, a push to the documentation repository triggers a template build and publishes the latest content. The same process works for public and private documentation sources.

Push to the documentation repository
  → GitHub webhook
  → Cloudflare Deploy Hook
  → Build the selected template repository branch
  → Fetch the latest documents from DOCS_BRANCH
  → Publish the site after a successful build

Before you start

Complete a successful site build first. Confirm that Workers Builds is connected to the template repository and can read the configured DOCS_REPO, DOCS_BRANCH, and documentation paths. The account adding the source repository webhook also needs permission to manage that repository’s webhooks.

If the documents and template already share the same Builds-connected repository and build branch, the existing push trigger can update the documents without another hook. Follow this guide when the documentation source is in a separate repository, or on another branch without an existing build trigger.

For a private source, configure the DOCS_TOKEN build secret first; see Private repositories. A Deploy Hook triggers a build but does not grant permission to read private documents.

1. Create a Cloudflare Deploy Hook

1. Open Workers & Pages → your Worker → Settings → Builds → Deploy Hooks.
2. Create a hook with a descriptive name, such as “Documentation updates”.
3. Select the template repository branch to build. It must contain working template code and build configuration.
4. Copy the actual Hook URL generated by Cloudflare; you will enter it in GitHub next.

The branch selected here is the template build branch. DOCS_BRANCH controls the source documentation branch read by the build scripts. These are independent settings and may differ.

Keep the existing build command, deploy command, and root directory. This process connects a GitHub webhook directly to a Cloudflare Deploy Hook; no new receiving endpoint or GitHub Actions workflow is required.

2. Create a webhook in the documentation repository

Open the GitHub repository specified by DOCS_REPO and go to Settings → Webhooks → Add webhook. Confirm that this is the repository where you maintain the Markdown files. If the template and documents are stored separately, add this webhook to the documentation repository.

Save the webhook. GitHub may send a ping to check the connection; this does not confirm that the documents have been updated automatically.

The Hook URL itself is a trigger credential. Store it only in the webhook settings that need it, not in public variables, documentation, or the repository. Store DOCS_TOKEN only in Cloudflare Build variables and secrets, using the Secret type. It is used for Git fetch and is not a webhook secret for this process.

3. Verify a documentation update

Commit and push an easily recognizable text change to the source branch specified by DOCS_BRANCH, then check:

1. In GitHub, open Settings → Webhooks → your webhook → Recent Deliveries, find the push delivery, and inspect the response status. A 2xx response means the hook accepted the request; it does not confirm a successful build or deployment.
2. In the Worker’s Builds, find the new build and confirm that both build and deployment succeeded. Read the build log if either failed.
3. Open the site and confirm that the edited text, page links, and images display correctly.
4. Compare the documentation commit SHA in the build log, site footer, or /_build.json to confirm which source version was published.

At build time, the template fetches the latest commit on DOCS_BRANCH. It does not pin the build to the commit SHA in the webhook event. If several pushes occur close together, the fetched SHA may be newer than the triggering commit. Use the SHA recorded by the build and displayed by the site.

A successful ping or a push response of 2xx does not replace these checks. Confirm automatic publication using both the Cloudflare build result and the updated site content.

Branches and duplicate triggers

A repository-level GitHub push webhook can also receive pushes to other branches or changes that affect no documentation files. These events can trigger extra builds. This connection does not filter events by file path; the build always reads the configured DOCS_BRANCH.

A successful push to another branch does not mean that branch’s documents will appear on the site. To switch the documentation branch, change the DOCS_BRANCH build variable or the template repository’s public default, then rebuild.

If a previous build for the same hook is still queued or initializing, repeated requests return the existing build with already_exists: true and may not create another build record. After the previous build leaves those stages, another request can create a new build.

Replace or remove a hook

To replace a hook, create a new one in Cloudflare, update the GitHub webhook’s Payload URL, save, and verify a documentation push. Remove the old hook after the new connection works.

When the documentation repository no longer needs to trigger builds, disable or delete its GitHub webhook and remove the unused Cloudflare hook. Rotate private repository tokens through the build secret separately from hook changes.

Troubleshooting

Official references

• Cloudflare Workers Builds Deploy Hooks
• Creating GitHub webhooks