CircleCIとは？使い方・config.ymlの書き方と料金（無料枠30,000クレジット）【2026年10月】

CircleCIは、GitHubなどのリポジトリへのpushやプルリクエストをきっかけに、ビルド・テスト・デプロイを自動で実行するクラウド型のCI/CDサービスです。設定はリポジトリの.circleci/config.ymlに書き、ジョブごとに実行環境（Docker・Linux VM・macOS・Windows・GPU・Arm）とマシンサイズを選びます。この記事では、仕組みと始め方、config.ymlの書き方、クレジット制の料金をプラン別の数字で整理したうえで、2026年10月時点の公式ドキュメントで変わった点（テスト分割のcircleci testsuite、CLI v1、スケジュールトリガー）まで押さえます。

まとめ：CircleCIの要点（2026年10月時点）

• 正体：コミットを契機にビルド・テスト・デプロイを回すクラウドCI/CD。設定は.circleci/config.ymlにversion: 2.1で書く。自社インフラに置くならCircleCI Server（現行4.10系）。
• 料金：Freeは月30,000クレジットと5ユーザーまで無料。Docker mediumは1分10クレジットなので約3,000分、Docker smallなら約6,000分。Performanceは月15ドルから、25,000クレジットごとに15ドル。
• 書き方の現行：イメージはcimg/系、GitHub連携はGitHub App、定期実行はスケジュールトリガー、テスト分割はcircleci testsuiteが公式の推奨。
• 選び方：GitHubだけで完結し、今のCIの待ち時間に不満が無ければGitHub Actionsで足ります。同じテストを両方で流し、短縮できる時間と増える費用・移行の手間を比べて、時間の価値が上回るときにCircleCIを選びます。

CircleCIとは：コミットを契機にビルドからデプロイまで自動で回すサービス

CI（継続的インテグレーション）は、コードを変更するたびに自動でビルドとテストを走らせ、壊れたことをすぐに知る仕組みです。CDは、いつでも本番に出せる状態を保つ継続的デリバリーと、本番への反映まで自動で行う継続的デプロイメントの2つを指します。CircleCIはこの実行基盤をクラウドで提供するサービスで、サーバーとビルドエージェントを自前で運用するJenkinsとはここが違います。CI/CDそのものの位置づけはDevOpsとは？アジャイル・CI/CDとの違いとDORA 5指標での成果の測り方で整理しています。

流れは次のとおりです。pushなどのイベントが起きると、CircleCIが.circleci/config.ymlを読んでジョブを動かし、結果をWeb画面とプルリクエストのステータスに返します。対応するVCSはGitHub・GitLab（self-managed含む）・Bitbucket Cloudで（Bitbucket Data Centerとの連携は2026年10月1日で終了）、2026年10月時点ではCursor Originとの連携もベータで加わっています（VCS別の機能対応表）。

パイプライン・ワークフロー・ジョブ・ステップの関係

設定を読むときに混同しやすい4語です。公式の定義では、パイプラインは設定全体、ワークフローはジョブの実行順と条件を決めるもの、ジョブは1つの実行環境（executor）の中でステップを順に流す単位、ステップはcheckout・run・save_cacheのような個々の命令です。

Cloud・Server・セルフホストランナーの違い

「CircleCI Enterprise」と呼ばれていたオンプレミス版は、現在のCircleCI Serverです。違いは次の3形態で整理できます。

Serverには、CLI v1・API v3・スケジュールトリガー・MCPサーバーといったCloudの新機能が入っていません。公式のエージェント向けの現行デフォルト一覧も、Serverでは旧来のCLI v0とtriggers.schedule、circleci tests splitを使うよう書き分けています。

CircleCIの使い方：GitHub連携から初回ビルドまで

初回ビルドまでの流れは次のとおりです。サインアップして組織を作り、Webアプリで「Create Project」からプロジェクトを作成します。続く画面でパイプラインに名前を付け、リポジトリを選びます（GitHubが未接続ならここでCircleCI GitHub Appをインストールして対象リポジトリへのアクセスを許可します）。トリガーは既定で「コミットごとにビルド」が1つ入るので、.circleci/config.ymlを追加してpushすれば最初のパイプラインが走ります。

GitHub連携の2方式：OAuthとGitHub Appの違い

