[Workers] Add Builds API guide with workflow examples by yomna-shousha · Pull Request #28229 · cloudflare/cloudflare-docs

yomna-shousha · 2026-02-10T04:12:53Z

Addressed bonk's review

This PR adds a new guide for using the Workers Builds API.

The guide covers:

Required API token permissions (Workers Builds Configuration + Workers Scripts Read)
The Worker tag vs Worker name distinction (external_script_id)
Step-by-step workflow: get Worker tag → get trigger UUID → trigger builds
Production vs preview triggers and environment variables
Example scripts for redeploying and setting up builds from scratch

- Document required permissions (Workers Builds Configuration + Workers Scripts Read) - Explain Worker tag vs Worker name (external_script_id) distinction - Add complete workflow: get Worker tag → get trigger UUID → work with builds - Include production vs preview trigger setup with environment variables - Add redeploy script example for refreshing build-time data - Add end-to-end setup example from GitHub repo connection to first build - Add troubleshooting section for common errors

yomna-shousha · 2026-02-10T04:13:52Z

/bonk review this PR using the docs agent guidelines

github-actions · 2026-02-10T04:13:59Z

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
`/src/assets/images/workers/`	`@cloudflare/workers-docs`, `@GregBrimble`, `@irvinebroque`, `@WalshyDev`, `@cloudflare/deploy-config`, `@cloudflare/pcx-technical-writing`, `@cloudflare/wrangler`, `@mattietk`
`/src/content/docs/workers/ci-cd/`	`@irvinebroque`, `@aninibread`, `@GregBrimble`, `@cloudflare/pcx-technical-writing`, `@yomna-shousha`

ask-bonk · 2026-02-10T04:16:18Z

