Builds API リファレンス

このガイドでは、Workers Builds REST API を使って、ビルドの起動、トリガーの管理、ビルド状態の監視をプログラムから行う方法を説明します。例はターミナルで直接実行できる curl コマンドです。好みのプログラミング言語に合わせて書き換えても構いません。一部の例では JSON レスポンスを絞り込むために jq ↗ へパイプしています。未インストールの場合は先に入れてください。

始める前に

1. 正しい権限の API トークンを作成する

Builds API を使うには、リクエストを認証する API トークンが必要です。Builds API では ユーザースコープ の API トークンが必要です。アカウントスコープのトークンはサポートされず、「Invalid token」エラーになります。

dash.cloudflare.com/profile/api-tokens ↗ で、次の権限を持つトークンを作成します。

権限	アクセスレベル	必要な理由
Workers Builds Configuration	Edit	ビルドの起動、トリガーの管理、環境変数の設定
Workers Scripts	Read	Worker のタグ（ドキュメント上は `external_script_id`）を取得する 1 つのエンドポイントでのみ必要です

2. Worker のタグ（ドキュメント上は external_script_id）

Builds API は、Cloudflare が割り当てる不変の UUID であるタグで Worker を識別します。API のレスポンスとパラメーターでは、この値は external_script_id として現れます。

識別子	例	取得元
Worker 名 (`id`)	`my-worker`	Worker に付けた名前
Worker のタグ (`external_script_id`)	`1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d`	Cloudflare が割り当てる不変の UUID

Worker を参照する Builds API のエンドポイントはすべて、名前ではなくタグが必要です。

3. トリガーとは

トリガー は、Worker のビルドとデプロイ方法を定義する設定です。ビルドコマンド、デプロイコマンド、環境変数、どのブランチでビルドを起動するかを指定します。各 Worker のトリガーは最大 2 つ です。1 つは本番用（本番ブランチで実行）、もう 1 つはプレビュー用（それ以外のすべてのブランチで実行）です。トリガーのセットアップは Workers Builds をゼロから設定するを参照してください。

トリガーのフィールド:

フィールド	型	説明
`trigger_name`	string	トリガーの表示名
`build_token_uuid`	string	Worker のデプロイに使うビルドトークンの UUID。Worker の Settings > Builds > API token で確認するか、`GET /builds/tokens` エンドポイントで取得します。
`build_command`	string	プロジェクトをビルドするコマンド（例: `npm run build`）
`deploy_command`	string	Worker をデプロイするコマンド（例: `npx wrangler deploy`）
`root_directory`	string	プロジェクトルートへのパス
`branch_includes`	array	ビルドを起動するブランチパターン（例: `["main"]` または `["*"]`）
`branch_excludes`	array	除外するブランチパターン
`path_includes`	array	ビルドを起動するファイルパスのパターン
`path_excludes`	array	無視するファイルパスのパターン
`build_caching_enabled`	boolean	ビルドキャッシュの有効 / 無効
`environment_variables`	object	このトリガー固有のビルド時変数

ワークフローの概要

Builds API の操作の多くは、次の流れです。まず Worker のタグを取得し、次にトリガー UUID を取得し、その後ビルド操作を実行します。

手順	操作	エンドポイント
1	Worker のタグを取得	`GET /workers/scripts`
2	トリガー UUID を取得	`GET /builds/workers/:worker_tag/triggers`
3a	ビルドを起動する	`POST /builds/triggers/:trigger_uuid/builds`
3b	ビルドを一覧する	`GET /builds/workers/:worker_tag/builds`
3c	ビルドログを取得する	`GET /builds/builds/:build_uuid/logs`
3d	ビルドをキャンセルする	`PUT /builds/builds/:build_uuid/cancel`

Step 1: Worker のタグを取得する

Workers Scripts API を呼び出して Worker を一覧し、対象 Worker の tag を探します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {name: .id, tag: .tag}'

出力例:

{
  "name": "my-worker",
  "tag": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
}
{
  "name": "another-worker",
  "tag": "8a1b2c3d4e5f67890abcdef123456789"
}

対象 Worker の tag を保存します。以降の API 呼び出しで使います。

Step 2: トリガー UUID を取得する

GET /builds/workers/{tag}/triggers エンドポイントで、Worker のトリガーを一覧します。

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}'

出力例:

{
  "trigger_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "trigger_name": "Deploy production",
  "branch_includes": ["main"],
  "branch_excludes": []
}
{
  "trigger_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trigger_name": "Deploy non-production branches",
  "branch_includes": ["*"],
  "branch_excludes": ["main"]
}

操作対象の trigger_uuid を保存します。トリガーは最大 2 つです。1 つは本番ブランチ（例: main）向けで、稼働中の Worker にデプロイします。もう 1 つは任意で、それ以外のブランチ向けにプレビューデプロイを作成します。

Step 3: ビルドを操作する

Worker のタグとトリガー UUID が揃ったら、ビルドの起動、履歴の一覧、ログの取得ができます。

手動でビルドを起動する