GitHubとの連携方式は、従来のOAuthと新しいGitHub Appの2つが併存しています。公式は新規ではGitHub Appを推奨しており、使える機能も異なります。GitHub Appではパイプラインを1プロジェクトに複数作れ、設定ファイルを任意のリポジトリ・任意のパスに置け、チェックアウトはHTTPSで行います。プルリクエストのオープンやマージ、タグのpushといったpush以外のイベントでも起動できます。後述のAIエージェントChunkや、GitHub Actionsのワークフローファイルをそのまま実行するプレビュー機能もGitHub App前提です。

初回ビルド用config.ymlの最小構成

次の内容を.circleci/config.ymlとして置けば動きます。cimg/で始まるのがCircleCIの現行のイメージ群（convenience images）です。古い記事にあるcircleci/nodeのような旧イメージは非推奨なので、コピーするときは置き換えてください。

version: 2.1
jobs:
  build:
    docker:
      - image: cimg/base:current
    resource_class: small
    steps:
      - checkout
      - run: echo "Hello, CircleCI"
workflows:
  main:
    jobs:
      - build

versionは2.1にします。version: 2.0のサポートは2026年9月21日で終わり、それ以降は2.1でないパイプラインはコンパイルに失敗します（公式の告知）。Orbsやパイプラインパラメータ、再利用できるcommands・executorsも2.1で入った機能です。インデントにタブを入れるとYAMLとして読めずに止まるので、スペースで揃えます。

config.ymlの書き方：主要キーとworkflows・Orbs

config.ymlの最上位に置く主なキーは6つです。小さな設定ではversion・jobs・workflowsだけで足り、Orbが提供するジョブだけを呼ぶ場合はjobsも省けます。

workflowsによる実行順と対象ブランチの制御

テストが通ったときだけ、しかもmainブランチのときだけデプロイする、という典型的な形です。requiresで依存関係を、filtersで対象ブランチを絞ります。リポジトリにpackage-lock.jsonとnpm testのスクリプト、実行権限を付けたscripts/deploy.shがある前提です。

version: 2.1
jobs:
  test:
    docker:
      - image: cimg/node:24.22
    steps:
      - checkout
      - run: npm ci
      - run: npm test
  deploy:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run: ./scripts/deploy.sh
workflows:
  test_and_deploy:
    jobs:
      - test
      - deploy:
          requires:
            - test
          filters:
            branches:
              only: main

デプロイ処理はrunステップで書きます。かつてのdeployステップは非推奨です。段階的に本番へ出す設計はカナリアリリースとは？段階リリースの仕組み・他方式との違い・実装と採用判断を実装視点で解説が参考になります。

Orbsによる定型処理の再利用

Orbsは、ジョブ・コマンド・executorをまとめて配布する設定パッケージです。公開のレジストリOrbsは名前空間/orb名@バージョンで読み込み、セマンティックバージョンで固定されます。組織内だけで共有するプライベートOrbsは全プランで使えます。Node.js公式Orbの最新版7.2.1で、Jestのテストを回す例です。

version: 2.1
orbs:
  node: circleci/[email protected]
workflows:
  test:
    jobs:
      - node/test:
          test-results-for: jest
          executor:
            name: node/default
            tag: "24.22"
            resource_class: medium

resource_classを明示しているのには理由があります。このOrbのnode/default executorは既定がlarge（4 CPU・8GB）で、Docker largeは1分20クレジットと、mediumの2倍を消費します。Orbは中身のYAMLを読み、マシンサイズとイメージのタグは自分で固定してから使います。

実行環境とresource_classの選定基準

マシンサイズはresource_classでジョブごとに指定します。既定値は変わることがあるため、公式は明示を勧めています。x86のDockerには従来の世代と並んでmedium.gen2のようなgen2クラスがあり、2026年5月に正式提供、8月28日からはFreeプランでも使えるようになりました（公式の告知）。単価は同じサイズで2割高く、mediumで10→12クレジット/分です。x86のLinux VMのgen2はmediumで18クレジット/分と従来（10）の1.8倍で、Arm向けのgen2はベータ提供（Linux VMのmediumで6クレジット/分）です。macOSはM4 Pro世代のm4pro.medium・m4pro.largeが現行です。gen2は速さと単価の両方が変わるので、同じジョブを両方で流し、所要時間×単価で比べてから切り替えます。

定期実行向けスケジュールトリガーの設定

