結論

CircleCI(サークルシーアイ)とは、リポジトリに置いた .circleci/config.yml の内容どおりに、ビルド・テスト・デプロイを自動で動かす CI/CD のサービスです。無料の Free プランでは毎月 30,000 クレジットが付き、いちばん小さい Docker の実行環境(Small)なら最大 6,000 分ぶんにあたります(2026年11月18日時点の公式の料金ページ)。

この記事でわかること

  • パイプライン・ワークフロー・ジョブ・ステップの関係と config.yml の書き方
  • 実行環境ごとに無料枠で何分動かせるかの計算と、料金の試算
  • 壊れた config.yml を YAML として読み込んだときのエラー原文6種と直し方

2026年11月18日更新|Python 3.13・PyYAML 6.0.3 で config.yml を読み込んで確認

この記事で実際に動かしたもの:自作の config.yml(テスト→ビルド→承認→デプロイ)と壊した6例を PyYAML で読み込み、ジョブのつながりを自作のチェックで確かめました。キャッシュのキー {{ checksum "..." }} の値と、クレジットの計算も Python で出しています。

flowchart TD
    P[git push] --> PL[パイプライン]
    PL --> W[ワークフロー]
    W --> T[job: test]
    T --> B[job: build]
    B --> H[承認 hold]
    H --> D[job: deploy]

よく調べられることの答えを先にまとめます。

知りたいこと 答え 詳しい節
CircleCIとは config.yml に書いた手順を、push のたびにクラウドの実行環境で動かす CI/CD のサービス CircleCIとは
CircleCIの使い方 アカウントを作り、プロジェクトにリポジトリをつなぎ、.circleci/config.yml を置いて push CircleCIの使い方
config.ymlの書き方 version・jobs・workflows の3つが骨組み config.ymlの書き方
CircleCIの料金 Free は $0 で月 30,000 クレジット。Performance は月 $15 から CircleCIの料金とクレジット
無料で何分使える Docker Small で 6,000 分、Medium で 3,000 分、macOS で 150 分 CircleCIの料金とクレジット
Orbとは ジョブ・コマンド・実行環境をまとめた、再利用できる設定の部品 Orbとは
キャッシュとワークスペースの違い キャッシュは次の実行を速くするもの、ワークスペースは同じワークフローの後ろのジョブへ渡すもの キャッシュ・ワークスペース・アーティファクト
GitHub Actionsとの違い 設定ファイルの置き場所・課金の単位・再利用の部品の名前が違う CircleCIとGitHub Actionsの違い

確認環境:Ubuntu 24.04.5 LTS の上で、Python 3.13.18 と PyYAML 6.0.3 を使い、自作の config.yml と、わざと壊した6つの config.yml を読み込みました。ジョブの参照(requires・executor)のつながりは、公式の設定リファレンスに合わせて自作した Python のチェックで確かめています。これは CircleCI 本体の検証ではありません。CircleCI CLI は GitHub のリリースからの取得がこの環境のプロキシで拒否された(HTTP 403)ため入れておらず、circleci config validate は公式の CLI リファレンスの記載で書いています。CircleCI のサービスには接続・サインイン・連携をしていません。料金・実行環境・キャッシュ・ワークスペース・Orb・SSH での再実行は circleci.com の公式ページ、GitHub Actions の事実は docs.github.com で確かめました。キャッシュのキーとクレジットの計算は Python で実際に計算しています。図は mermaid 11.16.0 で描画を確かめています(確認日 2026年11月18日)。

本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。

(記載例)出典:株式会社RJC「CircleCIとは|使い方・料金(無料枠の分数)・config.ymlの書き方」

CircleCIとは(意味とできること)

この節では、CircleCI が何をするサービスで、何ができるのかが分かります。

CircleCI は、コードを push したときなどに、決めておいた手順(依存の取得・ビルド・テスト・デプロイ)を自動で動かす CI/CD のサービスです。手順はリポジトリの .circleci フォルダーに置く config.yml という1つの YAML ファイルに書きます。公式の用語集は「1つの config.yml が CI/CD の流れ全体を指揮する」と説明しています。

CI(継続的インテグレーション)は、変更を小さく頻繁にまとめ、そのたびに自動でビルドとテストを回すこと。CD(継続的デリバリー/デプロイ)は、テストを通ったものをいつでも出せる状態にする、または自動で出すことです。CI/CD そのものの考え方は、関連記事「CI/CDとは|GitHub Actionsで最初のパイプラインを作るまで」で扱っています。

1テストとビルドを自動で回す

push やプルリクエストのたびに、決めた実行環境で npm test などを動かし、結果を画面に残す。

