cloudflare.pages.build-and-deploy

Build a SPA (dist + Pages Functions) from a git ref on an Orkestia runner group, then deploy it via cloudflare.pages.deploy. Fully in-platform — no GitHub Actions.

Overview

Property	Value
Workflow type	Linear
Library	App-cloudflare
Version	1.0

Input Schema

Field	Type	Required	Default	Description
`organization_uuid`	uuid	Yes	—	Organization UUID.
`pages_project_uuid`	uuid	No	—	Target Pages project row UUID.
`project_name`	string	No	—	Pages project name (with connection_uuid) when pages_project_uuid is not given.
`connection_uuid`	uuid	No	—	Cloudflare connection UUID (with project_name).
`github_repository_uuid`	uuid	No	—	GitHubRepository UUID to build from; used to bootstrap the Pages project (with project_name+connection_uuid) on first run and to backfill an existing project's repo binding.
`source_ref`	string	No	—	Branch/tag to build; default = project's production_branch.
`commit_sha`	string	No	—	Specific commit SHA to build.
`runner_group_uuid`	uuid	No	—	Runner group to build on; default = org's first active generic runner group.
`build_command`	string	No	—	Build command; default 'npm ci && npm run build'.
`output_dir`	string	No	—	Static output dir; default 'dist'.
`functions_dir`	string	No	—	Pages Functions dir to include; default 'functions'.
`node_version`	string	No	—	Node.js version for the build.
`env_vars`	json	No	—	Optional plain (non-secret) Pages project env vars, as a JSON map name->value. Applied to the production environment via the Cloudflare plugin before the deploy binds them (both modes).
`secrets`	json	No	—	Optional Pages project secrets, as a JSON map name->value or a list of {name, value}. Applied to the production environment via the Cloudflare plugin before deploy; secret VALUES never enter state_data, logs, or the runner env (both modes).
`use_secret_environment`	boolean	No	—	Per-run override of the runner group's config.use_secret_environment gate. When true, the build runner's credentials (GitHub token, Cloudflare API token) are staged into Secret Manager and passed to the launcher as references instead of plaintext values; staging failure fails the build (no fallback). Omit to inherit the runner group's setting (default: off).
`staging_connection_uuid`	uuid	No	—	Storage connection (aws/gcp/cloudflare-with-R2/magalu) to stage the built bundle in. When omitted (default), the runner deploys straight to Pages with the Cloudflare connection's Bearer token (DIRECT mode). When set, the bundle is staged there and the deploy child downloads it (STAGED mode); the connection must carry data-plane credentials.
`staging_bucket`	string	No	—	Bucket in the staging connection to stage the build bundle in; default 'orkestia-pages-builds'. Must already exist. STAGED mode only. Alias: bundle_bucket.
`bundle_bucket`	string	No	—	Back-compat alias for staging_bucket; used only in STAGED mode when staging_bucket is not given. Default 'orkestia-pages-builds'.

Output Schema