Step 2 の trigger_uuid を使い、POST /builds/triggers/{uuid}/builds エンドポイントを呼び出します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"branch": "main"}'

branch、commit_hash、またはその両方を指定する必要があります。

フィールド	説明
`branch`	ビルドする Git ブランチ名（例: `main`）
`commit_hash`	ビルドする特定のコミット SHA。`branch` なしで指定した場合は、そのコミットが属する現在のブランチでビルドします。

レスポンスに含まれる build_uuid で、ビルドを監視できます。

Worker のビルドを一覧する

Step 1 の worker_tag を使い、GET /builds/workers/{tag}/builds エンドポイントを呼び出します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {build_uuid, status, branch, created_at}'

レスポンスには各ビルドの build_uuid が含まれます。ログ取得やキャンセルに使います。

ビルドログを取得する

GET /builds/builds/{uuid}/logs エンドポイントを使います。build_uuid は次から取得できます。

ビルドの一覧
ビルド起動時のレスポンス
Get latest builds by script IDs
ダッシュボードのビルド詳細ページ URL の末尾セグメント

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/logs" \
  --header "Authorization: Bearer <API_TOKEN>"

実行中のビルドをキャンセルする

PUT /builds/builds/{uuid}/cancel エンドポイントを使います。build_uuid は次から取得できます。

ビルドの一覧
ビルド起動時のレスポンス
Get latest builds by script IDs
ダッシュボードのビルド詳細ページ URL の末尾セグメント

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/cancel" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --request PUT

トリガー設定を更新する

Step 2 の trigger_uuid を使い、PATCH /builds/triggers/{uuid} エンドポイントを呼び出します。トリガーとはで説明した任意のフィールドを更新できます。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "build_command": "npm run build:prod",
    "deploy_command": "npx wrangler deploy"
  }'

ビルド環境変数を管理する

環境変数はトリガーごとに設定します。本番ビルドとプレビュービルドで値を変えられます。たとえば、本番トリガーに NODE_ENV=production、プレビュートリガーに NODE_ENV=development を設定できます。エンドポイントの詳細は環境変数 API リファレンスを参照してください。

環境変数を一覧する

Step 2 の trigger_uuid を使います。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>"

環境変数を設定する

トリガーごとに異なる変数を設定できます。本番の環境変数を設定する例です。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{production_trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "NODE_ENV": {"value": "production", "is_secret": false},
    "API_KEY": {"value": "prod-secret-key", "is_secret": true}
  }'

プレビュービルドには別の値を設定します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{preview_trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "NODE_ENV": {"value": "development", "is_secret": false},
    "API_KEY": {"value": "dev-secret-key", "is_secret": true}
  }'

平文の値は is_secret を false に、ログでマスクすべき機密値は true にします。

環境変数を削除する

Step 2 の trigger_uuid を使います。variable_key は設定したキー名です（例: NODE_ENV）。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/environment_variables/{variable_key}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --request DELETE

ビルドキャッシュをパージする

Step 2 の trigger_uuid を使い、POST /builds/triggers/{uuid}/purge_build_cache エンドポイントを呼び出します。そのトリガーのキャッシュ済み依存関係とビルド成果物をクリアします。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/purge_build_cache" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --request POST

例

次の例は、Builds API のよくある使い方です。

Workers Builds をゼロから設定する

この例では、API だけを使って GitHub リポジトリを Worker に接続し、自動ビルドを設定する一連の手順を説明します。

セットアップの流れ: GitHub の ID を取得し、リポジトリ接続を作成し、Worker のタグを取得し、トリガーを作成し、環境変数を設定し、最初のビルドを起動します。

手順	操作	エンドポイント
1	GitHub のアカウント / リポジトリ ID を取得	`GET api.github.com/users/...` と `GET api.github.com/repos/...`
2	リポジトリ接続を作成する	`PUT /builds/repos/connections`
3	Worker のタグを取得	`GET /workers/scripts`
4	ビルドトークン UUID を取得	`GET /builds/tokens`
5a	本番トリガーを作成する	`POST /builds/triggers`
5b	プレビュートリガーを作成する	`POST /builds/triggers`
6	環境変数を設定する	`PATCH /builds/triggers/:trigger_uuid/environment_variables`
7	最初のビルドを起動する	`POST /builds/triggers/:trigger_uuid/builds`

前提条件

API を使う前に、ダッシュボードから Cloudflare GitHub App をインストールする必要があります。

Cloudflare ダッシュボード ↗ で Workers & Pages を開きます。
任意の Worker を選び、Settings > Builds > Connect に移動します。
GitHub を選び、自分のアカウントまたは組織に対して Cloudflare GitHub App を承認します。

この一度きりのセットアップで、GitHub アカウントと Cloudflare が接続されます。完了後は、残りを API で進められます。

Step 1: GitHub アカウント情報を取得する

GitHub App をインストールしたら、GitHub のアカウント ID とリポジトリ ID が必要です。既存のトリガー、または GitHub API から取得できます。

GitHub の API から取得する例:

# Get your GitHub user/org ID
curl -s "https://api.github.com/users/<GITHUB_USERNAME>" | jq '.id'