2順番・並列・承認を組める

ワークフローでジョブの順番を決め、並べて動かし、デプロイの前に人の承認を挟める。

3実行環境を選べる

Docker・Linux VM・macOS・Windows・GPU・Arm から選ぶ。大きさはリソースクラスで決める。

対応するコードの置き場所は、公式の「はじめ方」のページで「GitHub・Bitbucket・GitLab・Cursor Origin のプロジェクトに対応」と書かれています(2026年11月18日時点)。自社のサーバーで動かす CircleCI Server という形もあり、公式の Server のページでは Kubernetes のクラスター(GKE・EKS など)に入れる、と説明されています。

なお、CircleCI の公式ドキュメントの日本語版は、2025年4月1日に公開を終えています(公式の変更履歴)。いまの公式ドキュメントは英語で、この記事の用語も英語の名前を併記しています。

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

この節では、CircleCI の画面と config.yml に出てくる4つの言葉が、どう入れ子になっているかが分かります。

大きい順に「パイプライン > ワークフロー > ジョブ > ステップ」です。1回の push で1つのパイプラインが動き、その中のワークフローがジョブの順番を決め、各ジョブの中でステップ(コマンド)が上から順に動きます。

  1. 1パイプライン(pipeline)設定がどこにあり、どこからコードを取るかの定義。push などで1回動く単位
  2. 2ワークフロー(workflow)ジョブの一覧と順番を決める。並列・順番・スケジュール・手動の承認を組める
  3. 3ジョブ(job)ステップの集まり。ジョブごとに別の実行環境(executor)で動く
  4. 4ステップ(step)実行するコマンドやスクリプト。checkout・run・save_cache など

公式の用語集では、ジョブは「設定の組み立てブロック」、ワークフローは「ジョブを指揮する」と書かれています。ジョブごとに実行環境が分かれるので、ジョブAで作ったファイルは、そのままではジョブBから見えません。渡すにはワークスペースを使います(後の節)。

言葉 config.yml のキー 画面で見えるもの
パイプライン ファイル全体(parameters で値を受け取れる) push ごとの1行
ワークフロー workflows: ジョブの並びと矢印
ジョブ jobs: 成功・失敗の色、所要時間
ステップ steps: 開くと出るコマンドごとのログ

実行環境(Docker・Linux VM・macOS・Windows)とリソースクラス

この節では、ジョブを動かす場所の種類と、CPU・メモリの大きさの決め方が分かります。

実行環境(executor)は、config.yml のジョブに docker・machine・macos のどれかを書いて選びます。Windows は Windows の Orb か machine のイメージで、GPU と Arm は machine にリソースクラスを合わせて指定します。

実行環境 キー 公式の例 向く用途
Docker docker cimg/base:stable 多くのビルド・テスト。起動が軽い
Linux VM machine ubuntu-2404:current Docker のコマンドを直接使う、OS ごと要る
macOS macos xcode: 27.1.0 iOS・macOS アプリのビルド
Windows Orb か machine win/server-2022 .NET・Windows 向けのビルド
GPU machine linux-cuda-12:default 機械学習のテスト
Arm VM machine resource_class: arm.medium Arm 向けのビルド

公式の実行環境のページにある書き方を、主な3つだけ並べます。

# Docker
jobs:
  build:
    docker:
      - image: cimg/base:stable

# Linux VM
jobs:
  build:
    machine:
      image: ubuntu-2404:current

# macOS
jobs:
  build:
    macos:
      xcode: 27.1.0

CPU とメモリの大きさは resource_class で決めます。公式の設定リファレンスには「リソースクラスを指定しないと、変わることのある既定の値が使われる」と書かれているので、クレジットの消費をそろえたいときは明示します。Docker の cimg/ で始まるイメージは CircleCI が用意した「コンビニエンスイメージ」で、CircleCI/ で始まる以前のイメージは非推奨と書かれています。Docker のコマンドそのものは、関連記事「Dockerコマンド早見表|よく使う操作とつながらない時の対処」で扱っています。

CircleCIの使い方(はじめ方の流れ)

この節では、アカウントを作ってから最初のパイプラインが動くまでの流れが分かります。

流れは「アカウントを作る → 組織とプロジェクトを作ってリポジトリをつなぐ → config.yml を置いて push」です。ここでは公式の「はじめ方」のページの流れを紹介します。この記事の確認では、サインインや連携は行っていません。

1

アカウントを作る

公式の Sign Up のページで、メールアドレスとパスワードで作るか、GitHub・Bitbucket のアカウントで作る。GitLab はメールアドレスで作ってから、組織の設定でつなぐ、と公式に書かれている。

公式の説明どおり

