メインコンテンツまでスキップ

ビルドのトリガーと中止

エンドポイント機能アプリのチームに必要なロール
POST /apps/{app-slug}/builds新しいビルドをトリガーします。Owner、Admin、またはDeveloper
POST /apps/{app-slug}/builds/{build-slug}/abort特定のビルドを中止します。Owner、Admin、またはDeveloper

Bitrise APIを使用してビルドをトリガーおよび中止できます。ビルドのパラメータ(使用するブランチ、タグ、gitコミットなど)を定義します。カスタムEnvironment Variablesも定義できます。

APIで新しいビルドをトリガーするClick to copy link​

Bitrise APIで新しいビルドをトリガーするには、POST /apps/{APP-SLUG}/buildsエンドポイントを呼び出します。アプリのスラッグと、JSONオブジェクト内の少なくとも1つのビルドパラメータを指定する必要があります。

  • gitタグまたはgitコミットハッシュ
  • ブランチ
  • WorkflowIDまたはPipelineID
必要なロール

APIを使用して新しいビルドをトリガーするには、アプリのチームでdeveloper、admin、またはownerのロールを持っている必要があります。

ユーザーロールの完全なリストとロールのチートシートについては、Bitrise CIのロールと権限を確認してください。

JSONオブジェクトには、typeキーと、そのキーの値としてbitriseを持つhook_infoオブジェクトも含める必要があります。

次に、branchパラメータの値としてmainを指定する最小限のサンプルJSON本文を示します。

{
"hook_info": {
"type": "bitrise"
},
"build_params": {
"branch": "main"
}
}

こちらは、mainブランチでprod Workflowを使用してビルドをトリガーするためのcurlリクエストの構文です。

curl -X 'POST' \
'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
-H 'accept: application/json' \
-H 'Authorization: ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"build_params": {
"branch": "main",
"workflow_id":"prod"
},
"hook_info": {
"type": "bitrise"
}
}'
インタラクティブなcURL呼び出しコンフィギュレーター

アプリのbitrise.ioページでStart/Schedule a buildボタンをクリックし、ポップアップでAdvancedモードに切り替えると、インタラクティブなcURL呼び出しコンフィギュレーターを利用できます。ポップアップの下部には、ポップアップで指定したパラメータに基づくcurl呼び出しが表示されます。

前の例では、このJSONペイロードを文字列として渡しました。正確には、文字列にシリアライズされたJSONオブジェクトとして渡しています。

オブジェクトとして渡すこともできます(たとえば、JavaScriptから呼び出したい場合)。その場合は、ルートのpayload要素を含めるか、またはJSONオブジェクトをpayload POSTパラメータの値として設定します。

こちらは、payloadパラメータを使用したjQueryの例です。

$.post("https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/", {
"payload":{
"hook_info":{
"type":"bitrise"
},
"build_params":{
"branch":"main",
"workflow_id":"prod"
}
}
})

ビルドをトリガーする際には、さまざまなビルドパラメータを指定できます。パラメータはbuild_paramsオブジェクトに設定します。

ビルドするブランチ、コミット、タグの設定Click to copy link​

呼び出しにGit固有のパラメータを設定できます。branchパラメータは、ビルド対象のsource branchを指定します。これは、gitコミットのブランチ、またはプルリクエストビルドの場合はプルリクエストのsource branchのいずれかです。

curl -X 'POST' \
'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
-H 'accept: application/json' \
-H 'Authorization: ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"hook_info": {
"type": "bitrise"
},
"build_params": {
"branch": "main",
"workflow_id":"prod"
}
}'

特定のgitコミットやgitタグをビルドすることもできます。その場合は、build_paramsオブジェクトにコミットハッシュまたはタグを設定するだけです。また、commit_messageパラメータを使用して、ビルドのコミットメッセージを設定することもできます。

curl -X 'POST' \
'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
-H 'accept: application/json' \
-H 'Authorization: ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"hook_info":{
"type":"bitrise"
},
"build_params": {
"commit_hash": "0000ffffeeeee",
"commit_message": "testing",
"workflow_id":"prod"
}
}'
パラメータの優先順位

Git Clone Stepには、次のパラメータの優先順位があります。

  1. commit_hash
  2. tag
  3. branch

複数のパラメータを指定した場合、優先順位が低いパラメータは無視されます。

無視されたパラメータもログには記録されます。Stepsで利用できるほか、ビルドのDetailsページにも表示されますが、Git Clone Stepはチェックアウトに最も具体的なパラメータを使用します。

プルリクエストビルドのパラメータの設定Click to copy link​

プルリクエストビルドの場合、branch_destパラメータを使用して、プルリクエストの送信先ブランチまたはターゲットブランチを設定します。PRはこのブランチにマージされますが、その前にBitriseが、マージ後のコードがどのようになるかに基づいてアプリをビルドします。これは、たとえばwebhookによってPRビルドが自動的にトリガーされる場合に発生します。

GitHub スタックされたプルリクエスト

webhookがGitHubスタック内のプルリクエストに対してビルドをトリガーすると、Bitriseはbranch_destをそのスタックのベースブランチに設定します。

branch_repo_ownerパラメータとbranch_dest_repo_ownerパラメータは、リポジトリの所有者を識別し、プルリクエストに関わるブランチを一意に特定するために使用します。

フォークからのプルリクエストビルド