# Get a repository ID
curl -s "https://api.github.com/repos/<GITHUB_USERNAME>/<REPO_NAME>" | jq '.id'

Step 2: リポジトリ接続を作成する

GitHub リポジトリと Cloudflare の接続を作成します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/repos/connections" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PUT \
  --data '{
    "provider_type": "github",
    "provider_account_id": "<GITHUB_USER_ID>",
    "provider_account_name": "<GITHUB_USERNAME>",
    "repo_id": "<GITHUB_REPO_ID>",
    "repo_name": "<REPO_NAME>"
  }'

レスポンスの repo_connection_uuid を保存します。

Step 3: Worker のタグを取得する

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {name: .id, tag: .tag}'

Step 4: ビルドトークン UUID を取得する

ビルドトークンは、ビルドシステムが Worker をデプロイすることを許可します。ビルドトークン UUID の取得方法は次のとおりです。

Cloudflare ダッシュボード ↗ で対象の Worker を開きます。
Settings > Builds > API token に移動します。
既存のビルドトークンを選ぶか、新しく作成します。

API でビルドトークンを一覧することもできます。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/tokens" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {build_token_uuid, build_token_name}'

次の手順用に build_token_uuid を保存します。

Step 5: 本番トリガーを作成する

main へのプッシュでデプロイするトリガーを作成します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "external_script_id": "<WORKER_TAG>",
    "repo_connection_uuid": "<REPO_CONNECTION_UUID>",
    "build_token_uuid": "<BUILD_TOKEN_UUID>",
    "trigger_name": "Deploy production",
    "build_command": "npm run build",
    "deploy_command": "npx wrangler deploy",
    "root_directory": "/",
    "branch_includes": ["main"],
    "branch_excludes": [],
    "path_includes": ["*"],
    "path_excludes": []
  }'

Step 6: プレビュートリガーを作成する（任意）

それ以外のブランチ向けに、プレビューデプロイ用の 2 つ目のトリガーを作成します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "external_script_id": "<WORKER_TAG>",
    "repo_connection_uuid": "<REPO_CONNECTION_UUID>",
    "build_token_uuid": "<BUILD_TOKEN_UUID>",
    "trigger_name": "Deploy preview branches",
    "build_command": "npm run build",
    "deploy_command": "npx wrangler versions upload",
    "root_directory": "/",
    "branch_includes": ["*"],
    "branch_excludes": ["main"],
    "path_includes": ["*"],
    "path_excludes": []
  }'

deploy_command が異なります。本番は wrangler deploy、プレビューは wrangler versions upload を使い、稼働中のデプロイに影響せずプレビュー URL を作成します。

Step 7: 各トリガーに環境変数を設定する

本番の環境変数を設定します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{production_trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "NODE_ENV": {"value": "production", "is_secret": false}
  }'

プレビューの環境変数を設定します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{preview_trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "NODE_ENV": {"value": "development", "is_secret": false}
  }'

Step 8: 最初のビルドを起動する

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{production_trigger_uuid}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"branch": "main"}'

これで Worker が GitHub に接続されます。以降、main へのプッシュは本番デプロイを自動起動し、ほかのブランチへのプッシュはプレビューデプロイを作成します。

現在のデプロイを再デプロイする

ビルド時データを更新するため、現在有効なデプロイを再デプロイします。コード変更なしで再ビルドしたいときに便利です。

再デプロイの流れ: 有効なデプロイを取得し、そのバージョンのビルドを探し、同じブランチとコミットで再起動します。

手順	操作	エンドポイント
1	有効なデプロイを取得する	`GET /workers/scripts/:worker_name/deployments`
2	そのバージョンのビルドを探す	`GET /builds/builds?version_ids=:version_id`
3	同じブランチ / コミットで再起動する	`POST /builds/triggers/:trigger_uuid/builds`

Step 1: 有効なデプロイのバージョン ID を取得する

Step 1 の worker_name を使い、GET /workers/scripts/{script_name}/deployments エンドポイントを呼び出します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{worker_name}/deployments" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result.deployments[0].versions[0].version_id'

出力の version_id を保存します。

Step 2: そのバージョンのビルドを探す

前の手順の version_id を使い、GET /builds/builds エンドポイントを呼び出します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds?version_ids={version_id}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result.builds'

レスポンスから trigger.trigger_uuid、build_trigger_metadata.branch、build_trigger_metadata.commit_hash を控えます。

Step 3: 同じブランチとコミットで再起動する

前の手順の値を使い、POST /builds/triggers/{uuid}/builds エンドポイントを呼び出します。

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "branch": "{branch}",
    "commit_hash": "{commit_hash}"
  }'

branch と commit_hash の両方を渡すと、そのブランチ上のそのコミットにビルドを固定します。

トラブルシューティング

「Resource not found」エラー

Worker 名を使っている可能性が高いです。Builds API では Worker 名ではなく tag（1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d のような UUID）が必要です。Worker のタグの取得は Step 1 を参照してください。

そのほかのビルドエラーはビルドのトラブルシューティングを参照してください。