2025.03.06 自動化

CircleCIとは？config.ymlの書き方・料金・Jenkins/GitHub Actionsとの違い【2026年版】

CircleCIは、リポジトリへのコミットをきっかけにビルド・テスト・デプロイを自動実行するクラウド型のCI/CDサービスです。設定は.circleci/config.ymlというYAMLファイル1枚に集約され、実行環境（Docker／Linux VM／macOS／Windows）とマシンサイズをジョブごとに選べるのが特徴です。この記事では「CircleCIとは何か」を出発点に、実際に動く最小構成、クレジット制の料金の考え方、GitHub ActionsやJenkinsとの違い、そして2026年時点で変わった仕様（テスト分割コマンドの世代交代、gen2リソースクラス、GitHub App統合）までを公式ドキュメントの記述に沿って整理します。

まとめ：CircleCIの要点

  • 正体：コミットを契機にビルド・テスト・デプロイを自動化するクラウドCI/CDサービス。設定は.circleci/config.yml（現行はversion: 2.1）に書く。
  • 強み：ジョブ単位でマシンサイズ（resource_class）を選べる粒度の細かさと、テストを複数コンテナへ分割して流す並列実行。
  • 料金：クレジット制。無料プランで毎月30,000クレジットと5ユーザー分の枠。DockerやLinux VMのmediumなら1分あたり10クレジット消費＝おおよそ月3,000分相当。
  • 2026年の注意点：テスト分割はcircleci tests splitからcircleci tests runへ世代交代済み。GitHub連携は公式がGitHub App統合を推奨。古い日本語記事の手順はここでズレていることが多い。
  • 選び方：GitHubに閉じた小〜中規模ならGitHub Actionsで足りる場面が多い。テスト時間の短縮とマシンサイズの最適化を突き詰めたい、あるいはVCSをまたぎたいならCircleCIが効く。

CircleCIとは：CI/CDのどこを自動化するサービスか

CI（継続的インテグレーション）は、開発者が書いたコードを頻繁に統合し、そのたびに自動でビルドとテストを走らせて壊れをすぐ検知する手法です。CDはその先のデプロイまでを自動化します。CircleCIはこのパイプラインを実行する側を丸ごと引き受けるサービスで、サーバーの用意もエージェントの常駐管理も不要な点が、自前でホストするJenkinsとの一番大きな違いになります。

動きは単純です。GitHubやGitLab、Bitbucketのリポジトリにpushやプルリクエストのイベントが発生すると、CircleCIがそれを検知し、リポジトリ内の.circleci/config.ymlを読んで、そこに定義されたジョブを実行環境の中で流します。テストが落ちればプルリクエストにその結果が返り、通ればそのまま次のジョブ（デプロイなど）へ進みます。CI/CDの位置づけそのものを整理したい場合はDevOpsとは？開発と運用を統合する実践・ツール・導入判断を実装視点で解説、テストを自動で回す狙いについてはリグレッションテスト（回帰テスト）とは？目的・範囲選定・自動化と実施判断を解説も参考になります。

2026年時点の前提：GitHub連携は「GitHub App」が推奨

ここは古い解説記事と現行仕様がもっとも食い違うポイントです。CircleCIのGitHub連携には、従来からのOAuth連携と、新しいGitHub App統合の2方式が併存しています。公式ドキュメントは後者について「新しいトリガー機能の大半はGitHub App統合を通じて提供されるため、すべての新機能を利用できるようGitHub Appのインストールを推奨する」と明記しています。

両者は使い勝手がかなり違います。OAuth連携ではパイプラインはプロジェクトに1本きりで、設定ファイルは対象リポジトリの.circleci/config.ymlに固定、チェックアウトはSSH方式（チェックアウトキーを使う）でした。GitHub App統合では、パイプラインを複数作れて、設定ファイルはAppがアクセスできる任意のリポジトリ・任意のパスに置け、チェックアウトはHTTPSで行われます。トリガーもpushだけでなくプルリクエストのオープンやマージ、タグのpushなどに広がり、スケジュール実行はcron構文で書けます。これから新規に導入するならGitHub Appを選ぶのが素直です。

config.ymlの書き方：version 2.1の最小構成

