🎃

CircleCI Pipeline のAPI 実行と外部パラメータによる処理の切り替え

に公開
CircleCI
tech

今日はCircleCIのPipelineをAPIから実行してみます。その時にパラメータの入力を受け付け、それにより内部の処理を変更させてみます。

CircleCI API v2 と v1

https://circleci.com/docs/api-intro/
CircleCIのAPIには大きく2世代が存在しているようです。ドキュメントを見るとV2はPipelineの呼び出し時にパラメータとして値を渡すことでcoinfig.ymlの処理を分岐させたり、設定の上書きが行えるようです。また処理の安定もされており、v1はまだサポートされているものの、CircleCIではV2への移行を推奨しているようです。

さっそくやってみる

ではAPI経由でPipelineの呼び出しを行ってみます。

1. 環境準備

https://zenn.dev/kameoncloud/articles/641dbdd496a59d
などを参考にGitHubへのPushでPipelineが実行されるようにしておきます。

2. Access Token の発行

https://zenn.dev/kameoncloud/articles/707a448101e5c0
こちらの記事を参考にアクセストークンを発行しておきます。CircleCIにはアカウント全体に効力を持つAccess TokenとProject単位に効力を持つProject トークンの２種類が存在していますが、v2 APIは記事執筆の2025年7月時点ではAcccess Tokenのみが対応しているようです。

3. 必要なパラメータの取得

Projectのトップ画面、右上からSettingsをクリックします。

Project Slugをコピーします。

次に左ペインのPipelinesからDefinition IDをコピーしておきます。

4. config.ymlの入れ替え

config.ymlを以下に入れかえます。これはテスト用に単純にnode環境を構築しバージョンを報告するだけを行います。外部パラメータ入力により起動するNodeバージョン（コンテナイメージタグ）を指定できるようにしてあります。なにも指定しなければdefaultの18.17が起動します。

version: 2.1

# パラメータの定義
parameters:
  node_version:
    type: string
    default: "18.17"

# ジョブの定義
jobs:
  install_node:
    parameters:
      node_version:
        type: string
        default: "18.17"
    docker:
      - image: cimg/node:<< parameters.node_version >>
    steps:
      - run:
          name: "Node.js確認"
          command: |
            echo "Node.jsバージョン:"
            node --version
            echo "npmバージョン:"
            npm --version

# ワークフローの定義
workflows:
  node_workflow:
    jobs:
      - install_node:
          node_version: << pipeline.parameters.node_version >>

5. curl によるAPIの実行

curl -X POST --location 'https://circleci.com/api/v2/project/<project slug>/pipeline/run' \
--header 'Circle-Token: <Access Token>' \
--header 'content-type: application/json' \
--data '{
  "definition_id": "<Definiton ID>",
  "config": {"branch": "main"},
  "checkout": {"branch": "main"}
  }'

<project slug>, <Access Token>,<Definiton ID>は皆さんの環境ごとに置き換えます。
実行すると以下のようなResponseが戻ります。

{
    "state": "pending",
    "created_at": "2025-07-12T12:35:57.633Z",
    "number": 23,
    "id": "2af6571e-d0c5-4592-a3d7-a652f81b6910"
}


API経由でPipelineがトリガーされたことがわかります。
18.17.1が構築されたバージョンであることが表示されています。

6. パラメータによるバージョン指定

今度はBodyに"parameters": {"node_version": "20.5"}を付け加えて実行します。

curl -X POST --location 'https://circleci.com/api/v2/project/<project slug>/pipeline/run' \
--header 'Circle-Token: <Access Token>' \
--header 'content-type: application/json' \
--data '{
  "definition_id": "<Definiton ID>",
  "config": {"branch": "main"},
  "checkout": {"branch": "main"},
  "parameters": {"node_version": "20.5"}
  }'

ポイントはconfig.ymlの以下です。

workflows:
  node_workflow:
    jobs:
      - install_node:
          node_version: << pipeline.parameters.node_version >>

workflowsの<< pipeline.parameters.node_version >>APIからJSON BODYで受け取ったバージョンがdockerイメージのバージョンとして引き渡されており、任意のバージョンが起動します。

    docker:
      - image: cimg/node:<< parameters.node_version >>

テストやデプロイの切り替え

同様の仕組みでテスト実行の有無やDeployの有無の切り替えも可能です。

version: 2.1

# パラメータの定義
parameters:
  node_version:
    type: string
    default: "18.17"
  run_tests:
    type: boolean
    default: true
  environment:
    type: string
    default: "development"

# ジョブの定義
jobs:
  setup:
    parameters:
      node_version:
        type: string
        default: "18.17"
    docker:
      - image: cimg/node:<< parameters.node_version >>
    steps:
      - run:
          name: "環境確認"
          command: |
            echo "Node.jsバージョン: $(node --version)"
            echo "環境: << pipeline.parameters.environment >>"

  test:
    parameters:
      node_version:
        type: string
        default: "18.17"
    docker:
      - image: cimg/node:<< parameters.node_version >>
    steps:
      - run:
          name: "テスト実行"
          command: |
            echo "テストを実行中..."
            echo "Node.js $(node --version) でテスト完了!"

  deploy:
    docker:
      - image: cimg/base:stable
    steps:
      - run:
          name: "デプロイ"
          command: |
            echo "環境: << pipeline.parameters.environment >>"
            echo "デプロイ完了!"

# ワークフローの定義
workflows:
  main_workflow:
    jobs:
      # 1. セットアップ（常に実行）
      - setup:
          node_version: << pipeline.parameters.node_version >>
      
      # 2. テスト（run_testsがtrueの場合のみ）
      - test:
          node_version: << pipeline.parameters.node_version >>
          requires:
            - setup
          when: << pipeline.parameters.run_tests >>
      
      # 3. デプロイ（production環境の場合のみ）
      - deploy:
          requires:
            - setup
          when:
            equal: [ "production", << pipeline.parameters.environment >> ]

curl -X POST --location 'https://circleci.com/api/v2/project/<project slug>/pipeline/run' \
--header 'Circle-Token: <Access Token>' \
--header 'content-type: application/json' \
--data '{
  "definition_id": "<Definition ID>",
  "config": {"branch": "main"},
  "checkout": {"branch": "main"},
  "parameters": {
    "node_version": "20.5",
    "run_tests": true,
    "environment": "development"
  }
}'

Discussion