Contents
1. CircleCI 無料プランの概要と利用できる機能
CircleCI はクラウド型 CI/CD サービスで、コードがリポジトリにプッシュされるたびに自動的にビルド・テスト・デプロイを実行します。無料プランは「小規模プロジェクト」や「学習目的」に最適化されたリソースセットです。
1‑1. 無料プランで提供される主なスペック
| 項目 | 内容 |
|---|---|
| 同時実行ジョブ数 | 1 ジョブのみ |
| 月間クレジット上限 | 2,500 クレジット（約 3,000 分相当） |
| ジョブあたりの最大実行時間 | 30 分 |
| 利用可能な Executor | Linux Docker executor のみ（macOS executor は有料プラン限定） |
| キャッシュ容量 | プロジェクト単位で 10 GB まで |
| ビルドアーティファクト保存上限 | 5 GB／ジョブ |
出典: CircleCI 公式サイト「Pricing」https://circleci.com/pricing/
1‑2. 無料枠での活用シーン
- 学習・チュートリアル：1 日に数回程度のビルドならクレジット消費はほぼゼロ。
- 個人プロジェクト：Linux コンテナ上で動作するアプリケーションの CI がすべて実行可能。
- プルリクエスト検証：GitHub の PR 作成時に自動テストを走らせ、品質担保が容易になる。
ポイント: macOS 環境が必要な iOS アプリや Xcode ビルドは無料枠では利用できません。必要な場合は有料プランへのアップグレードをご検討ください。
2. 無料アカウントの作成とセキュリティ設定
この章では、公式サイトからアカウントを取得し、メール認証と二要素認証（2FA）までを実装する手順を示します。安全に CI を運用するための必須ステップです。
2‑1. アカウント作成フロー
- 公式サイト https://circleci.com/ にアクセスし、右上の「Sign Up」ボタンをクリック。
- GitHub（または Bitbucket）アカウントで OAuth 認証を行う。必要なスコープは
repoとworkflowのみです。 - 登録したメールアドレスに届く認証リンクを開き、メール認証 を完了させる。
2‑2. 二要素認証（2FA）の有効化
- ダッシュボード右上のユーザーアイコン → 「User Settings」 → 「Security」 に移動。
- 「Two‑Factor Authentication」をオンにし、認証アプリ（Google Authenticator、Authy 等）で QR コードをスキャン。
- 生成された 6 桁コードを入力して設定完了。
補足: 2FA を有効化すると、GitHub の OAuth トークンが漏洩した場合でも不正ログインを防止できます。
3. GitHub リポジトリとの連携設定
CI が自動で走るためには、CircleCI とリポジトリの接続が必要です。このセクションでは、GitHub（Bitbucket も同様）との連携手順と、Webhook の確認方法を解説します。
3‑1. リポジトリ追加手順
| 手順 | 内容 |
|---|---|
| ① | CircleCI ダッシュボード左メニューの 「Add Projects」 を選択。 |
| ② | 連携したい GitHub アカウントが表示されていることを確認し、対象リポジトリの 「Set Up Project」 ボタンをクリック。 |
| ③ | 初回セットアップ時に OAuth アプリが自動作成され、repo, workflow スコープが付与されたことを画面で確認。 |
3‑2. Webhook の自動登録と確認
- CircleCI がリポジトリへ Webhook（URL:
https://circleci.com/hooks/github） を自動で追加します。 - GitHub 側の Settings → Webhooks ページで「Recent Deliveries」欄に
pingと表示されていれば正常です。
注意点: 連携後にリポジトリのプライベート設定を変更した場合は、再度 OAuth スコープが正しく付与されているか確認してください。
4. .circleci/config.yml の基本構造と Executor の選び方
CI 定義ファイルはプロジェクト直下の .circleci/config.yml に記述します。この章では必須キー、Docker executor の設定例、無料枠で注意すべき点を具体的に示します。
4‑1. 設定ファイル全体の構成
- version: CircleCI 設定フォーマット（現在は
2.1が主流）。 - jobs: 個々のビルド単位。Docker コンテナやコマンドを指定できる。
- workflows: 複数ジョブ間の依存関係と実行順序を定義。
基本例（Linux Docker executor のみ）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
# .circleci/config.yml version: 2.1 jobs: build: docker: - image: cimg/node:lts # CircleCI が提供する公式 Node LTS イメージ steps: - checkout # ソースコード取得 - restore_cache: keys: - node-modules-{{ checksum "package-lock.json" }} - run: npm ci # 依存関係インストール - save_cache: paths: - ~/.npm key: node-modules-{{ checksum "package-lock.json" }} workflows: build_and_test: jobs: - build |
4‑2. 無料プランで使える Executor とリソースクラス
| Executor | 利用可否（無料） | 最大実行時間 | 推奨リソースクラス |
|---|---|---|---|
| Docker (Linux) | ✅ | 30 分／ジョブ | medium （CPU 2 コア、メモリ 4 GB） |
| macOS (Xcode) | ❌（有料プラン限定） | - | - |
- Docker executor はデフォルトで
smallクラスが割り当てられます。無料枠でもmediumクラスまで利用可能ですが、large以上は有料となります。 - macOS executor は高コストリソースのため、無料プランでは提供されません。iOS アプリの CI が必要な場合は Performance または Scale プランへのアップグレードが必須です。
5. サンプルパイプラインとトラブルシューティング
実際に動かすことで概念が定着します。ここでは「ビルド → テスト」の 2 段階構成サンプルを示し、よくあるエラーへの対処法も併せて解説します。
5‑1. 完全版サンプル config.yml
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
version: 2.1 jobs: build: docker: - image: cimg/node:lts steps: - checkout - restore_cache: keys: - npm-cache-{{ checksum "package-lock.json" }} - run: npm ci - save_cache: paths: - ~/.npm key: npm-cache-{{ checksum "package-lock.json" }} test: docker: - image: cimg/node:lts steps: - checkout - run: npm test workflows: ci_pipeline: jobs: - build - test: requires: - build |
実行手順
- 上記内容をリポジトリの
.circleci/config.ymlにコミット。 - GitHub にプッシュすると、CircleCI が自動で Pipeline を作成しジョブが開始されます。
- ダッシュボードの Pipelines ページで進行状況を確認でき、失敗した場合は該当ジョブをクリックして詳細ログを見ることができます。
5‑2. よくあるエラーと対処法
| エラーメッセージ | 主な原因 | 解決策 |
|---|---|---|
docker executor not found |
docker: キーのスペルミスやインデント不正 |
YAML のインデントを 2 スペースで統一し、docker: が正しく記述されているか確認 |
Cache size limit exceeded |
保存キャッシュが 10 GB を超過 | 不要なディレクトリは除外するか、キャッシュキーを細分化してサイズを抑える |
Missing required environment variable DEPLOY_TOKEN |
環境変数未設定（デプロイ時に必要） | Project Settings → Environment Variables に DEPLOY_TOKEN を追加 |
Job exceeded time limit of 30 minutes |
ビルドが長時間走り続けた | ビルドステップを分割し、persist_to_workspace / attach_workspace を活用してジョブ間で成果物を共有 |
エラーが出たら ジョブログの最上部 にある「Retry」ボタンで再実行し、同様のケースが公式ドキュメントに記載されていないか https://circleci.com/docs/ で検索してください。
6. 次のステップと有料プランへの移行指針
無料枠は 1 ジョブ・2,500 クレジット が上限ですが、プロジェクトが成長すると以下のようなニーズが出てきます。
- 同時実行ジョブ数を増やしたい → Performance プラン（同時 5 ジョブ）へ。
- macOS/Xcode ビルドが必要 → macOS executor が利用できるプランにアップグレード。
- 長時間のビッグデータ処理や大規模テスト → Scale プランでクレジット上限とリソースクラスを拡張。
まずは本記事の手順で無料環境を体験し、以下をチェックしてください。
- ビルド頻度が月 30 回以上になるか。
- macOS が必須な機能（iOS アプリ等）を追加したいか。
- 同時実行ジョブ数の増加で開発サイクルが改善できるか。
上記に該当すれば、CircleCI の Pricing ページ https://circleci.com/pricing/ からプラン比較と見積もりを取得し、プロジェクトに最適なプランへ移行しましょう。
本稿のまとめ
- 無料プランは Linux Docker executor が唯一利用可能で、月間 2,500 クレジット・30 分ジョブ上限というシンプル構成です。
- アカウント作成時に GitHub OAuth とメール認証、そして二要素認証を設定すればセキュリティは十分です。
- リポジトリ連携は Add Projects → Set Up Project の流れで完了し、Webhook が自動登録されます。
.circleci/config.ymlはversion,jobs,workflowsの３要素が必須。サンプルをそのまま貼り付ければすぐに CI が走ります。- エラーはジョブログと公式ドキュメントで対処し、必要に応じて有料プランへ段階的に移行してください。
これらの手順を踏めば、2026 年時点でも最新の CircleCI 環境でスムーズに CI/CD を導入できるはずです。ぜひご自身のプロジェクトで実践し、継続的な品質向上に役立ててください。