ドキュメント
circleci.com
Start Building for Free

パイプラインのスケジュール実行

1 month ago1 min read
クラウド
Helpful Resources
このページの内容

はじめに

パイプラインのスケジュール実行により、スケジュールに沿って定期的にパイプラインをトリガーすることができます。

スケジュール実行はパイプラインに基づいているため、パイプラインのスケジュール実行にはパイプラインの使用における下記の機能がすべて備わっています。

パイプラインのスケジュール実行は、API を使って、または CircleCI Web アプリのプロジェクト設定から設定します。

パイプラインのスケジュール実行機能の使い方

パイプラインのスケジュール実行には、最初から設定する、またはスケジュール実行化した既存のワークフローをパイプラインのスケジュール実行に移行するという二つの方法があります。

最初から設定する

API を使用する

プロジェクトにスケジュール実行化したワークフローがなく、パイプラインのスケジュール実行を試してみたい場合:

  1. CircleCI トークンを準備する、または 手順に沿って新しいトークンを作成します。
  2. 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 に関するドキュメントスケジュールのセクションを参照してください。

プロジェクト設定を使う

  1. CircleCI アプリケーションで、サイドバーにある Projects に移動し、お客様のプロジェクトの横の省略記号 (…) をクリックします。 Project Settings ボタンは各プロジェクトのランディングページにもあります。
  2. Triggers に移動します。
  3. 新しいスケジュールを作成するには、Add Scheduled Trigger をクリックします。
  4. 新しいスケジュールの名前、タイムテーブル、パイプラインのパラメーター、実行ユーザー (スケジュールに関連付けられているユーザー)を定義し、トリガーを保存します。

スケジュール実行化したワークフローをパイプラインのスケジュール実行に移行

プロジェクトの作業をスケジュール化するには、現在はワークフローのスケジュール実行機能を利用しています。 しかしこの機能には制限があるため、スケジュール実行化したワークフローをパイプラインのスケジュール実行機能に移行することを検討してください。 ワークフローのスケジュール実行には以下のような制限があります。

  • 実行ユーザーを制御できないため、ワークフローのスケジュール実行では制限されたコンテキストを使用できません。
  • パイプラインの自動キャンセル操作を制御することができません。
  • 複雑な回避策がないと、ワークフローのスケジュール実行機能をダイナミックコンフィグで使用することはできません。
  • パイプラインをトリガーしないと、1つのブランチ上のスケジュール実行化されたワークフローの変更やキャンセルができません。
  • スケジュールを変更しないと、スケジュール実行化されたワークフローのテスト実行を開始できません。
  • ワークフローを Webhook で実行する場合は、 PR ブランチからのワークフローのスケジュール実行を制限できません。

スケジュール実行化したワークフローをパイプラインのスケジュール実行に移行するには 次の手順に従います。

  1. プロジェクトの.circleci/config.ymlで、以下の例のようなスケジュールされたトリガーを見つけます。

     daily-run-workflow:
       triggers:
         - schedule:
             # Every day, 0421Z.
             cron: "21 4 * * *"
             filters:
               branches:
                 only:
                   - main
       jobs:
         - test
         - build
    
  2. cron 式からトリガーを実行する頻度を解釈します。
  3. API またはプロジェクト設定を使用してスケジュールを作成するには、上記の 最初から設定すると同じ手順で行います。
  4. 設定ファイルで、 triggersの部分を削除して通常のワークフローと同じようにします。
     daily-run-workflow:
       jobs:
         - test
         - build
    

ワークフローのフィルター機能の追加

スケジュール実行化されたパイプラインは基本的にトリガーされたパイプラインであるため、設定内のすべてのワークフローが実行されます。

パイプライン値を使うことによりワークフローのフィルター機能を開始するすることも可能です。 例えば下記のようにします。

daily-run-workflow:
  when:
    and:
      - equal: [ scheduled_pipeline, << pipeline.trigger_source >> ]
      - equal: [ "my schedule name", << pipeline.schedule.name >> ]
  jobs:
    - test
    - build

上記の例では、when の下の2番目の equal は厳密には必要ではありません。 pipeline.schedule.name は、パイプラインがスケジュールによってトリガーされたときに使用可能なパイプライン値です。

スケジュールがトリガーされる時に実行しないワークフローのフィルタリングを追加することもできます。

daily-run-workflow:
  when:
    and:
      - equal: [ scheduled_pipeline, << pipeline.trigger_source >> ]
      - equal: [ "my schedule name", << pipeline.schedule.name >> ]
  jobs:
    - test
    - build

other-workflow:
  when:
    not:
      equal: [ scheduled_pipeline, << pipeline.trigger_source >> ]
  jobs:
   - build
   - deploy

FAQ

質問: 作成したスケジュールはどうやって探せば良いですか?

回答: スケジュール実行化されたパイプラインは CircleCI に直接保存されるため、スケジュール毎に関連付けされた UUID があります。 作成したスケジュールは、プロジェクト設定のトリガーのページで閲覧できます。 一つのプロジェクトの配下のすべてのスケジュールをリストアップすることも可能です。

curl --location --request GET "https://circleci.com/api/v2/project/<project-slug>/schedule" \
--header "circle-token: <PERSONAL_API_KEY>"

project-slug は、例えば、gh/CircleCI-Public/api-preview-docs のような vcs-slug/org-name/repo-name の形式を取ります。

質問: スケジュールしたパイプラインが実行されないのはなぜですか?

回答: 考えられる理由が 2つあり得ます。

  • スケジュール実行化されたパイプラインに設定されている実行ユーザーは現在も組織の一員ですか?
  • スケジュールに設定されたブランチが削除されていませんか?
  • ご自身の GitHub 組織が SAML 保護を使用してませんか? SAML トークンは頻繁に失効します。失効していると GiHub へのリクエストが失敗します。

質問: パイプラインのスケジュール実行が思っていたより遅いのはなぜですか?

回答: Cron 式と比較して、パイプラインのスケージュール実行にはスケジュール方法に微妙な違いがあります。

たとえば、08:00 (協定世界時) のスケジュールを 1 時間に 1 回と指定すると、このスケジュールされたパイプラインは 08:00 ~ 09:00 (協定世界時) の間に 1 回実行されます。 これは 08:00 (協定世界時) ちょうどに実行されるという意味ではないのでご注意ください。

このパイプラインのスケジュール実行は、その後は常に最初の実行と同じ時間に実行されます。 つまり、最初にスケジュールされたパイプラインが 08:11 (協定世界時) に実行された場合、その次も 08:11 (協定世界時) に実行されます。

質問: 正規表現はサポートしていますか?

回答: 現在はサポートしていません。 パイプラインのスケジュール実行には、Webhook、API 呼び出し、スケジュールに含まれるコミット SHA、ブランチ、タグ (完全認証、正規表現なし) などの高度に決定論的な入力が必要です。


ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。