2

組織とプロジェクトを作る

組織に入るか新しく作り、プロジェクトを作ってリポジトリとつなぐ。GitHub OAuth と Bitbucket Cloud ではプロジェクトがリポジトリと同じ名前で結びつき、GitHub App・GitLab では独立したプロジェクトにコードをつなぐ形になる。

連携の方式で形が違う

3

config.yml を置く

リポジトリの一番上に .circleci/config.yml を作る。最初は次の節の最小の例から始める。

手元で書ける

4

push して結果を見る

push するとパイプラインが動き、ワークフロー・ジョブ・ステップの順に結果が出る。失敗したステップを開くとログが読める。

画面で確かめる

公式の「はじめ方」のページには、CLI の circleci onboard(リポジトリを調べて設定を作り、サインアップまで進める)や circleci auth signup で始める方法も載っています。どちらもブラウザが開く、と書かれています。

config.ymlの書き方(最小の例と各行の意味)

この節では、いちばん小さい config.yml の形と、各行が何をしているかが分かります。

config.yml の骨組みは version・jobs・workflows の3つです。次は公式の Hello World のページに載っている例そのままです。

version: 2.1

jobs:
  hello-job:
    docker:
      - image: cimg/node:17.2.0 # the primary container, where your job's commands are run
    steps:
      - checkout # check out the code in the project directory
      - run: echo "hello world" # run the `echo` command

workflows:
  my-workflow:
    jobs:
      - hello-job
行 意味
version: 2.1 設定の版。公式のリファレンスで使える値は 2・2.0・2.1
jobs: と hello-job: ジョブの一覧と、ジョブの名前
docker: と - image: Docker の実行環境と、コマンドが動く主のコンテナ
steps: ジョブの中で上から順に動く手順
- checkout プロジェクトのコードを取り出す
- run: ... シェルのコマンドを動かす
workflows: の中の jobs: このワークフローで動かすジョブを並べる

公式の設定リファレンスでは、トップレベルのキーとして version・setup・orbs・commands・parameters・executors・jobs・workflows などが並んでいます。ジョブの中の working_directory の既定は ~/project(「project」は文字どおりの名前)、Linux の既定のシェルは /bin/bash があれば /bin/bash -eo pipefail です。pipefail が付くので、パイプの途中のコマンドが失敗してもステップは失敗になります。

YAML の書き方そのもの(インデント・クォート・複数行)は、関連記事「YAMLの書き方|構文一覧とパース結果、落とし穴10例を実測」で扱っています。

実用的なconfig.yml(テスト→ビルド→承認→デプロイ)

この節では、キャッシュ・テスト結果・ワークスペース・承認を入れた、そのまま土台にできる config.yml が分かります。

次の config.yml は、テストを4並列で動かし、ビルドの成果物をワークスペースで渡し、人の承認のあとにデプロイのジョブへ進む形です。実行環境は executors に1度だけ書いて、3つのジョブで使い回しています。

version: 2.1

executors:
  node-exec:
    docker:
      - image: cimg/node:lts
    resource_class: medium

jobs:
  test:
    executor: node-exec
    parallelism: 4
    steps:
      - checkout
      - restore_cache:
          keys:
            - npm-v1-{{ checksum "package-lock.json" }}
            - npm-v1-
      - run: npm ci
      - save_cache:
          key: npm-v1-{{ checksum "package-lock.json" }}
          paths:
            - ~/.npm
      - run: npm test
      - store_test_results:
          path: reports
  build:
    executor: node-exec
    steps:
      - checkout
      - run: npm ci && npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist
  deploy:
    executor: node-exec
    steps:
      - attach_workspace:
          at: .
      - run: ls dist

workflows:
  build-test-deploy:
    jobs:
      - test
      - build:
          requires:
            - test
      - hold:
          type: approval
          requires:
            - build
      - deploy:
          requires:
            - hold
  • restore_cache の keys は上から順に探します。1つ目が lock ファイルの中身と一致するキー、2つ目はその前半だけの「代わりに使う」キーです。
  • type: approval のジョブ(ここでは hold)は、画面で承認されるまで後ろのジョブを止めます。公式のリファレンスでは、承認のジョブは jobs: に定義したジョブと同じ名前にしない、と書かれています。
  • requires は、前のジョブが終わってから動かすための指定です。公式のリファレンスでは、success・failed などの状態を指定できるとも書かれています。
  • ブランチやタグで動かすジョブを絞る filters の branches・tags は、公式のリファレンスで「非推奨。式によるジョブフィルターを使う」と書かれています(2026年11月18日時点)。

config.ymlの検証(読み込みの結果とエラー原文)

