ビルドのトリガーと中止
| エンドポイント | 機能 | アプリのチームに必要なロール |
|---|---|---|
| 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つのビルドパラメータを指定する必要があります。
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"
}
}'
アプリの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には、次のパラメータの優先順位があります。
- commit_hash
- tag
- branch
複数のパラメータを指定した場合、優先順位が低いパラメータは無視されます。
無視されたパラメータもログには記録されます。Stepsで利用できるほか、ビルドのDetailsページにも表示されますが、Git Clone Stepはチェックアウトに最も具体的なパラメータを使用します。
プルリクエストビルドのパラメータの設定Click to copy link
プルリクエストビルドの場合、branch_destパラメータを使用して、プルリクエストの送信先ブランチまたはターゲットブランチを設定します。PRはこのブランチにマージされますが、その前にBitriseが、マージ後のコードがどのようになるかに基づいてアプリをビルドします。これは、たとえばwebhookによってPRビルドが自動的にトリガーされる場合に発生します。
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}'