Review complete. The findings are summarized above. No build-breaking issues were found, and the three recommended changes (#6 troubleshooting overlap, #8 editorial tone, #9 ofetch) are all minor improvements.

github run

- Remove editorial tone about API docs (line 37) - Simplify troubleshooting section, link to dedicated troubleshoot page - Replace ofetch with built-in fetch in redeploy example

github-actions · 2026-02-10T04:33:41Z

Preview URL: https://37cc879b.preview.developers.cloudflare.com
Preview Branch URL: https://yomna-workers-builds-api-guide.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/workers/ci-cd/builds/api-reference/	https://yomna-workers-builds-api-guide.preview.developers.cloudflare.com/workers/ci-cd/builds/api-reference/

irvinebroque

Let's make sure that references to the REST API link back to the relevant links to Builds API docs at api.cloudflare.com

irvinebroque · 2026-02-14T18:37:38Z

+
+### 1. Create an API token with the correct permissions
+
+The Builds API requires a user-scoped API token with specific permissions. Create your token at [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens).


Does it actually require user scoped? Or is it just that in dash we default to user scoped for ?

irvinebroque · 2026-02-14T18:39:45Z

+| Permission | Access | Why you need it |
+|------------|--------|-----------------|
+| Workers Builds Configuration | Edit | Trigger builds, update triggers, manage environment variables |
+| Workers Scripts | Read | Retrieve Worker tags (required for all Builds API calls) |


@stritt @AdamBouhmad if dash supported deeplinking to API token creation, with specific permissions (or future: roles) as a query param

Then from docs like this we could send someone straight into creating a token with exactly the right permissions / roles

cc @vy-ton

irvinebroque · 2026-02-14T18:41:54Z

+
+Here is the typical workflow for interacting with the Builds API:
+
+```txt


Love having diagram here — maybe worth experimenting with conveying this via Mermaid? Will render nicely

irvinebroque · 2026-02-14T18:43:07Z

+
+Call the Workers Scripts API to list all your Workers and find the `tag` for the Worker you want to work with:
+
+```bash


Is the goal of this guide to show you how you could manually do this via CLI or show you a bit of code that you might write in TypeScript to program around the builds API and have it do things?

irvinebroque · 2026-02-14T18:43:45Z

+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 2. Get trigger UUID (using the Worker tag)                      │


At this point I'm not sure we have explained what a trigger is? Does someone need to understand that in order to follow?

- Clarify user-scoped token requirement and link to build token docs - Update Worker tags section title to include external_script_id - Rewrite trigger explanation with production/preview context - Revert to ASCII diagrams for workflow overview - Restructure Examples section with diagrams for each use case - Add multiple sources for obtaining build_uuid - Fix anchor links and API reference URLs

yomna-shousha · 2026-02-24T05:08:32Z

/bonk Task: Convert ASCII diagrams to Mermaid in the Builds API reference
Convert the three ASCII flowchart diagrams in /Users/yomnashousha/cloudflare-docs/src/content/docs/workers/ci-cd/builds/api-reference.mdx to Mermaid format.
Diagram locations:

Workflow overview (around line 64) - General 3-step workflow
Set up Workers Builds from scratch (around line 289) - 6-step setup flow
Redeploy current deployment (around line 474) - 3-step redeploy flow

Make them even more detailed than the ASCII diagrams based on the text they represent if need be

Co-authored-by: yomna-shousha <yomna-shousha@users.noreply.github.com>

ask-bonk · 2026-02-24T05:12:45Z

Zero errors. All three ASCII diagrams have been successfully converted to Mermaid format. Here's a summary of the changes:

Diagram 1: Workflow overview (line 68)

Converted from ASCII boxes to a flowchart TD with a decision node (diamond shape) at step 3 that branches out to the four build operations: trigger, list, get logs, and cancel
Added the "Cancel a build" operation which wasn't in the original ASCII but is documented in the page

Diagram 2: Set up Workers Builds from scratch (line 294)

Converted the 6-step linear flow to a flowchart that shows the fork at step 4 where production and preview triggers are created in parallel, then converge back at step 5 (environment variables)
Added detail about the different deploy commands (wrangler deploy vs wrangler versions upload) and branch patterns directly in the diagram nodes

Diagram 3: Redeploy current deployment (line 452)

Converted the 3-step linear flow with expanded descriptions explaining the purpose of each step (finding the live deployment, looking up the original build metadata, and rebuilding with same parameters)

github run

- Fix anchor link (#3-understand-triggers → #3-what-is-a-trigger)

yomna-shousha · 2026-02-24T06:19:40Z

/bonk instead of &{tag&}, &{uuid&}, and &{name&} can you make sure the correct fields are generated if it is incorrect
can you also make the Redeploy current deployment mermaid diagram horizontal

can you remove the text after the endpoint for all diagrams, except ones that are like → note account ID

for all mermaid diagrams, can you bold the title instead of the endpoint

do you need an endpoint for these: Production trigger and Preview trigger (optional)

Co-authored-by: yomna-shousha <yomna-shousha@users.noreply.github.com>

ask-bonk · 2026-02-24T06:23:06Z

All changes are complete. Here's a summary of what was changed across all three Mermaid diagrams:

Diagram 1: Workflow overview (line 68)

Fixed placeholders: {tag} → {worker_tag}, {uuid} → {trigger_uuid} / {build_uuid} (matching the curl commands)
Bolded titles instead of endpoints (e.g., <strong>1. Get Worker tag</strong> instead of <strong>GET /workers/scripts</strong>)
Removed descriptive text after endpoints (e.g., removed "Find your Worker and note the tag UUID")

Diagram 2: Set up Workers Builds from scratch (line 294)

Fixed placeholder: {uuid} → {trigger_uuid}
Bolded titles instead of endpoints
Removed descriptive text after endpoints (e.g., removed "Links your GitHub repo to Cloudflare", "Save the repo_connection_uuid")
Kept the → note account ID / → note repo ID annotations on the GitHub API calls (as requested)
No endpoints on Production/Preview trigger nodes — they are configuration sub-items of step 4 (which already shows POST /builds/triggers), not separate API calls

Diagram 3: Redeploy current deployment (line 452)

Changed to horizontal layout (flowchart LR instead of flowchart TD)
Fixed placeholders: {name} → {worker_name}, {id} → {version_id}, {uuid} → {trigger_uuid}
Bolded titles instead of endpoints
Removed descriptive text after endpoints (e.g., removed "Find the current live deployment and note the version_id")

github run

github-actions · 2026-03-11T03:51:28Z

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label is helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant).

…rams

GregBrimble · 2026-03-30T15:40:52Z

+```bash
+curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/triggers" \
+  --header "Authorization: Bearer <API_TOKEN>" \
+  | jq '.result[] | {trigger_uuid, trigger_name, branch_includes, branch_excludes}'


Are we comfortable assuming jq is installed for everyone? It isn't a default package on any common OSes. Even just a link out to where you can download it would be helpful for people that are unfamiliar.

GregBrimble · 2026-03-30T15:42:27Z

+
+Save the `trigger_uuid` for the trigger you want to work with. Remember, you will have at most two triggers: one for your production branch (for example, `main`) that deploys to your live Worker, and optionally one for all other branches that creates preview deployments.
+
+## Step 3: Work with builds


It's kinda weird to talk about using a trigger before you show how to create one. I know that comes later on in the doc, but I'd consider flipping the order.

GregBrimble · 2026-03-30T15:43:22Z

+
+The response includes `build_uuid` for each build, which you need for getting logs or canceling builds.
+
+### Get build logs


Do we have a WebSocket streaming endpoint we want to document?

GregBrimble · 2026-03-30T15:46:44Z

+  --data '{
+    "branch": "{branch}",
+    "commit_hash": "{commit_hash}"
+  }'


You said earlier that you can specify branch "or" commit_hash. Is it "and/or"?

GregBrimble

small-ish nits

yomna-shousha requested review from GregBrimble, aninibread and irvinebroque as code owners February 10, 2026 04:12

yomna-shousha requested a review from a team February 10, 2026 04:12

github-actions Bot added product:workers Related to Workers product size/l labels Feb 10, 2026

github-actions Bot assigned aninibread, GregBrimble and irvinebroque Feb 10, 2026

[Workers] Address bonk review feedback

f923210

- Remove editorial tone about API docs (line 37) - Simplify troubleshooting section, link to dedicated troubleshoot page - Replace ofetch with built-in fetch in redeploy example

irvinebroque reviewed Feb 14, 2026

View reviewed changes

3 ASCII diagrams converted to Mermaid.

1b4799f

Co-authored-by: yomna-shousha <yomna-shousha@users.noreply.github.com>

[Workers] Fix broken anchor link to trigger section

14e3049

- Fix anchor link (#3-understand-triggers → #3-what-is-a-trigger)

yomna-shousha force-pushed the yomna/workers-builds-api-guide branch from c4de607 to 14e3049 Compare February 24, 2026 06:13

Fixed 3 Mermaid diagrams: fields, style

4346c09

Co-authored-by: yomna-shousha <yomna-shousha@users.noreply.github.com>

github-actions Bot added the stale label Mar 11, 2026

[Workers] Standardize redeploy example to curl, add SVG workflow diag…

d0eda80

…rams

yomna-shousha requested review from MattieTK and WalshyDev as code owners March 30, 2026 15:08

yomna-shousha requested review from a team as code owners March 30, 2026 15:08

GregBrimble reviewed Mar 30, 2026

View reviewed changes

GregBrimble approved these changes Mar 30, 2026

View reviewed changes

yomna-shousha added 2 commits March 30, 2026 13:06

[Workers] Address Greg's review comments on Builds API reference

ffbfd7a

[Workers] Remove accidentally committed preview-builds.mdx

37cc879

yomna-shousha enabled auto-merge (squash) March 30, 2026 17:14

yomna-shousha merged commit c9f24c2 into production Mar 30, 2026
12 checks passed

yomna-shousha deleted the yomna/workers-builds-api-guide branch March 30, 2026 17:29


		### 1. Create an API token with the correct permissions

		The Builds API requires a user-scoped API token with specific permissions. Create your token at [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens).


		Here is the typical workflow for interacting with the Builds API:

		```txt


		Call the Workers Scripts API to list all your Workers and find the `tag` for the Worker you want to work with:

		```bash


		Save the `trigger_uuid` for the trigger you want to work with. Remember, you will have at most two triggers: one for your production branch (for example, `main`) that deploys to your live Worker, and optionally one for all other branches that creates preview deployments.

		## Step 3: Work with builds


		The response includes `build_uuid` for each build, which you need for getting logs or canceling builds.

		### Get build logs

Uh oh!

Conversation

yomna-shousha commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yomna-shousha commented Feb 10, 2026

Uh oh!

github-actions Bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ask-bonk Bot commented Feb 10, 2026

Uh oh!

github-actions Bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

irvinebroque left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yomna-shousha commented Feb 24, 2026

Uh oh!

ask-bonk Bot commented Feb 24, 2026

Diagram 1: Workflow overview (line 68)

Diagram 2: Set up Workers Builds from scratch (line 294)

Diagram 3: Redeploy current deployment (line 452)

Uh oh!

yomna-shousha commented Feb 24, 2026

Uh oh!

ask-bonk Bot commented Feb 24, 2026

Diagram 1: Workflow overview (line 68)

Diagram 2: Set up Workers Builds from scratch (line 294)

Diagram 3: Redeploy current deployment (line 452)

Uh oh!

github-actions Bot commented Mar 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GregBrimble Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GregBrimble left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yomna-shousha commented Feb 10, 2026 •

edited

Loading

github-actions Bot commented Feb 10, 2026 •

edited

Loading

github-actions Bot commented Feb 10, 2026 •

edited

Loading

GregBrimble Mar 30, 2026 •

edited

Loading