この節では、config.yml を push する前に手元で間違いを見つける方法と、壊したときに実際に出たエラーの原文が分かります。

まず YAML として読めるかを確かめ、次にジョブの名前のつながりを確かめます。前の節の config.yml を、自作のチェック(PyYAML で読み込み、requires と executor の参照先が定義されているかを見る)にかけた結果です。

$ python3 check_cfg.py .circleci/config.yml
OK: jobs=['test', 'build', 'deploy'] workflows=['build-test-deploy']

次に、よくある間違いを6つ作って読み込みました。上の3つは YAML の読み込みそのもの(PyYAML)のエラー、下の3つは自作のチェックが出したものです。

インデントにタブが入っている

YAMLの読み込みに失敗:
while scanning for the next token
found character '\t' that cannot start any token
  in "bad/tab.yml", line 14, column 1

インデントが1文字ずれている

YAMLの読み込みに失敗:
while parsing a block mapping
  in "bad/indent.yml", line 11, column 5
expected <block end>, but found '<block sequence start>'
  in "bad/indent.yml", line 24, column 6

run の中に「: 」がある

- run: echo "dist: ok" && ls dist と書いた行です。echo から始まる値の途中に「コロンと空白」があるため、YAML は「ここで新しいキーが始まった」と読みます。

YAMLの読み込みに失敗:
mapping values are not allowed here
  in "bad/colon.yml", line 41, column 24

値全体をクォートで囲む(- run: 'echo "dist: ok" && ls dist')か、run: | の複数行にすると、どちらも読み込みが通りました。複数行にした値は 'echo "dist: ok"\nls dist\n' として読まれ、1行ずつコマンドになります。

requires の名前の綴りが違う・version が違う・実行環境が無い

$ python3 check_cfg.py bad/requires.yml
NG workflow build-test-deploy: build の requires tests がこの workflow に無い
$ python3 check_cfg.py bad/version.yml
NG version が '3'(2 / 2.0 / 2.1 のどれか)
$ python3 check_cfg.py bad/noexec.yml
NG job deploy: 実行環境(docker/machine/macos/executor)が無い

CircleCI 本体では、公式の CLI の circleci config validate で検証できます。公式の CLI リファレンスでは、既定で .circleci/config.yml を読み、--json で JSON の出力、--org で非公開の Orb の解決先を指定でき、「API トークンが無くても公開の Orb だけは解決できる」と書かれています。circleci config process は Orb などを展開した後の設定を出し、circleci config pack は分けて書いた設定を1つにまとめます。CLI の入れ方は公式に Homebrew(brew install circleci)・WinGet・apt・rpm・Snap・GitHub のリリースが並んでいます。この記事の環境では CLI を入れられなかったので、CLI の出力は載せていません。

  • 1インデントは半角スペースだけタブは「found character '\t' that cannot start any token」になった
  • 2コロンを含むコマンドはクォートか「|」そのままだと「mapping values are not allowed here」
  • 3requires の名前は jobs の名前と一字一句同じtest と tests の違いは YAML では見つからない
  • 4各ジョブに実行環境を書くdocker・machine・macos・executor のどれか

キャッシュ・ワークスペース・アーティファクトの違い

この節では、ジョブの間や実行の間でファイルを残す3つの仕組みの使い分けと、キャッシュのキーの決まり方が分かります。

キャッシュは「次の実行を速くするための置き場」、ワークスペースは「同じワークフローの後ろのジョブに渡す置き場」、アーティファクトは「ワークフローが終わった後も取り出せる成果物の置き場」です。

仕組み 入れる・出すステップ 届く範囲 保存期間の既定と上限
キャッシュ save_cache・restore_cache プロジェクト全体(別のブランチの実行でも使われる) 15日
ワークスペース persist_to_workspace・attach_workspace 同じワークフローの、後ろにあるジョブだけ 15日
アーティファクト store_artifacts 画面と API から取り出せる 30日

保存期間は公式の「データの保存」のページの記載です(2026年11月18日時点)。ワークスペースは足すことしかできず、同時に動くジョブが同じファイル名を入れると、取り出すときにエラーになる、と公式に書かれています。

キャッシュのキー(checksum)を手元で再現する

公式のキャッシュのページでは、{{ checksum "filename" }} は「ファイルの中身の SHA256 ハッシュを Base64 にしたもの」と説明されています。同じ計算を Python で行い、lock ファイルの版を1文字だけ変えたときのキーを比べました。