始め方：リポジトリ接続から初回ビルドまで

導入の手順自体は短く、4ステップで初回ビルドまで到達します。(1) CircleCIにサインアップし、組織を作成する。(2) CircleCI GitHub Appをインストールし、対象リポジトリへのアクセスを許可する（前述のとおり新規導入ではこちらが推奨）。(3) リポジトリに.circleci/config.ymlを追加してコミットする。(4) pushすると、CircleCIがそれを検知してジョブが走り、Webの画面とプルリクエスト上に結果が返ります。設定ファイルさえリポジトリに入れば動き出すので、まずは次の最小構成をそのまま置いて、パイプラインが green になることを確認するのが早道です。

CircleCIの設定はすべて.circleci/config.ymlに書きます。冒頭で使う仕様のバージョンを宣言し、CircleCI Cloudと新しめのServerでは2.1を使います。公式ドキュメントに載っている最小の設定はこれだけです。

version: 2.1

jobs:
  build:
    docker:
      - image: cimg/base:2022.05
    steps:
      - run: echo "Say hello to YAML!"

ここで押さえたい規則が2つあります。1つは、ジョブを1つしか定義しない場合、そのジョブ名はbuildでなければならないこと。もう1つは、イメージの指定です。かつて広く使われたcircleci/nodeのような旧イメージ群は現在レガシー扱いで、現行の推奨はcimg/で始まる次世代のconvenience imagesです。古い記事のコピペでcircleci/node:latestと書いてしまうと、そこでつまずきます。

ジョブを2つ以上動かす、あるいは実行順序を制御するならworkflowsを足します。

version: 2.1

jobs:
  test:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run: npm ci
      - run: npm test
  deploy:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run: ./scripts/deploy.sh

workflows:
  test_and_deploy:
    jobs:
      - test
      - deploy:
          requires:
            - test
          filters:
            branches:
              only: main

requiresで依存関係を、filtersで対象ブランチを絞っています。この例なら、テストが通ったときだけ、しかもmainブランチのときだけデプロイが走ります。段階的にリリースする設計まで踏み込むならカナリアリリースとは？段階リリースの仕組み・他方式との違い・実装と採用判断を実装視点で解説が参考になります。YAMLで環境を宣言的に定義する感覚はdocker-composeとは？複数コンテナをymlで定義し一括管理する仕組みを解説と近いものがあります。

実行環境とresource_class：マシンサイズはジョブごとに選ぶ

ジョブごとに実行環境（executor）を選べるのがCircleCIの設計の核です。Dockerコンテナ、Linux VM（machine）、macOS、Windows、GPU、Armがあり、さらにそれぞれでマシンサイズをresource_classとして指定します。CPUとメモリの割り当てがサイズごとに決まっており、公式は「resource_classを明示せずデフォルトに頼るのではなく、明示的に指定するのがベストプラクティス」としています（デフォルトは変更されうるため）。

jobs:
  build:
    docker:
      - image: cimg/base:2022.09
    resource_class: xlarge
    steps:
      - run: echo "Hello World"

2026年5月には、x86のDocker向けのgen2リソースクラス（medium.gen2のような表記）が正式提供（GA）されました。公式は従来世代（gen1）比で1.4倍高速としています。ただしこのDocker gen2は有料プラン限定で、無料プランでは使えません（Linux VMやRemote Dockerのgen2は無料プランでも利用可能なため、「gen2＝すべて有料」と誤解しないでください）。速い分クレジット消費レートも上がるので、短いジョブでは費用対効果を実測してから切り替えるのが安全です。macOSのマシンサイズはApple Silicon世代のm4pro.medium／m4pro.largeが現行で、古い記事に出てくるmacos.x86.medium.gen2のような表記は現在の一覧には存在しません。

ビルドを速くする2本の柱：並列実行とキャッシュ

テストの並列実行は「tests split」ではなく「tests run」へ

parallelismキーは、そのジョブを何個の実行環境に分けて走らせるかを指定します。4を指定すれば同じジョブが4コンテナで同時に立ち上がり、テストを4分割して流せます。ここで現行仕様と古い記事の差がはっきり出ます。長らく定番だったcircleci tests splitについて、公式ドキュメントは「circleci tests runに置き換えられた（superseded）」と明記しており、新しいコマンドは失敗テストだけを再実行するRerun Failed Testsの機能も使えます。

