ようこそ

API を使用したジョブのトリガー

CircleCI API を使用してジョブをトリガーする方法について説明します。

メモ: 現在のところ、API から 2.1 設定ファイルを使用するジョブをトリガーすることはできません。

概要

CircleCI API を使用して、.circleci/config.yml で定義したジョブをトリガーします。

curl を使用して deploy_docker ジョブをトリガーする例を以下に示します。

curl -u ${CIRCLE_API_USER_TOKEN}: \
     -d build_parameters[CIRCLE_JOB]=deploy_docker \
     https://circleci.com/api/v1.1/project/<vcs-type>/<org>/<repo>/tree/<branch>

この例には以下の変数が使用されています。

  • CIRCLE_API_USER_TOKEN: パーソナル API トークン.
  • <vcs-type>: 選択された VCS (github または bitbucket) を示すプレースホルダー変数
  • <org>: CircleCI 組織の名前を示すプレースホルダー変数
  • <repo>: リポジトリの名前を示すプレースホルダー変数
  • <branch>: ブランチの名前を示すプレースホルダー変数

API の関連情報については、CircleCI API ドキュメントにまとめられています。

API を通してジョブをトリガーする場合の重要な検討事項

  • API によってトリガーされるジョブに workflows セクションが含まれてもかまいません。
  • ワークフローが、API によってトリガーされるジョブを参照する必要はありません。
  • API によってトリガーされたジョブは、特定の CircleCI コンテキスト用に作成された環境変数にアクセスできません。
  • 環境変数を使用する場合は、それらの環境変数がプロジェクトレベルで定義されている必要があります。
  • 現在のところ、CircleCI 2.1 とワークフローを使用する場合には、単一のジョブをトリガーすることができません。
  • プロジェクトのビルドをトリガーするエンドポイントを使用して、CircleCI API でワークフローをトリガーできます。

API を使用したジョブの条件付き実行

以下は、デプロイされるビルドに対してのみ setup_remote_docker で Docker イメージを構築する場合の設定ファイル例です。

version: 2
jobs:
  build:
    docker:
      - image: ruby:2.4.0-jessie
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        environment:
          LANG: C.UTF-8
    working_directory: /my-project
    parallelism: 2
    steps:
      - checkout

      - run: echo "run some tests"

      - deploy:
          name: デプロイ ジョブを条件付きで実行
          command: |
            # これをビルド・デプロイのチェックに置き換えます (すなわち、現在のブランチが "release")
            if [[ true ]]; then
              curl --user ${CIRCLE_API_USER_TOKEN}: \
                --data build_parameters[CIRCLE_JOB]=deploy_docker \
                --data revision=$CIRCLE_SHA1 \
                https://circleci.com/api/v1.1/project/github/$CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME/tree/$CIRCLE_BRANCH
            fi

  deploy_docker:
    docker:

      - image: ruby:2.4.0-jessie
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    working_directory: /
    steps:
      - setup_remote_docker
      - run: echo "deploy section running"

この例では以下の点にご留意ください。

  • ビルド ジョブの deploy ステップを必ず使用してください。これを使用しないと、並列処理の値が N の場合に、N 回のビルドがトリガーされることがあります。
  • API 呼び出しを build_parameters[CIRCLE_JOB]=deploy_docker で使用し、deploy_docker ジョブのみが実行されるようにします。

関連項目

トリガー