import hashlib, base64
def checksum(b): return base64.b64encode(hashlib.sha256(b).digest()).decode()
print('npm-v1-' + checksum(lock1))   # 1.3.0 の lock
print('npm-v1-' + checksum(lock2))   # 1.3.1 に変えた lock
lock1 key: npm-v1-aLQRnSNSh5EilarJAncUmfp1SHXF15wpNTcu0jKDKvc=
lock2 key: npm-v1-ETZBlhtPKZC13zqY31ZR0sjbsTbG8/euEy60Wjkw9do=

1文字の違いでキーがまるごと変わるので、依存が変わったときだけ新しいキャッシュができます。さらに、公式の「キーを上から順に、前方一致で探し、一致したうちで新しいものを使う」という決まりを Python で再現し、lock を変えた後にどのキャッシュが戻るかを見ました。

want npm-v1-aLQRnSNSh5Eil... -> matched by 'npm-v1-aLQRnSNSh5Eil...' restored npm-v1-aLQRnSNSh5Eil... exact
want npm-v1-ETZBlhtPKZC13... -> matched by 'npm-v1-' restored npm-v1-aLQRnSNSh5Eil... partial

lock を変えた2回目は、1つ目のキーが一致せず、2つ目の npm-v1- の前方一致で前回のキャッシュが戻りました(partial)。公式はこれを「一部の復元」と呼び、戻った中身が今の依存と違うことがある、と書いています。npm ci のように lock から入れ直すコマンドを後ろに置くと、差分だけ取り直せます。

キャッシュのキーの決め方

やってはいけない{{ epoch }}・{{ .BuildNum }}・{{ .Revision }} をキーに入れる。実行や commit のたびに新しいキャッシュができ、前のものを使えない
→
代わりに{{ checksum "package-lock.json" }} のように lock ファイルの中身でキーを作る。OS に依存する物は {{ arch }} も足す

公式の説明:キャッシュは書いた後に上書きできない(同じキーなら前のものを使う)

GitHub Actions のキャッシュのキーの考え方は、関連記事「GitHub Actionsのキャッシュとmatrix|コピペ用YAMLとキー設計」で扱っています。

Orbとは(使い方と注意)

この節では、Orb が何で、config.yml にどう書き、何に気をつけるかが分かります。

Orb は、ジョブ・コマンド・実行環境をまとめた、引数を渡せる再利用の部品です。公式の Orb のページでは「パラメーター化できる設定の、再利用できるパッケージ」と説明されています。

version: 2.1

orbs:
  node: circleci/node@x.y.z   # x.y.z は Orb のページで今の版を確かめて書く

jobs:
  test:
    docker:
      - image: cimg/node:lts
    steps:
      - checkout
      - node/install-packages   # Orb の中のコマンドを「名前/要素」で呼ぶ
      - run: npm test
  • 書き方は orbs: に「名前: 名前空間/Orb名@版」。呼ぶときは node/install-packages のように「付けた名前/要素」です。公式の例はどれも version: 2.1 で書かれています。
  • 公開の Orb は Orb のレジストリ(circleci.com/developer/orbs)で探します。版の番号はそこで確かめて書きます。
  • Orb の種類は Certified(CircleCI が書いてテストしたもの)・Partner(技術パートナーが書いたもの)・Community(コミュニティが書いたもの)です。公式の説明では、Partner と Community の Orb を使うには、組織の管理者がセキュリティの設定で許可する必要があります。

Orb の中身は他の人が書いた設定なので、使う前に Orb のページでソースと版を確かめ、版を固定して書くと、知らないうちに中身が変わることを防げます。

CircleCIの料金とクレジット(無料枠で何分使えるか)

この節では、プランごとの料金と、クレジットから実際に何分動かせるかの計算が分かります。

CircleCI の料金は「クレジット」で数えます。ジョブは、実行環境とリソースクラスごとに決まった「1分あたりのクレジット」を使います。次は公式の料金ページの記載です(2026年11月18日時点)。

項目 Free Performance Scale
料金 $0/月 $15/月から 個別(年払い)
含まれるクレジット 30,000/月 30,000/月、追加は 25,000 ごとに $15 個別
含まれる利用者 5 5 個別
同時実行(Docker・Linux VM など) 30 80 上限なし
同時実行(macOS) 1 15 個別
ストレージ 2 GB 2 GB 200 GB

料金ページには、Free のクレジットは毎月消えて繰り越さないこと、オープンソースのプロジェクトは Linux・Arm・Docker で月 400,000 クレジットまで使えることも書かれています。自社のサーバーで動かす CircleCI Server は、公式のページでは価格が載っておらず、営業への問い合わせになっています。

無料の 30,000 クレジットで何分動かせるか(計算)

公式の価格表の「1分あたりのクレジット」で 30,000 を割りました。