jobs:
  build:
    docker:
      - image: cimg/go:1.18.1
    parallelism: 4
    resource_class: large
    steps:
      - checkout
      - run: go list ./... | circleci tests run --command "xargs gotestsum --junitfile junit.xml --format testname --" --split-by=timings --timings-type=name

--split-by=timingsは過去の実行時間の実績データをもとに、各コンテナの所要時間が均等になるよう分割する指定です。これを効かせるにはテスト結果をJUnit形式のXMLで出力し、store_test_resultsでCircleCIに渡しておく必要があります（timings分割はXML内のfile属性とtestcaseのtime属性を見るため）。初回の実行時点ではまだタイミングデータが存在しないため最適化は効かず、2回目以降の実行で分割が実行時間ベースに寄っていきます（--split-byの既定値はテスト名ベースのnameです）。どのテストを流すかの範囲設計はテストカバレッジとは？C0/C1/C2の網羅率と計測ツール・目標設定を実装者向けに解説とあわせて考えると整理しやすくなります。

キャッシュは「上書きできない」前提でキーを設計する

依存パッケージのダウンロードを毎回やり直すとビルド時間の大半を食います。CircleCIのキャッシュは手動制御で、自動的な依存キャッシュは提供されていません。restore_cacheをインストールコマンドの前に、save_cacheを後ろに置くのが公式の型です。

steps:
  - checkout
  - restore_cache:
      keys:
        - v1-deps-{{ .Branch }}-{{ checksum "package-lock.json" }}
        - v1-deps-{{ .Branch }}-
        - v1-deps-
  - run: npm ci
  - save_cache:
      key: v1-deps-{{ .Branch }}-{{ checksum "package-lock.json" }}
      paths:
        - ~/.npm

設計上のポイントは3つです。第一に、キャッシュは書き込み後は不変（immutable）で、同じキーに対して上書きはできません。だからこそキーにはロックファイルのチェックサムを含め、依存が変わったときだけ新しいキーになるようにします。第二に、キーの一覧は「複数のキャッシュ」ではなく「1つのキャッシュに対するフォールバック候補」です。上から順に前方一致で探し、完全一致がなければ部分一致の古いキャッシュを拾います。第三に、先頭のv1-は手動のバージョン番号で、v2-に上げれば既存キャッシュを一括で無効化できます。

公式が明確にアンチパターンとしているのは、{{ epoch }}や{{ .BuildNum }}、{{ .Revision }}、{{ .Environment.CIRCLE_WORKFLOW_ID }}を主キーに使うことです。毎回キーが変わるためキャッシュがまったくヒットせず、保存だけがかさみます。またキャッシュ対象はnode_modulesのようなインストール済みディレクトリより、~/.npmのようなダウンロードキャッシュを選ぶのが推奨です。なおキャッシュの保持期間は既定で15日（これが上限）で、ジョブ単位にretentionキーで1日〜15日の範囲に縮められます。

料金：クレジット制の実際のところ

CircleCIの課金単位はクレジットで、秒単位で消費されます。1分あたりの消費レートは使ったマシンタイプとresource_classによって変わる、という設計です。ここは金額に直結するので、公式ドキュメントに数字が明示されているものだけを挙げます。

  • 無料枠：毎月30,000クレジットと5ユーザー分の無料シート。
  • 消費レートの目安：DockerまたはLinux VMのmediumで1分あたり10クレジット。つまり25,000クレジットで約2,500分のビルドに相当する、と公式が例示しています。無料枠の30,000クレジットは、この計算ならおおよそ月3,000分です。
  • 追加購入：25,000クレジット単位で15ドル（1クレジットあたり0.0006ドル）。購入したクレジットは毎月繰り越され、購入から1年で失効します。
  • オープンソース：無料プランの組織はpublicリポジトリのLinuxビルドに対し、月400,000クレジットまで無料で使えます（この枠の残量はWeb画面には表示されません）。
  • Docker Layer Caching：DLCを有効にしたジョブは1実行あたり200クレジットの追加消費。

