パイプラインのスケジュール実行
このページの内容
- はじめに
- パイプラインのスケジュール実行機能の使い方
- Web アプリのプロジェクト設定を使用する
- API を使用する場合
- ワークフローのスケジュール実行からパイプラインのスケジュール実行への移行
- パイプラインのスケジュール実行のビデオチュートリアル
- FAQ
- 既存のワークフローのスケジュール実行をパイプラインのスケジュール実行に移行することはできますか?
- 作成したスケジュールはどうやって探せば良いですか?
- パイプラインのスケジュール実行の際に使われるタイムゾーンは?
- パイプラインを指定した日時にスケジュール実行することは可能ですか?
- スケジュールを設定したパイプラインは、指定した時間どおりに正確に実行されますか?
- パイプラインのスケジュール実行が思っていたより遅いのはなぜですか?
- 正規表現に対応していますか?
- 次のステップ
パイプラインのスケジュール実行機能は現時点では GitHub VCS ユーザーと Bitbucket VCS ユーザーにご利用いただけます。 パイプラインのスケジュール実行機能を使うと、スケジュールに基づき定期的にパイプラインをトリガーすることができます。 パイプラインのスケジュール実行では、以下のようなパイプラインのすべての機能が保持されます。
-
パイプラインに関連付けるユーザーの管理: これにより、 制限付きコンテキストの使用が可能になります。
-
セットアップ ワークフロー経由の ダイナミックコンフィグの使用
-
.circleci/config.yml
. の編集が不要なスケジュール変更 -
自動キャンセル機能の利用.
-
スケジュールに関連付ける パイプライン パラメーターの指定。
-
ワークフロー間などで共通するスケジュールの管理.
パイプラインのスケジュール実行は、API を使って、または CircleCI Web アプリのプロジェクト設定から設定します。
パイプラインのスケジュール実行は、1 つのブランチに対してのみ設定できます。 2 つのブランチに対してスケジュール実行をしたい場合、2 つのスケジュールを設定する必要があります。 |
はじめに
パイプラインのスケジュール実行は、CircleCI Web アプリまたは API から、スケジュールに基づいて定期的にパイプラインを起動することができます。 スケジュールは、毎日、毎週、毎月、または非常に特定のタイムテーブルの範囲にすることができます 基本的なスケジュールされたパイプラインを設定するには、.circleci/config.yml
ファイルに追加の設定は必要ありませんが、この機能をより高度に使用するには、追加の .circleci/config.yml
設定が必要になります(例、ワークフローのフィルタリング、またはパラメータの使用など)。
パイプラインパラメータは、文字列、整数、またはブール値の形で型付けされたパイプライン変数です。 スケジュールされたパイプラインにパラメータを追加するには、Web アプリでスケジュールを設定する際に、トリガーフォームから行います。 この方法で設定されたパラメータは、パラメータキー(parameters
)を使用して設定ファイルに追加する必要があります。
スケジューリングされたパイプラインは、CircleCI スケジューリングシステム、または特定のユーザー(例えば、自身)である "actor" によって実行するように設定されています。 ワークフローで制限されたコンテキストを利用する場合、スケジューリングアクターは重要な考慮事項です。 ワークフローを実行するユーザー(actor)がコンテキストへのアクセス権を持っていない場合、ワークフローは Unauthorized
ステータスで失敗します。
基本的な使い方は パイプラインのスケジュール実行を夜間に設定するページで、より高度な例は 複数のワークフローを使ったパイプラインのスケジュール実行 ページをご覧ください。
パイプラインのスケジュール実行機能の使い方
パイプラインのスケジュール実行機能を使うには、API を使用する方法と、CircleCI Web アプリを使用する方法があります。 それぞれの方法を下記でご紹介します。
Web アプリのプロジェクト設定を使用する
-
CircleCI Web アプリで、サイドバーにある Projects に移動し、プロジェクトの隣にある 省略記号 (…) をクリックします。 Project Settings ボタンは各プロジェクトのランディングページにもあります。
-
Triggers に移動します。
-
新しいスケジュールを作成するには、Add Trigger をクリックします。
-
フォームに入力して新しいスケジュールを定義し、Save Trigger をクリックします。
このフォームでは、 パイプラインパラメーター を追加するオプションも指定します。これは、設定ファイルで最初に宣言した型指定されたパイプライン変数です。
複数のワークフローで共通のスケジュールを管理するには、.circleci/config.yml
ファイルで手動で設定する必要があります。 コード例については 複数のワークフローを使ったパイプラインのスケジュール実行のページを参照してください。
API を使用する場合
プロジェクトにスケジュール化したワークフローがなく、パイプラインのスケジュール実行を試してみたい場合:
-
CCI トークンを準備します、または API トークンの管理 のページに記載されている手順に従って新しいトークンを作成します。
-
API を使用 して新しいスケジュールを作成します。 たとえば以下のようになります。
curl --location --request POST "https://circleci.com/api/v2/project/<project-slug>/schedule" \
--header "circle-token: <PERSONAL_API_KEY>" \
--header "Content-Type: application/json" \
--data-raw '{
"name": "my schedule name",
"description": "some description",
"attribution-actor": "system",
"parameters": {
"branch": "main"
<additional pipeline parameters can be added here>
},
"timetable": {
"per-hour": 3,
"hours-of-day": [1,15],
"days-of-week": ["MON", "WED"]
}
}'
詳細については、 API v2 に関するドキュメントの スケジュール のセクションを参照してください。
ワークフローのスケジュール実行からパイプラインのスケジュール実行への移行
パイプラインのスケジュール実行に移行する必要がある既存のワークフローがある場合は、 パイプラインのスケジュール実行への移行ガイドをご覧ください。
パイプラインのスケジュール実行のビデオチュートリアル
このビデオでは以下のシナリオに対する短いチュートリアルをご覧いただけます。
-
Web アプリでスケジュールを設定する
-
API を使ってスケジュールを設定する
-
ワークフローのスケジュール実行からパイプラインのスケジュール実行への移行する
これらのシナリオに関するドキュメントは、以下のページを参照してください: - パイプラインのスケジュール実行を夜間に設定する - 複数のワークフローを使ったパイプラインのスケジュール実行
FAQ
既存のワークフローのスケジュール実行をパイプラインのスケジュール実行に移行することはできますか?
はい、できます。詳細については、 パイプラインのスケジュール実行への移行 を参照してください。
作成したスケジュールはどうやって探せば良いですか?
スケジュール化されたパイプラインは CircleCI に直接保存されるため、スケジュール毎に関連付けされた UUID があります。 作成したスケジュールは、プロジェクト設定のトリガー(Triggers)のページで閲覧できます。 一つのプロジェクトの配下のすべてのスケジュールをリストアップすることも可能です。
curl --location --request GET "https://circleci.com/api/v2/project/<project-slug>/schedule" \
--header "circle-token: <PERSONAL_API_KEY>"
GitHub および Bitbucket ユーザーの場合: project-slug
は、例えば、gh/CircleCI-Public/api-preview-docs
のような vcs-type/org-name/repo-name
の形式を取ります。
パイプラインのスケジュール実行の際に使われるタイムゾーンは?
スケジュールの指定は、UTC 協定世界時のタイムゾーンに基づきます。
パイプラインを指定した日時にスケジュール実行することは可能ですか?
はい、できます。 スケジュールされたパイプラインは、 CircleCIウェブアプリ、または CircleCI API v2を使って設定できます。
現在 ワークフローのスケジュール実行機能を使用されている場合は、 移行ガイドを参照し、ワークフローのスケジュール実行をパイプラインのスケジュール実行に更新してください。
スケジュールを設定したパイプラインは、指定した時間どおりに正確に実行されますか?
スケジュールの正確性については保証できません。 スケジュールは、設定した時間にコミットがプッシュされたとして実行されます。
パイプラインのスケジュール実行が思っていたより遅いのはなぜですか?
Cron 式と比較して、パイプラインのスケージュール実行にはスケジュール方法に微妙な違いがあります。
たとえば、08:00 (協定世界時) のスケジュールを 1 時間に 1 回と指定すると、このスケジュールされたパイプラインは 08:00 ~ 09:00 (協定世界時) の間に 1 回実行されます。 これは 08:00 (協定世界時) ちょうどに実行されるという意味ではないのでご注意ください。
このパイプラインのスケジュール実行は、その後は常に最初の実行と同じ時間に実行されます。 つまり、最初にスケジュールされたパイプラインが 08:11 (協定世界時) に実行された場合、その次も 08:11 (協定世界時) に実行されます。
正規表現に対応していますか?
現在対応していません。 パイプラインのスケジュール実行には、Webhook、API 呼び出し、スケジュールに含まれるコミット SHA、ブランチ、タグ (完全認証、正規表現なし) などの高度に決定論的な入力が必要です。