Docker small              5 credits/min -> Free 30,000 credits =  6,000 min
Docker medium            10 credits/min -> Free 30,000 credits =  3,000 min
Docker large             20 credits/min -> Free 30,000 credits =  1,500 min
Linux VM medium          10 credits/min -> Free 30,000 credits =  3,000 min
Arm Docker medium        13 credits/min -> Free 30,000 credits =  2,307 min
Windows VM medium        40 credits/min -> Free 30,000 credits =    750 min
macOS M4 Pro Medium     200 credits/min -> Free 30,000 credits =    150 min
6,000分Docker Small(1 vCPU・2 GB)5 クレジット/分
3,000分Docker Medium(2 vCPU・4 GB)10 クレジット/分
150分macOS M4 Pro Medium200 クレジット/分

同じ 30,000 クレジットでも、macOS は Docker Small の40分の1の時間しか動かせません。iOS のビルドを含むプロジェクトは、macOS のジョブを本当に要るブランチだけに絞ると、クレジットが長持ちします。

月の料金の試算(Performance)

1回8分のジョブを、月22日動かすとして計算しました。Performance の 1 クレジットは $15 ÷ 25,000 = $0.0006 です。

USD per credit 0.0006
20 runs/day x22 days x8min Docker medium: 35,200 credits, over 5,200 -> 1 pack(s) $15
40 runs/day x22 days x8min Docker medium: 70,400 credits, over 40,400 -> 2 pack(s) $30
20 runs/day x22 days x8min Docker large: 70,400 credits, over 40,400 -> 2 pack(s) $30

1日20回・Docker Medium なら月 35,200 クレジットで、含まれる 30,000 を 5,200 超えるので、追加の 25,000 クレジット($15)が1つ要る計算です。リソースクラスを Large にすると、回数を倍にしたのと同じクレジットになりました。実際の請求は利用者の数や追加の機能(Docker Layer Caching は1ジョブ 200 クレジットなど)でも変わるので、最新の料金ページで確かめます。

並列実行(parallelism)の時間とクレジット

parallelism は、1つのジョブを複数の実行環境に分けて動かすキーです。20分かかるテストを分けたときを、各コンテナの準備に1分かかると仮定して計算しました(1分は仮定の値です)。

parallelism 1: wall 21.0 min, credits 210 (medium)
parallelism 2: wall 11.0 min, credits 220 (medium)
parallelism 4: wall 6.0 min, credits 240 (medium)
parallelism 8: wall 3.5 min, credits 280 (medium)

待ち時間は 21.0分 → 3.5分まで縮みますが、クレジットは 210 → 280 と増えます。並列にするほど、準備の時間が数のぶんだけ掛かるためです。待ち時間を縮めたいジョブだけ並列にするのが、クレジットとの釣り合いの取り方です。

CircleCIとGitHub Actionsの違い

この節では、CircleCI と GitHub Actions の違いを、公式の記載で並べて分かります。

どちらも YAML で CI/CD を書くサービスで、ジョブ・ワークフローという言葉も共通です。違いは、設定ファイルの置き場所・課金の数え方・再利用の部品の名前・対応するコードの置き場所です。どちらが上ということではなく、使っているリポジトリや実行環境で選びます。

観点 CircleCI GitHub Actions
設定ファイル .circleci/config.yml の1つ .github/workflows に複数置ける
実行環境の指定 docker・machine・macos(executor) runs-on(コンテナは container)
再利用の部品 Orb(ジョブ・コマンド・実行環境を含める) アクション(uses: で呼ぶ)
ジョブの順番 workflows: の中の requires ジョブの中の needs
失敗時だけ動かす when: on_fail if: failure()
課金の数え方 クレジット(Free は月 30,000) 金額(GitHub Free は月 $12 ぶん、公開リポジトリの標準ランナーは無料)
対応するコードの置き場所 GitHub・Bitbucket・GitLab など GitHub のリポジトリ

CircleCI の「GitHub からの移行」の公式ページでは、ジョブの依存は CircleCI では別のセクション(workflows)で決めること、if: failure() と if: always() は when: on_fail と when: always にあたること、services: は docker: の2つ目以降のイメージにあたることが説明されています。GitHub Actions の料金は docs.github.com の課金のページの記載で、含まれる量を分ではなく金額で示している、と書かれています(2026年11月18日時点)。

CircleCI が合いやすい

GitHub 以外(Bitbucket・GitLab)のリポジトリも同じ仕組みで回したい

リソースクラスで CPU・メモリを細かく選びたい

macOS・GPU・Arm の実行環境をまとめて使いたい

GitHub Actions が合いやすい

リポジトリもプルリクエストも GitHub で完結している