見落としがちなのは、コンピュート時間だけでなく「アクティブユーザー数」も課金対象になる点です（機能へのアクセスはアクティブユーザー1人あたり月25,000クレジット相当の費用として扱われます）。ただしオープンソースプロジェクトへの貢献者はアクティブユーザーに数えられません。プランはFree／Performance（月15ドルから）／Scale（年額・要問い合わせ）に加え、自社インフラ内で動かすServerがあります。

セキュリティ：2023年のインシデントと、いま取るべき設計

CircleCIを検討するなら、2023年1月のセキュリティインシデントは避けて通れません。事実関係だけを整理すると、2022年12月にCircleCIの従業員のノートPCがマルウェアに感染し（アンチウイルスは検知しませんでした）、盗まれたセッションクッキーによって2要素認証済みのSSOセッションがなりすまされました。攻撃者は本番システムへ権限昇格し、同年12月22日に顧客の環境変数・トークン・キーを含むデータのサブセットを持ち出しています。データは保存時に暗号化されていましたが、稼働中のプロセスから暗号鍵ごと抜かれたため、暗号化は防御になりませんでした。CircleCIは全ユーザーに対し、CircleCIに保存していたすべてのシークレットのローテーションを要請しました。

この教訓が効いてくるのが、いまのシークレット管理の設計です。ポイントは長命の認証情報をCI側に置かないことに尽きます。CircleCIはジョブ実行時に$CIRCLE_OIDC_TOKENというOIDCトークンを環境変数として提供しており、これを使えばAWSやGCPのようなクラウドサービスに対し、長命のアクセスキーをCircleCIに保存することなく認証できます。AWSならIAMロールの信頼ポリシーにCircleCIのOIDCプロバイダを登録し、ジョブ側はトークンを提示して一時的な権限を受け取る形です。

複数プロジェクトで共有する認証情報は、プロジェクト単位の環境変数ではなくコンテキストにまとめ、組織管理者がセキュリティグループでアクセスを制限します。コンテキストの値は実行時に注入され、組織メンバーなら作成できますが、制限をかけられるのは管理者だけです。フォークされたプルリクエストにシークレットを渡す設定は、必要がなければ有効にしないのが安全側の判断になります。

GitHub Actions・Jenkinsとの違いと選び方

比較の前に、事実として押さえておきたい点があります。よく「Travis CIは終了した」と書かれますが、2026年7月時点でTravis CIはサービスを継続しています。また、CircleCIのセルフホスト版であるCircleCI Serverも現行製品として提供され続けています（ドキュメントの現行系列は4.10、Kubernetes上に展開）。

  • Jenkins：オープンソースで自前ホスト。プラグインで何でもできる反面、サーバーとプラグインの維持管理、バージョン追従、ビルドエージェントの面倒をすべて自分で見ることになります。CircleCIはそこを丸ごと引き受ける代わりに、実行時間に応じた課金が発生します。閉域網の要件があるならJenkinsかCircleCI Serverが選択肢です。
  • GitHub Actions：GitHubに統合されており、リポジトリがGitHubにあるなら導入の摩擦がほぼありません。一方CircleCIは、ジョブごとのマシンサイズ指定、実行時間の実績にもとづくテスト分割、キャッシュやDLCといった「ビルド時間を削る」ための道具立てが体系化されているのが持ち味です。GitLabやBitbucketも含め複数のVCSを扱う組織にも向きます。なお両者の優劣を示す中立な一次情報は存在しないため、ここは自社のテストスイートで実測して決めるのが確実です。

実務的な判断基準はシンプルです。GitHubに閉じていて、テスト時間が数分で収まる規模なら、まずGitHub Actionsで足ります。テストが十数分〜数十分に膨らんで開発のリズムを壊し始めたとき、並列実行とマシンサイズの最適化で時間を買い戻す道具としてCircleCIが効いてきます。

2026年のCircleCI：ChunkとMCPサーバー

