Bitrise APIで、アプリのビルド開始と中断を実行することができます。ビルドするためのパラメータを定義できます: 例えば、ブランチ、タグ、またはgitコミット。カスタム環境変数も同様に設定することができます。
新しいビルドのトリガー(開始) ⚓
エンドポイント | 機能 |
---|---|
POST /apps/{app-slug}/builds | 新しいビルドのトリガー(開始)。 |
Bitrise APIで新しいビルドを開始するために /apps/{APP-SLUG}/builds
エンドポイントをコールします。特定のアプリスラッグを指定することと、少なくとも1つのビルドパラメータをJSONオブジェクトに設定する必要があります:
- gitのタグまたはgitコミットハッシュ
- ブランチ名
- ワークフローID
そのJSONオブジェクトは bitrise
という値を設定した type
キーを持つ hook_info
オブジェクトを必ず持つ必要があります。
これが branch
パラメータに master という値を設定した、最小構成のJSONボディです。
{
"hook_info": {
"type": "bitrise",
},
"build_params": {
"branch": "master"
}
}
こちらがcurlリクエストの例です:
curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d '{"hook_info":{"type":"bitrise"},"build_params":{"branch":"master"}}'
上記の例では、アプリの master
ブランチのビルドを開始します。
この例ではJSONペイロードを文字列、正確には、文字列にシリアライズされたJSONオブジェクトとして渡しています。
それをオブジェクトとして渡すこともできます(例えば、JavaScriptからコールしたい場合)。それを実行するためには、ルートに payload
要素を持つか、代わりに そのJSONオブジェクトを payload
POSTパラメータの値として設定してください。
こちらが payload
パラメータを使ったjQueryの実装例です:
$.post("https://api.bitrise.io/app/APP-SLUG/builds/", {
"payload":{
"hook_info":{
"type":"bitrise",
},
"build_params":{
"branch":"master"
}
}
})
ビルド開始ときに、いろいろな異なるビルドパラメータを設定することができます。そのパラメータは build_params
オブジェクトに設定される必要があります: いくつかの使用可能な例を見てみましょう!
ビルドのためのブランチ、コミット、タグの設定 ⚓
Git固有のパラメータをAPIコールに設定できます。 branch
パラメータはビルドするソースブランチを指定します。これはGitコミットのブランチ、またはPRビルドの場合はそのPRのソースブランチのいずれかです。
curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d '{"hook_info":{"type":"bitrise"},"build_params":{"branch":"master"}}'
特定のgitのコミットまたはgitのtagもビルドできます。build_params
オブジェクトにコミットハッシュまたはtagを設定するだけです。 commit_message
パラメータを使うことで、コミットメッセージをその特定のビルドに設定することもできます。
curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d '{"hook_info":{"type":"bitrise"},"build_params":{"commit_hash":"0000ffffeeeee", "commit_message":"testing"}}'
PRビルドのためのパラメータ設定 ⚓
PRビルドのために、そのマージ先、またはターゲットブランチを設定するために branch_dest
パラメータを使います。そのPRは将来的にはこのブランチにマージされますが、その前に、BitriseはこのPRが未来にどのようにマージされるかの結果をベースにあなたのアプリをビルドします。例えば、これはwebhookにより自動的にPRビルドが開始されたときに何が起こるかということです。
branch_repo_owner
と branch_dest_repo_owner
パラメータは、そのリポジトリのオーナーを特定するため、またそのPRに関連するブランチを明確に特定するために使われます。
PR自体を特定するため、 pull_request_id
パラメータを使用してください。そのパラメータは整数型です。(例: GitHub上のPR番号)
curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d '{"hook_info":{"type":"bitrise"},"build_params":{"branch": "the-pr-branch", "branch_dest":"master", "pull_request_id": 133, "commit_hash": "fffff000000eeeeee"}}'
もしgitプロバイダ側でサポートされているならば、 pull_request_merge_branch
パラメータを使ってそのPRのマージ前の状態のブランチをビルドすることも可能です。その代替としては pull_request_head_branch
パラメータです。そのパラメータはPRのソースブランチを指す特定のgitリファレンスです。
もしあなたのリポジトリのフォークから開かれたPRのビルドをトリガー(開始)したい場合、pull_request_repository_url
パラメータを使用してください。その値はフォークのURLである必要があります。
gitステータスレポートのスキップ ⚓
もしwebhookの設定をしている場合、Bitriseはあなたのgitプロバイダにビルドのステータスレポートを送ります。しかし skip_git_status_report
パラメータを使ってAPI経由で無効とすることができます。もしその値が true
と設定された場合は、ビルドステータスレポートは送信されません。
curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d '{"hook_info":{"type":"bitrise"},"build_params":{"branch": "the-pr-branch", "branch_dest":"master", "pull_request_id": 133, "skip_git_status_report": "true"}}'
環境変数の設定 ⚓
あなたのビルドに対し、環境変数を追加で設定できます。
環境変数には優先順位があることに注意してください! 追加された変数は Secrets
と App Env Vars
の間の優先度に従って管理されます。つまり、あなたのビルド設定(例えばApp Env Vers)で定義された環境変数は上書きすることはできません。Secretsのみ上書きできます。
そのパラメータはオブジェクトの配列である必要があります。そしてその全ての配列の要素は少なくとも mapped_to
プロパティを持つ必要があります。その要素は以下を保持します:
- その環境変数のキー
- その環境変数の値
例:
"environments":[
{"mapped_to":"API_TEST_ENV","value":"This is the test value","is_expand":true},
{"mapped_to":"HELP_ENV","value":"$HOME variable contains user's home directory path","is_expand":false},
]
ビルドのワークフローを設定 ⚓
デフォルトでは、あなたのビルドのためのワークフローは build_params
の内容と、そのアプリの実行マップをベースにして選択されます。これは Webhooks が開始マップをベースにして、どのようにワークフローをそのビルドのために自動で選択するかと同様です。
APIを使うことで、 この選択を上書きでき、そしてどのワークフローを使いたいかを決定できます。
build_params
に workflow_id
パラメータを追加し、特定のビルドに使いたいワークフローを選択します。こちらは deploy
ワークフローを特定するAPIコールの例です。
curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d '{"hook_info":{"type":"bitrise"},"build_params":{"branch":"master","workflow_id":"deploy"}}'
ビルドの中断 ⚓
エンドポイント | 機能 |
---|---|
POST /apps/{app-slug}/builds/{build-slug}/abort | 特定のビルドを中断する。 |
実行中のビルドを中断することができ、合わせて中断の理由と同様にそのビルドについてのメール通知を設定することができます。
単純にビルドを中断するために /apps/APP-SLUG/builds/BUILD-SLUG/abort
エンドポイントをコールします。必須パラメータは、アプリスラッグとビルドスラッグのみです。
curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/BUILD-SLUG/abort"
中断理由の設定 ⚓
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}'
メール通知のキャンセル ⚓
あなたのアプリ設定に従って、ビルドが中断したときにBitriseはメール通知を送信するかもしれません。もし通知が必要ない場合は skip_notification
パラメータに true
を設定してください。
curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/BUILD-SLUG/abort" -d '{"skip_notification": true}'