目的ごとにワークフローのファイルを分けたい

公開リポジトリを標準のランナーで動かしたい

GitHub Actions でワークフローを部品にする方法は、関連記事「GitHub Actions再利用可能ワークフロー|compositeとの違い」で扱っています。

よくあるエラー・つまずき(症状表)

この節では、CircleCI で起きやすいつまずきを、症状から原因と直し方まで引けます。

症状 原因 確かめ方・直し方
found character '\t' that cannot start any token インデントにタブ エディターでタブを半角スペースに置き換える
mapping values are not allowed here 値の途中に「: 」 値をクォートで囲むか run: | にする
expected <block end>, but found '<block sequence start>' インデントのずれ エラーの行と、その上の同じ深さの行の桁をそろえる
後ろのジョブが動かない requires の名前違い、または承認待ち ジョブ名を見比べる。type: approval なら画面で承認
前のジョブのファイルが無い ジョブごとに実行環境が別 persist_to_workspace と attach_workspace で渡す
キャッシュが毎回作り直される キーに {{ epoch }} などの毎回変わる値 lock ファイルの checksum でキーを作る
Docker のコマンドが使えない Docker の実行環境で、Docker を使う準備のステップが無い setup_remote_docker を足すか、machine を使う
Partner・Community の Orb が使えない 組織で許可されていない 組織の管理者がセキュリティの設定で許可する
クレジットが早く減る 大きいリソースクラス・macOS・並列の数 resource_class を明示し、並列を要るジョブに絞る

setup_remote_docker は、公式のリファレンスで「Docker のコマンドを動かせるようにする。machine とは一緒に使えない」と書かれています。失敗の原因が画面のログで分からないときは、ジョブの「Rerun」のメニューから「Rerun job with SSH」を選ぶと、SSH でつないで中を調べられます。公式のページでは、つないだ後のセッションは Free プランで1時間、ほかのプランで2時間と書かれています(2026年11月18日時点)。

判断表(CircleCIを使うか・どの実行環境にするか)

この節では、自分の状況で CircleCI を選ぶか、どの実行環境とプランにするかを決められます。

状況 選ぶもの 理由
個人や小さなチームで、まず試す Free・Docker Small か Medium 月 3,000〜6,000 分ぶん動かせる
Docker のイメージをビルドしたい setup_remote_docker か machine 公式のリファレンスで「Docker のコマンドを動かせるようにする」ステップとされている
iOS・macOS のアプリをビルドしたい macos Free でも使えるが、同時実行は1・1分 200 クレジット
Free のクレジットが毎月足りない Performance 25,000 クレジットごとに $15 で足せる
コードを社外に出せない CircleCI Server か、セルフホストのランナー 自社の Kubernetes や自社のマシンで動かす
GitHub だけで完結している GitHub Actions と見比べる 設定の置き場所・課金の数え方が違う
テストの待ち時間が長い parallelism 待ち時間は縮むが、クレジットは増える

自社のサーバーで CI を動かす別の道としては Jenkins もあります。CircleCI Server は GitHub Enterprise Cloud と GitHub Enterprise Server だけに対応する、と公式の Server のページに書かれているので、使っているコードの置き場所と合わせて選びます。

よくある質問

この節では、CircleCI について検索されることの多い疑問に、短く答えます。

Q. CircleCI は無料で使えますか?
A. 使えます。Free プランは $0 で、毎月 30,000 クレジット、利用者5人までが含まれます(2026年11月18日時点の公式の料金ページ)。

Q. CircleCI の読み方は?
A. 「サークルシーアイ」です。CI は Continuous Integration(継続的インテグレーション)の略です。

Q. 無料のクレジットは翌月に繰り越せますか?
A. 公式の料金ページでは、Free のクレジットは毎月消えて繰り越さない、と書かれています。

Q. config.yml はどこに置きますか?
A. リポジトリの一番上の .circleci フォルダーに config.yml として置きます。

Q. version は 2.1 と 2.0 のどちらにしますか?
A. Orb・executors・commands などを使う公式の例はどれも version: 2.1 です。新しく書くなら 2.1 にしておくと、公式の例をそのまま使えます。

Q. push する前に config.yml の間違いを見つけられますか?
A. 公式の CLI の circleci config validate で検証できます。YAML として読めるかだけなら、PyYAML などで読み込むと、タブやインデントのずれをエラーの行番号つきで見つけられました。

Q. キャッシュはどれくらい残りますか?
A. 公式の説明では、既定で15日で、15日が上限です。ジョブごとに retention で 1d〜15d に短くできます。