夜間ビルドのような定期実行は、CloudではWeb画面またはAPIで作るスケジュールトリガーが現行の方法です。GitHub Appのパイプラインならcron式をそのまま書けます。ワークフロー内にtriggers: - schedule: cron:と書く旧来の「スケジュールワークフロー」は、公式がスケジュールトリガーへの移行手順を公開しています。cronの時刻はUTCで、21 4 * * *は日本時間の13時21分です。

CircleCIの料金：クレジット制とプラン別の上限

CircleCIの課金はクレジット単位です。マシンの種類とサイズごとに1分あたりの単価が決まっていて、実行中は秒単位で消費されます。アクティブユーザー数もクレジットで課金される点が、時間課金だけのサービスと違います。以下は2026年10月時点の公式料金ページの値です（税別）。

無料クレジットは翌月に繰り越されません。Performanceで購入したクレジットは翌月以降に繰り越され、購入から1年で失効します。SSO・設定ポリシー・監査ログのストリーミング・予算管理はScaleの機能です（プラン概要）。

無料枠30,000クレジットで動かせる時間

何分動くかは、使うリソースクラスの単価で決まります。主なクラスの単価は価格表（2026年10月8日更新）のとおりです。

現在の公式料金ページでFreeプランに書かれている「最大6,000」は、Docker smallで換算したビルドの分数です。クレジット数は30,000なので、両者を取り違えないようにします。publicリポジトリのオープンソースは、Linux・Arm・Dockerに限り月400,000クレジット（80,000分相当）まで無料で使えます。WindowsとmacOSは通常の30,000クレジットの範囲です。

コンピュート以外にかかる費用

見積もりで漏れやすいのは次の4つです。Docker Layer Caching（DLC）は有効にしたジョブ1回ごとに200クレジット（約0.12ドル）かかり、並列で3ジョブ動けば600クレジットになります。ストレージ（キャッシュ・ワークスペース・アーティファクトの保存）はプランの無料分（Freeは2GB-月）を超えた分が1GB-月あたり420クレジットです。ネットワークの課金はセルフホストランナーへの転送だけが対象で、Freeは1GBまで無料、超過は1GBあたり420クレジット。IPレンジ機能は使ったデータ1GBあたり450クレジットかかります。テスト関連のSmarter Testingは、テスト影響分析や動的なテスト分割などの有料機能が、月の無料分（Free 1,000・Performance 10,000・Scale 100,000テストアトム）を超えると100,000テストアトムごとに3,000クレジットかかります。テストアトムは通常テストファイル1つのことで、再実行を含めパイプラインを実行するたびに評価した数が計上されます。

主要11製品の無料枠を横並びで比べるならCI/CDツール比較｜主要11製品の無料枠・料金と選び方【2026年10月】が早いです。

ビルドを速くする：テスト分割とキャッシュの設計

circleci testsuiteによるテストの並列分割

ジョブにparallelism: 4と書くと、同じジョブが4台で同時に起動し、テストを4分割して流せます。分割に使うコマンドはこの数年で2回変わっています。circleci tests splitはいったんcircleci tests runに置き換えられ、現在の公式の推奨はSmarter Testingのcircleci testsuiteです。旧来のcircleci tests系も動き続けますが、公式の導入手順はtestsuiteを基準に書かれています。

testsuiteでは、テストの洗い出し方と実行方法を.circleci/test-suites.ymlに書きます。Vitestの例です。

# .circleci/test-suites.yml
name: ci tests
discover: npx vitest list --filesOnly
run: npx vitest run --reporter=junit --outputFile="<< outputs.junit >>" --silent --bail 0 << test.atoms >>
outputs:
  junit: test-reports/tests.xml

# .circleci/config.yml のテストジョブ
  test:
    docker:
      - image: cimg/node:24.22
    parallelism: 4
    steps:
      - checkout
      - run: npm ci
      - run: circleci testsuite run "ci tests"
      - store_test_results:
          path: test-reports

--split-by=timingsのような指定は要りません。parallelismがあれば過去の実行時間で分割し、時間のデータが無い初回は名前で分割します。この静的な分割と、「失敗から再実行」で落ちたテストだけを流し直す機能は全プランで無料です。導入前にcircleci testsuite doctor "ci tests"を手元で実行すると、設定の誤りを指摘してくれます。ローカルで使うCLIは現在CLI v1が現行で、旧版（v0.1.x）を入れている場合はアンインストールしてから入れ直します。旧版にあったcircleci local execute（ジョブを手元のDockerで動かす機能）はv1で削除されました。

