背景:
プロジェクトの “Only build pull requests (プルリクエストのみをビルドする)” 設定をオンにすると、デフォルト以外のブランチについて、CircleCI での検証の実行タイミングがプルリクエストの存在時のみに限定されます。
しかし、CircleCI と GitHub の マージキュー機能 5などを併用する場合、この設定は制約が強すぎるとのご意見をいただきました。経緯の詳細については、Canny の投稿 (英語) 7 をご覧ください。
そこで、2023 年 4 月 18 日より、CircleCI API でこの “Only build pull requests” 設定を上書きできるようになりました。 これにより、正規表現で指定したブランチについては全コミットで検証をトリガーし、一方で他のデフォルト以外のブランチについては “Only build pull requests” 設定を有効にしておくことができます。
入力:
- 正規表現と完全なブランチ名を記載したコンマ区切りリスト
-
リストに一致するブランチでは、コミットのたびにビルドが行われます。他のブランチでは、プルリクエストの存在時にのみビルドが行われます。
-
デフォルトブランチ (
main
ブランチ) への全コミットをビルドする通常の挙動を維持するため、このリストにはデフォルトブランチを含めてください。
-
注:
-
CircleCI API に入力する
vcs-type
、org-slug
、project-slug
の各値は、CircleCI Web アプリでプロジェクトを表示した際の URL から確認できます。 -
このオーバーライド機能は、プロジェクト設定の変更権限を持つユーザー全員が利用できます。
-
API を呼び出してオーバーライド機能を利用するには、API トークンが必要です。CircleCI API を初めて利用する方は、API トークンの追加方法 (英語) 3をご覧ください。
-
正規表現でリテラル文字列を使用する場合は、エスケープ処理が必要です。たとえば、
main-(2123)
という名前のブランチとマッチさせるには、main-\\(2123\\)
のようにバックスラッシュを使用して丸括弧をダブルエスケープしてください。 -
正規表現の文字クラスはダブルエスケープする必要があります。たとえば、
main-\\d+
は、main-3
やmain-32
などのブランチ名にマッチします。ギリシャ文字の UTF-8 ブロックが含まれるブランチ名とマッチさせるには、\\p{IsGreek}
のように指定します。 -
API 呼び出しで設定を変更する場合、既存の設定ではなく現在の設定が置き換えられます。
サンプル #1:
“Only build pull requests (プルリクエストのみをビルドする)” 設定がオンであるとします。次のブランチおよびブランチ名パターンについて、“Only build pull requests” 設定をオーバーライドします: main
、release.*
、enterprise-.*
curl -X PUT --header "Circle-Token: <token>"
--header "Accept: application/json"
--header "Content-Type: application/json"
--data '{"feature_flags":{"pr-only-branch-overrides": "main, release.*, enterprise-.*"}}'
'https://circleci.com/api/v1.1/project/vcs-type/org-slug/project-slug/settings'
注: 「token」 は、お使いの CircleCI API トークンと置き換えてください。
結果: 次のような応答が返されます。
""%
名前が「release」から始まるすべてのブランチ (release2
や release-to-prod
)、および enterprise-
から始まるすべてのブランチ (enterprise-2.0
など) で、コミットのたびに検証が実行されるようになります。また、デフォルト (main
) ブランチでは、通常どおり全コミットでビルドが行われます。
プロジェクト内の他のブランチは、プルリクエストがある場合のみビルドされます。
サンプル #2:
CircleCI API で "Only build pull requests (プルリクエストのみをビルドする) 設定をオンにして、次のブランチおよびブランチ名パターンについてこの設定をオーバーライドします: main
、release.*
、enterprise-.*
curl -X PUT --header "Circle-Token: <token>"
--header "Accept: application/json"
--header "Content-Type: application/json"
--data '{"feature_flags":{"build-prs-only":true, "pr-only-branch-overrides": "main, release.*, enterprise-.*"}}'
'https://circleci.com/api/v1.1/project/vcs-type/org-slug/project-slug/settings'
結果: 名前が release
から始まるすべてのブランチ (release2
や release-to-prod
)、および enterprise-
から始まるすべてのブランチ (enterprise-2.0
など) で、コミットのたびに検証が実行されるようになります。また、デフォルト (main
) ブランチでは、通常どおり全コミットでビルドが行われます。
プロジェクト内の他のブランチは、プルリクエストがある場合のみビルドされます。
サンプル #3:
CircleCI API で "Only build pull requests (プルリクエストのみをビルドする) 設定をオンにして、次のブランチおよびブランチ名パターンについてこの設定をオーバーライドします:main
、\\(\\d+\\)-release.*
注: 「token」 は、お使いの CircleCI API トークンと置き換えてください。
curl -X PUT --header "Circle-Token: <token>"
--header "Accept: application/json"
--header "Content-Type: application/json"
--data '{"feature_flags":{"build-prs-only":true, "pr-only-branch-overrides": "main, \(\\d+\)-release.*"}}'
'https://circleci.com/api/v1.1/project/vcs-type/org-slug/project-slug/settings'
結果: 名前の先頭が丸括弧に囲まれた 1 桁以上の数字であり、次に -release
が続き、その後に任意の文字が 0 回以上続くすべてのブランチについて、コミットのたびにビルドが行われます。以下に例を示します。
(123)-release2
、(7)-release-to-prod
、(334)-release
などのブランチで、コミットのたびに検証が実行されます。また、デフォルト (main
) ブランチでは、通常どおり全コミットでビルドが行われます。
制限事項:
-
pr-only-branch-overrides
は、“Only build pull requests (プルリクエストのみをビルドする)” 設定がオンの場合のみ有効です。- この設定は、API の応答でブール値
build-prs-only?
がtrue
であればオンになっています。また、CircleCI Web アプリの [Project Settings (プロジェクト設定)] で [Advanced (詳細設定)] セクションでも設定状態を確認できます。
- この設定は、API の応答でブール値
-
指定できる正規表現の数はプロジェクトごとに 100 個までであり、正規表現ごとの文字数上限は 1,000 文字です。
-
ブランチ名にコンマ (,) を含めることはできません。コンマを含めてもエラーにはなりませんが、コンマの前後で 2 つのブランチ名に分かれるものと解釈されます。
-
プロジェクト設定の値を個別に取得することはできません。現在の設定値を確認する場合は、プロジェクトのすべての設定を取得してください。
-
本稿執筆時点では、この機能は VCS として GitHub を利用している CircleCI 組織のみがお使いいただけます。
サンプル: 組織の特定のプロジェクトについてプロジェクト設定を取得する方法
curl -X GET --header "Circle-Token: <token>"
--header "Accept: application/json"
--header "Content-Type: application/json"
'https://circleci.com/api/v1.1/project/vcs-type/org-slug/project-slug/settings'
注: 「token」 は、お使いの CircleCI API トークンと置き換えてください。
応答:
注: 応答には、機密情報が含まれている可能性があります。現在設定されているブランチ名の正規表現は、"pr-only-branch-overrides"
の横に表示されます。
{
"irc_server": null,
"slack_integration_channel": null,
"irc_keyword": null,
"slack_integration_team_id": null,
"vcs-type": "github",
"aws": { "keypair": null },
"slack_webhook_url": null,
"slack_integration_team": null,
"username": "foo-user",
"branches":
{
"circleci-project-setup":
{
"running_builds": [],
"recent_builds":
[
{
"status": "success",
"outcome": "success",
"build_num": 1,
"vcs_revision": "f2aa5c44b9db87f76b5cec3827b5f973f80a2ff2",
"pushed_at": "2022-05-02T23:26:20.608Z",
"added_at": "2022-05-02T23:26:25.446Z",
"is_workflow_job": true,
"is_2_0_job": true,
},
],
"is_using_workflows": true,
"pusher_logins": ["foo-user"],
"last_success":
{
"status": "success",
"outcome": "success",
"build_num": 1,
"vcs_revision": "f2aa5c44b9db87f76b5cec3827b5f973f80a2ff2",
"pushed_at": "2022-05-02T23:26:20.608Z",
"added_at": "2022-05-02T23:26:25.446Z",
"is_workflow_job": true,
"is_2_0_job": true,
},
"last_non_success":
{},
"latest_workflows":
{
"say-hello-workflow":
{
"id": "231434a4-19da-46cd-b88f-91a92234ac00",
"status": "canceled",
"created_at": "2022-05-20T15:11:08.201Z",
},
},
"latest_completed_workflows":
{
"say-hello-workflow":
{
"id": "231434a4-19da-46cd-b88f-91a92234ac00",
"status": "canceled",
"created_at": "2022-05-20T15:11:08.201Z",
},
},
},
},
"jira": null,
"slack_integration_notify_prefs": null,
"slack_integration_webhook_url": null,
"slack_subdomain": null,
"following": true,
"slack_notify_prefs": null,
"irc_password": null,
"vcs_url": "https://github.com/foo-user/helloworld",
"default_branch": "main",
"irc_username": null,
"language": null,
"slack_channel_override": null,
"slack_api_token": null,
"has_usable_key": true,
"irc_notify_prefs": null,
"slack_channel": null,
"feature_flags":
{
"setup-workflows": false,
"set-github-status": false,
"build-prs-only": true,
"forks-receive-secret-env-vars": false,
"build-fork-prs": false,
"autocancel-builds": false,
"pr-only-branch-overrides": "main, release.*, enterprise-.*"
},
"slack_integration_channel_id": null,
"irc_channel": null,
"oss": false,
"reponame": "helloworld",
"slack_integration_access_token": null,
"ssh_keys": [],
}