Field	Type	Required	Default	Description
`organization_uuid`	uuid	Yes	—	Organization UUID.
`pages_project_uuid`	uuid	No	—	Target Pages project row UUID.
`project_name`	string	No	—	Pages project name (with connection_uuid) when pages_project_uuid is not given.
`connection_uuid`	uuid	No	—	Cloudflare connection UUID (with project_name).
`github_repository_uuid`	uuid	No	—	GitHubRepository UUID to build from; used to bootstrap the Pages project (with project_name+connection_uuid) on first run and to backfill an existing project's repo binding.
`source_ref`	string	No	—	Branch/tag to build; default = project's production_branch.
`commit_sha`	string	No	—	Specific commit SHA to build.
`runner_group_uuid`	uuid	No	—	Runner group to build on; default = org's first active generic runner group.
`build_command`	string	No	—	Build command; default 'npm ci && npm run build'.
`output_dir`	string	No	—	Static output dir; default 'dist'.
`functions_dir`	string	No	—	Pages Functions dir to include; default 'functions'.
`node_version`	string	No	—	Node.js version for the build.
`env_vars`	json	No	—	Optional plain (non-secret) Pages project env vars, as a JSON map name->value. Applied to the production environment via the Cloudflare plugin before the deploy binds them (both modes).
`secrets`	json	No	—	Optional Pages project secrets, as a JSON map name->value or a list of {name, value}. Applied to the production environment via the Cloudflare plugin before deploy; secret VALUES never enter state_data, logs, or the runner env (both modes).
`use_secret_environment`	boolean	No	—	Per-run override of the runner group's config.use_secret_environment gate. When true, the build runner's credentials (GitHub token, Cloudflare API token) are staged into Secret Manager and passed to the launcher as references instead of plaintext values; staging failure fails the build (no fallback). Omit to inherit the runner group's setting (default: off).
`staging_connection_uuid`	uuid	No	—	Storage connection (aws/gcp/cloudflare-with-R2/magalu) to stage the built bundle in. When omitted (default), the runner deploys straight to Pages with the Cloudflare connection's Bearer token (DIRECT mode). When set, the bundle is staged there and the deploy child downloads it (STAGED mode); the connection must carry data-plane credentials.
`staging_bucket`	string	No	—	Bucket in the staging connection to stage the build bundle in; default 'orkestia-pages-builds'. Must already exist. STAGED mode only. Alias: bundle_bucket.
`bundle_bucket`	string	No	—	Back-compat alias for staging_bucket; used only in STAGED mode when staging_bucket is not given. Default 'orkestia-pages-builds'.
`staging_mode`	string	No	—	Selected staging mode: 'direct' (runner deploys via wrangler with the Cloudflare Bearer token) or 'staged' (bundle staged in the storage connection, deploy child downloads it).
`runner_execution_uuid`	uuid	No	—	RunnerExecution UUID for the build.
`secret_environment_used`	boolean	No	—	True when the build runner received its credentials as Secret Manager references (secret_environment) instead of plaintext env.
`staged_secret_env_keys`	list	No	—	Runner env var NAMES whose values were staged into Secret Manager for this build. Names only — never values.
`build_succeeded`	boolean	No	—	True once the build stage completed successfully.
`bundle_ref`	string	No	—	URI of the built bundle (dist + functions) for direct upload.
`deploy_workflow_uuid`	string	No	—	Child cloudflare.pages.deploy workflow id.
`deployment_ref`	string	No	—	Created Cloudflare Pages deployment identifier (matches pages/deploy.py's deployment_ref field name).
`production_url`	string	No	—	Production URL after deploy.
`status`	string	No	—	Overall status ('deployed' once complete).
`_children_by_key`	dict	No	—	Child workflow ids keyed by 'build' / 'deploy'.
`prepared_at`	string	No	—	ISO8601 timestamp when prepare_build completed.
`build_launched_at`	string	No	—	ISO8601 timestamp when the build runner execution was launched.
`build_completed_at`	string	No	—	ISO8601 timestamp when the build completed.
`deploy_started_at`	string	No	—	ISO8601 timestamp when the deploy child was started.
`completed_at`	string	No	—	ISO8601 timestamp when the workflow completed.
`auto_advance`	string	No	—	Internal next-action signal emitted by a polling transition.
`failure_reason`	string	No	—	Engine-stamped human-readable failure reason
`failed_at_state`	string	No	—	Engine-stamped state when the workflow failed
`failed_step`	string	No	—	Engine-stamped step name (DAG path)
`failed_layer`	integer	No	—	Engine-stamped layer index (DAG path)
`error`	string	No	—	Engine-stamped exception message
`error_type`	string	No	—	Engine-stamped exception class name
`failure_type`	string	No	—	Engine-stamped failure category (atomic path)
`failed_action`	string	No	—	Engine-stamped action method that raised (atomic path)

States

State	Initial	Terminal	Success	Auto-advance	Description
`pending`	Yes	No	—	`prepare_build`	Build request accepted
`building`	No	No	—	—	Runner execution building the SPA
`built`	No	No	—	`deploy`	Bundle published; ready to deploy
`deploying`	No	No	—	—	cloudflare.pages.deploy child running
`prepared`	No	No	—	`launch_build`	Project + runner group resolved
`completed`	No	Yes	Yes	—	Bundle deployed to Cloudflare Pages
`failed`	No	Yes	No	—	Build or deploy failed

State Diagram

Transitions

From	Action	To	Description
`pending`	`prepare_build`	`prepared`	—
`prepared`	`launch_build`	`building`	—
`building`	`poll_build`	`building`	—
`building`	`build_succeeded`	`built`	—
`built`	`deploy`	`deploying`	—
`deploying`	`poll_deploy`	`deploying`	—
`deploying`	`deploy_succeeded`	`completed`	—
`*` (any state)	`fail`	`failed`	—

API Usage

bash

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "cloudflare.pages.build-and-deploy",
  "initial_data": {
    "organization_uuid": "value"
  }
}

cloudflare.pages.build-and-deploy ​

Overview ​

Input Schema ​

Output Schema ​

States ​

State Diagram ​

Transitions ​

API Usage ​

cloudflare.pages.build-and-deploy

Overview

Input Schema

Output Schema

States

State Diagram

Transitions

API Usage