上書き不可のキャッシュに対応したキー設計

CircleCIのキャッシュは自動では効きません。restore_cacheを依存のインストールの前に、save_cacheを後ろに置きます。

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

キャッシュは書き込んだ時点で固定され、同じキーには上書きできません。キーにロックファイルのチェックサムを入れ、依存が変わったときだけ新しいキーになるようにします。keysの2行目以降は前方一致で探すフォールバックです。先頭のv1-をv2-に上げれば、既存のキャッシュをまとめて復元の対象から外せます（保存済みのデータは保持期間が切れるまで残ります）。{{ epoch }}や{{ .BuildNum }}を主キーに入れると毎回別キーになり、保存だけが増えてヒットしません。保持期間は既定で15日（上限）で、ジョブのretentionキーで1日から15日の範囲に短くできます（キャッシュの公式ガイド）。

失敗したジョブの調べ方とよくあるつまずき

ログだけで原因が分からないときは、ジョブの「Rerun」メニューから「Rerun job with SSH」を選ぶと、同じ環境にSSHで入れます。事前にCircleCIのユーザー設定かGitHubのアカウントにSSH公開鍵を登録しておきます。注意点は、SSHでの操作が対話型のログインシェルになることです。通常のステップは非対話シェルで動くため、SSHでは成功しても本番のステップでは失敗することがあります（SSH再実行の公式手順）。

導入初期に詰まりやすいのは次のケースです。

• パイプラインが起動しない：ファイルの置き場所が.circleci/config.ymlでない、またはGitHub Appに対象リポジトリへのアクセスを許可していない。
• YAMLの解析エラー：インデントにタブが混ざっている。手元のcircleci config validateで事前に確認できる。
• 古い記事のコピーで失敗：circleci/系の旧イメージ、version: 2、廃止済みのリソースクラスを書いている。
• キャッシュが一度も当たらない：キーにビルド番号や時刻が入っている。
• クレジットの減りが速い：Orbの既定のresource_classがlargeになっている、DLCを全ジョブで有効にしている。

セキュリティ：2023年のインシデントとOIDCでの設計

CircleCIは2023年1月4日にセキュリティインシデントを公表し、利用者に保存しているシークレットをすべてローテーションするよう求めました。公式の事後報告によると、従業員のノートPCがマルウェアに感染して2要素認証済みのSSOセッションのクッキーが盗まれ、2022年12月22日に顧客の環境変数・トークン・鍵を含むデータの一部が持ち出されました。

ここから得られる設計の原則は、長く有効な認証情報をCI側に置かないことです。CircleCIはジョブ実行時にOIDCトークンを発行しており、AWSやGoogle Cloudは信頼ポリシーでこれを受け入れれば、アクセスキーを保存せずに一時的な権限を渡せます。2026年10月時点のOIDCの公式ガイドは、新規の設定では$CIRCLE_OIDC_TOKEN_V3を推奨しています。V3はチェックアウト元と設定ファイルの取得元をクレームに含むため、「このリポジトリのこのブランチから動いたときだけ許可する」という絞り込みを信頼ポリシーで書けます。

複数のプロジェクトで使う認証情報は、プロジェクトの環境変数でなくコンテキストにまとめ、組織の管理者が利用条件を絞ります。絞り方はプロジェクト単位の制限と式（ブランチ名など）による制限が使え、VCSのチームで絞るセキュリティグループ制限はgithubタイプの組織だけで使えます（コンテキストの公式ガイド）。フォークからのプルリクエストにシークレットを渡す設定は、必要がない限り有効にしません。

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

判断は3つの条件で分かれます。リポジトリがGitHubだけにあり、テストが数分で終わるならGitHub Actionsで十分で、CircleCIを足す理由は薄いです（仕組みはGitHub Actionsとは？できること・使い方と最初のワークフロー、料金と上限【2026年10月】）。テストの待ち時間が開発の妨げになっているなら、CircleCIを候補にします。比べ方は実測で、同じテストスイートをGitHub ActionsとCircleCIの両方で流して、所要時間・月のクレジット費用・設定を移す手間を並べます。時間ベースの分割とジョブごとのマシンサイズで短縮できた時間が、増える費用と移行の手間を上回るなら採用します。閉域網でしか動かせない、あるいはビルド環境を細かく自作したいならJenkins（Jenkinsとは？できること・無料の範囲とインストールから使い方まで【2026年版】）かCircleCI Serverです。