CircleCIはAIエージェント方面に軸足を移しています。2025年9月に発表されたChunkは、CI/CD向けの自律エージェントで、フレーキーテスト（ときどき落ちる不安定なテスト）の修正、失敗したビルドの修復、テストの追加、設定の最適化などをエージェントが行いプルリクエストとして提出します。2026年7月時点でベータ提供であり、公式は「ベータ期間中の追加費用はなく、正式提供（GA）時には有料機能になる」としています。採用を検討するならこの前提を踏まえてください。

モデルの選び方は4通りあります。既定はCircleCIが管理するプロバイダ（Anthropic製モデル・APIキー不要、1日あたり40万トークン）で、これに加えてAnthropic・OpenAI・Amazon Bedrockについては自前のAPIキーを持ち込む（BYOK）構成も選べます。「必ず自前のキーが要る」わけではありません。もう1つの制約は連携先で、Chunkの利用にはCircleCI GitHub Appの導入が前提となるため、GitLabやBitbucketの組織では利用できません。前述のGitHub App推奨は、この点でも実利があります。

もう1つがCircleCI MCPサーバーです。エディタやAIエージェントから自然言語でビルド失敗の診断やパイプラインの操作ができるもので、公式リポジトリ（CircleCI-Public/mcp-server-circleci）は現在も活発に更新されています。CIのログを読みに行かずに、手元のエージェントへ「直近の失敗の原因は？」と聞けるという体験は、日々のデバッグの摩擦を確実に減らします。

よくある質問

CircleCIは何ができますか？

リポジトリへのpushやプルリクエストをきっかけに、ビルド・テスト・デプロイを自動で実行できます。具体的には、テストを複数の実行環境に分割して並列で流す、依存パッケージをキャッシュしてビルド時間を削る、ジョブごとにマシンサイズ（resource_class）を変える、Orbsで設定を再利用する、mainブランチのときだけデプロイするといった制御が.circleci/config.ymlのYAML1枚で書けます。実行環境はDocker・Linux VM・macOS・Windows・GPU・Armから選べます。

CircleCIは無料で使えますか？

使えます。無料プランでは毎月30,000クレジットと5ユーザー分の無料シートが付きます。DockerやLinux VMのmediumサイズは1分あたり10クレジット消費なので、単純計算で月およそ3,000分のビルドに相当します。publicリポジトリのオープンソースプロジェクトであれば、Linuxビルドに対して月400,000クレジットまで無料枠が拡大されます。

CircleCIとJenkinsはどちらを選ぶべきですか？

インフラの管理を自分たちで持ちたいか、持ちたくないかで決まります。Jenkinsはサーバーもプラグインもエージェントも自前で運用する代わりに無償かつ自由度が高く、閉域網にも置けます。CircleCIはその運用を肩代わりする代わりに実行量に応じた課金が生じます。コンプライアンス上の要件で自社インフラ内に置く必要がある場合は、CircleCI Server（セルフホスト版）という選択肢もあります。

config.ymlのversionは何を書けばよいですか？

version: 2.1です。CircleCI Cloudと新しめのServerはこのバージョンを使い、orbsやexecutors、パラメータ化されたジョブといった再利用のための機能はすべて2.1で使えます。なお2023年12月1日以降に作成されたプロジェクトでは、動的コンフィグ（setup workflows）が既定で有効になっています。

ビルドが遅いときはどこから手を付けるべきですか？

まず依存インストールのキャッシュがヒットしているかを確認します（キーにロックファイルのチェックサムが入っているか、restore_cacheがインストール前に置かれているか）。次にテストの並列化で、parallelismとcircleci tests run --split-by=timingsを使い実行時間ベースで分割します。それでも足りなければresource_classを上げますが、消費クレジットも比例して増えるため、実測してから判断してください。

circleci tests splitはもう使えないのですか？

公式ドキュメントはcircleci tests splitがcircleci tests runに置き換えられた（superseded）と明記しており、ドキュメント上のサンプルもtests runが主になっています。新規に書くならtests runを選んでください。失敗したテストだけを再実行するオプションもこちらでのみ利用できます。ただし公式も「サードパーティツールとの連携によっては、いまもcircleci tests splitが必要になる場合がある」と留保しているため、既存の設定を機械的に置き換える前に連携先の要件を確認してください。

関連記事

資料請求

RELATED POSTS 関連記事

一覧へ戻る