Q. ジョブの間でファイルを渡すには?
A. 前のジョブで persist_to_workspace、後ろのジョブで attach_workspace を使います。後ろのジョブに見えるのは、ワークフローで前にあるジョブが入れたものだけです。

Q. GitHub Actions から移ると、何を書き直しますか?
A. 公式の移行ページの順では、ジョブ・ステップ・ワークフロー、ジョブの依存、アクションを Orb へ、キャッシュ・ワークスペース・並列の順です。

Q. CircleCI のドキュメントに日本語版はありますか?
A. 公式の変更履歴によると、日本語版の公開は 2025年4月1日に終わり、いまは英語のページだけです。

Q. macOS のビルドは無料プランでできますか?
A. 料金ページでは Free でも macOS の同時実行は1と書かれています。M4 Pro Medium は1分 200 クレジットなので、30,000 クレジットで150分ぶんです。

まとめ

この節では、記事の要点を5つにまとめます。

  • CircleCI は、.circleci/config.yml に書いた手順を自動で動かす CI/CD のサービスで、パイプライン > ワークフロー > ジョブ > ステップの入れ子で動く。
  • config.yml の骨組みは version・jobs・workflows。実行環境は docker・machine・macos で選び、大きさは resource_class で明示する。
  • Free は月 30,000 クレジット。Docker Small で 6,000 分、Medium で 3,000 分、macOS で 150 分ぶんの計算になる(2026年11月18日時点)。
  • キャッシュのキーは lock ファイルの checksum で作る。1文字の違いでキーが変わり、2つ目の前方一致のキーで前のキャッシュを使い回せた。
  • push の前に YAML として読み込むと、タブ・インデント・「: 」の間違いを行番号つきで見つけられる。ジョブ名のつながりは CLI の validate か、名前の照合で確かめる。

参考・出典

確認日はいずれも 2026年11月18日です。

  • CircleCI「Concepts」:https://circleci.com/docs/reference/concepts/
  • CircleCI「Configuration reference」:https://circleci.com/docs/reference/configuration-reference/
  • CircleCI「Hello world」:https://circleci.com/docs/guides/getting-started/hello-world/
  • CircleCI「First steps」:https://circleci.com/docs/guides/getting-started/first-steps/
  • CircleCI「Execution environments overview」:https://circleci.com/docs/guides/execute/executor-intro/
  • CircleCI「Caching dependencies」:https://circleci.com/docs/guides/optimize/caching/
  • CircleCI「Persisting data overview」:https://circleci.com/docs/guides/optimize/persist-data/
  • CircleCI「Using workspaces to share data between jobs」:https://circleci.com/docs/guides/orchestrate/workspaces/
  • CircleCI「Orbs overview」:https://circleci.com/docs/orbs/use/orb-intro/
  • CircleCI「Debug with SSH」:https://circleci.com/docs/guides/execute/ssh-access-jobs/
  • CircleCI「Migrating from GitHub Actions」:https://circleci.com/docs/guides/migrate/migrating-from-github/
  • CircleCI「CircleCI CLI」:https://circleci.com/docs/guides/toolkit/circleci-cli/
  • CircleCI CLI「Reference」:https://cli.circleci.com/reference/
  • CircleCI「Pricing」:https://circleci.com/pricing/
  • CircleCI「Price list」:https://circleci.com/pricing/price-list/
  • CircleCI「CircleCI Server」:https://circleci.com/pricing/server/
  • CircleCI Changelog「Japanese documentation pages to be discontinued」:https://circleci.com/changelog/japanese-documentation-pages-to-be-discontinued
  • GitHub Docs「Workflows」:https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows
  • GitHub Docs「Workflow syntax for GitHub Actions」:https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
  • GitHub Docs「GitHub Actions billing」:https://docs.github.com/en/billing/concepts/product-billing/github-actions

本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。

(記載例)出典:株式会社RJC「CircleCIとは|使い方・料金(無料枠の分数)・config.ymlの書き方」

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。

WE ARE HIRING

RJCで一緒に開発しながら、
成長を楽しみませんか?

RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!

  • 127日年間休日
  • 12時間平均残業時間
  • 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!

ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。

ABOUT RJC RJCがどんな会社か知る 考え方、研修、働き方、福利厚生、社員の前職まで。RJCのことが丸わかり! RJC丸わかりページへ JOB DESCRIPTION 仕事内容・待遇を見てみる 仕事内容、給与・待遇、選考の流れ。経験者も未経験も!応募前に知りたいこと、まとめました! 募集要項を見る ENTRY エントリーする エントリーは1〜2分・履歴書不要です。まずは話を聞いてみたい、という方でも歓迎です! エントリーフォームへ

成長のヒミツ、 ぜんぶ丸わかり