乗り換えの試算には、2026年10月時点でプレビュー提供の「GitHub Actionsのワークフローファイルをパイプライン設定として使う」機能が役立ちます。.github/workflows/のファイルを書き換えずにCircleCIのマシンで実行でき、同じワークフローで所要時間と費用を比べられます。ただし対象はGitHub App連携の組織のLinuxワークフローに限られ、互換も一部です。たとえばconcurrencyは警告が出るだけで効かず、重複デプロイを防ぐ用途には使えません。secrets: inheritやプライベートなアクションも動かないので、公式の対応表で使っている機能を確かめてから試します（公式の対応範囲）。GitHub Actionsのままランナーだけ速くしたい場合は、Blacksmithとは？GitHub Actionsを速く安くするランナーの料金・移行手順【2026年10月】のような選択肢もあります。社内のCI/CDをどの製品で組むか、移行の設計から相談したい場合はDevOps・CI/CD導入支援も行っています。

2026年のAI機能：Chunkとホスト型MCPサーバー

Chunkは、不安定なテストの修正、テストが足りない箇所への追加、バグの修正などを行い、プルリクエストとして提案するCircleCIのAIエージェントです。2026年10月時点でベータ提供で、公式の説明ではベータ期間中の追加料金は無く、正式提供時に有料機能になります。ただし実行にはCircleCIのクレジットと、モデル提供元のトークンを消費します。モデルは既定がCircleCI管理のAnthropicモデルでAPIキーは不要（1日400,000トークンまで、UTC12時にリセット）です。自前のAPIキーを持ち込む場合はAnthropic・OpenAI・Amazon Bedrock（Claudeのみ）を選べます。利用にはCircleCI GitHub Appのインストールが必要です。

エディタやAIエージェントからビルドの失敗を調べるためのMCPサーバーは、https://mcp.circleci.com/v1/mcpで提供されるホスト型に移りました。以前のnpxで入れるローカル版は非推奨です。認証はOAuth2が推奨で、対応しないクライアントでは個人APIトークンを使います。

よくある質問

CircleCIは無料で使えますか？

使えます。Freeプランは月30,000クレジットと5ユーザーまでで、クレジットカードは不要です。Docker mediumなら月約3,000分、Docker smallなら約6,000分動かせます。publicリポジトリのオープンソースはLinux・Arm・Dockerで月400,000クレジットまで無料です。

CircleCIの有料プランはいくらですか？

Performanceプランは月15ドルからで、無料分の30,000クレジットに加えて25,000クレジットごとに15ドルで買い足します。5人を超えるユーザーは1人あたり月25,000クレジット（15ドル相当）です。Scaleプランは年契約の個別見積もりです。

config.ymlはどこに置き、versionは何を書きますか？

リポジトリ直下の.circleci/config.ymlに置き、1行目にversion: 2.1と書きます。GitHub App連携なら別のパスや別のリポジトリに置いた設定ファイルも指定できます。

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

Cloudでは動き続けますが推奨ではありません。新しく書くならcircleci testsuiteを使います。CircleCI Serverでは逆にcircleci tests splitが現行の方法で、tests runとtestsuiteは使えません。

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

サーバーを自分たちで運用するかどうかで決まります。Jenkinsは無償で自由度が高い代わりに、サーバー・プラグイン・エージェントの保守を自前で持ちます。CircleCIは保守を任せる代わりに実行量とユーザー数に応じて課金されます。社内ネットワークの外に出せない場合はJenkinsかCircleCI Serverです。

関連記事

• CI/CDツール比較｜主要11製品の無料枠・料金と選び方【2026年10月】
• GitHub Actionsとは？できること・使い方と最初のワークフロー、料金と上限【2026年10月】
• Jenkinsとは？できること・無料の範囲とインストールから使い方まで【2026年版】
• TerraformのCI導入ガイド｜fmt・validate・planを自動化するパイプライン設計とツールの選び方
• Datadog CI Visibilityとは？対応CI・設定手順・料金とTest Optimizationの分担