branch_repo_ownerパラメータとbranch_dest_repo_ownerパラメータを指定しない場合、APIはプルリクエストビルドがフォークから送信されたものと見なします。そのため、手動承認が完了するまでビルドが保留になることがあります。詳細はプルリクエストビルドの承認を参照してください。

PR自体を識別するには、pull_request_idパラメータを使用します。これは整数を受け取ります。たとえば、GitHub上のPRの番号です。

curl -X 'POST' \
'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
-H 'accept: application/json' \
-H 'Authorization: ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"hook_info":{
"type":"bitrise"
},
"build_params": {
"branch": "the-pr-branch",
"branch_dest": "main",
"commit_hash": "fffff000000eeeeee",
"pull_request_id": 1,
"workflow_id":"prod"
}
}'

ご使用のgitプロバイダーが対応している場合は、pull_request_merge_branchパラメータを使用して、PRのブランチのマージ前の状態をビルドすることもできます。もう1つの方法としてpull_request_head_branchパラメータがあります。これは、PRのソースを指す特別なgit refです。

リポジトリのフォークから開かれたPRからビルドをトリガーしたい場合は、pull_request_repository_urlパラメータを使用します。値には、フォークのURLを指定します。

GitステータスレポートのスキップClick to copy link​

webhookを設定している場合、Bitriseはビルドに関するステータスレポートをgitプロバイダーに送信します。ただし、この動作はAPI経由で無効にできます。その場合はskip_git_status_reportパラメータを使用します。trueに設定すると、ビルドステータスレポートは送信されません。

curl -X 'POST' \
'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
-H 'accept: application/json' \
-H 'Authorization: ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"hook_info":{
"type":"bitrise"
},
"build_params": {
"branch": "the-pr-branch",
"branch_dest": "main",
"skip_git_status_report": true,
"workflow_id":"prod"
}
}'

Environment Variablesの指定Click to copy link​

ビルドに追加のEnvironment Variables(環境変数)を定義できます。これらの追加の変数はSecretsとApp Env Varsの間の優先順位で処理されるため、ビルド設定で定義された環境変数(App Env Varsなど)を上書きすることはできず、Secretsのみを上書きできます。

追加の環境変数はenvironmentsパラメータで定義します。このパラメータはオブジェクトの配列である必要があり、配列の各項目には少なくともkeyプロパティを含める必要があります。これには次を含める必要があります。

  • 環境変数のキー。
  • 環境変数の値。
環境変数名の置換

デフォルトでは、値の中にある環境変数名は、トリガーされたビルドにおいてターゲット環境の実際の値に置き換えられます。この動作は、is_expandフラグをfalseに設定することで無効にできます。

"environments":[
{"key":"API_TEST_ENV","value":"This is the test value","is_expand":true},
{"key":"HELP_ENV","value":"$HOME variable contains user's home directory path","is_expand":false},
]

ビルドのWorkflowの設定Click to copy link​

デフォルトでは、トリガーされたビルドのWorkflowは、build_paramsの内容とアプリのトリガーマップに基づいて選択されます。これは、webhookがトリガーマップに基づいてビルドのWorkflowを自動的に選択する方法と同じです。

APIを使用すると、この選択を上書きして、使用するWorkflowを正確に指定できます。

build_paramsにworkflow_idパラメータを追加し、その特定のビルドで使用したいワークフローを指定します。次に、deployワークフローを指定する呼び出しの例を示します。

curl -X 'POST' \
'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
-H 'accept: application/json' \
-H 'Authorization: ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"hook_info": {
"type": "bitrise"
},
"build_params": {
"branch": "main",
"workflow_id": "deploy"
}
}'

ビルドの中止Click to copy link​

実行中のビルドを中止し、中止の理由を設定できるほか、そのビルドに関するメール通知を送信するかどうかも指定できます。

必要なロール

APIを使用してビルドを中止するには、アプリのチームでowner、admin、またはdeveloperのロールを持っている必要があります。

ユーザーロールの完全なリストとロールのチートシートについては、Bitrise CIのロールと権限を確認してください。

ビルドを単純に中止するには、/apps/APP-SLUG/builds/BUILD-SLUG/abortエンドポイントを呼び出します。これには3つのパラメータが必要です。

  • アプリのスラッグ。
  • ビルドのスラッグ。
  • ビルド中止パラメータの本文。中止に特定のパラメータを設定したくない場合は空のままにできます。-d "{}"。
curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/BUILD-SLUG/abort" -d "{}"

abort_reasonパラメータを使用して、ビルドを中止する理由を設定できます。このパラメータは文字列を受け取り、アプリのビルドページに表示されます。

curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/BUILD-SLUG/abort" -d '{"abort_reason": "aborted for a reason"}'

通常、中止されたビルドは失敗したビルドとしてカウントされます。abort_with_successパラメータを使用すると、ビルドを中止しつつ成功したビルドとしてカウントできます。gitプロバイダーに送信されるステータスレポートではビルドは成功として表示されますが、bitrise.ioではCancelledとして表示されます。

curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/BUILD-SLUG/abort" -d '{"abort_with_success": true}'

app settingsによっては、ビルドが中止されるとチームメンバーにBitriseがメール通知を送信することがあります。通知を希望しない場合は、skip_notificationsパラメータをtrueに設定してください。

curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/BUILD-SLUG/abort" -d '{"skip_notifications": true}'