結論
有料プラン（Performance / Scale / Server）を使っているなら、Private Orbs を選ぶべきです。
| プラン | 選択 |
|---|---|
| Performance / Scale / Server | Private Orbs 一択 |
| Free | Custom Docker（Orbsが使えないため） |
Custom Dockerをあえて選ぶ理由は、「Freeプランである」または「他のCI/CDツールと環境を共有したい」場合のみです。
なぜ Private Orbs 一択なのか
1. Custom Dockerの役割もカバーできる
Private Orbsには executor を含めることができます。つまり、実行環境の定義もOrb内に含められるため、Custom Dockerの役割を完全にカバーできます。
# Private Orb内でexecutorを定義
executors:
default:
docker:
- image: cimg/node:18.17
environment:
NODE_ENV: production
commands:
setup:
steps:
- checkout
- run: pnpm install
jobs:
build:
executor: default
steps:
- setup
- run: pnpm build
# 利用側はシンプルに呼び出すだけ
orbs:
my-orb: my-org/my-orb@1.0.0
workflows:
main:
jobs:
- my-orb/build
2. CircleCIネイティブの管理機能
| 機能 | Private Orbs | Custom Docker |
|---|---|---|
| バージョン管理 | セマンティックバージョニング（自動） | Dockerタグ（手動管理） |
| 公開範囲制御 | CircleCI上で完結 | レジストリ側で設定 |
| 依存関係の解決 | 自動 | 自前で管理 |
| 更新の反映 | バージョン指定を変えるだけ | イメージのリビルド＆プッシュ |
3. 公式Orbsと同じ使い勝手
AWS、GCP、Slack等の公式Orbsと同じように使えるため、チームメンバーの学習コストが低いです。
orbs:
aws-cli: circleci/aws-cli@4.0.0 # 公式Orb
my-deploy: my-org/deploy@1.0.0 # Private Orb（同じ使い方）
jobs:
deploy:
executor: my-deploy/default
steps:
- aws-cli/setup
- my-deploy/deploy-to-ecs
Custom Dockerを選ぶべきケース
以下の場合のみ、Custom Dockerが適切です。
1. Freeプランを使っている
Private OrbsはFreeプランでは利用できません。Freeプランで設定や環境を再利用したい場合は、Custom Dockerが唯一の選択肢です。
2. 複数のCI/CDツールで同じ環境を使いたい
GitHub Actions、GitLab CI、Jenkins等でも同じDockerイメージを使いたい場合は、Custom Dockerが適しています。
# CircleCI
jobs:
build:
docker:
- image: my-org/my-image:1.0.0
# GitHub Actions（同じイメージを使用）
jobs:
build:
runs-on: ubuntu-latest
container: my-org/my-image:1.0.0
3. 既存のDockerイメージ資産がある
すでに本番環境やローカル開発で使っているDockerイメージがあり、それをCI/CDでも流用したい場合。
比較表
| 項目 | Private Orbs | Custom Docker |
|---|---|---|
| 対象 | CircleCI専用 | マルチCI/CD対応 |
| 含められるもの | executor + commands + jobs | 実行環境のみ |
| Freeプラン | ❌ | ✅ |
| 管理場所 | CircleCI | Docker Registry |
| 更新の手間 | バージョン番号変更のみ | リビルド＆プッシュ |
| チーム学習コスト | 低（公式Orbと同じ） | 中（Docker知識必要） |
Private Orbの作成方法
# 1. Orb の初期化
circleci orb init my-orb
# 2. 構造
my-orb/
├── src/
│ ├── commands/
│ │ └── setup.yml # 再利用可能なステップ
│ ├── jobs/
│ │ └── build.yml # 再利用可能なジョブ
│ └── executors/
│ └── default.yml # 実行環境（←Custom Dockerの代替）
└── orb.yml
# 3. Private Orb として公開
circleci orb publish my-org/my-orb@1.0.0 --private
executor の定義例
# src/executors/default.yml
description: "Node.js 18 with pnpm"
docker:
- image: cimg/node:18.17
resource_class: medium
environment:
NODE_ENV: production
これでCustom Dockerと同等の環境定義がOrb内で完結します。
まとめ
有料プラン？
├── Yes → Private Orbs 一択
│ （executor で環境定義も含められる）
│
└── No（Freeプラン）
├── CircleCIのみ使う → Custom Docker
└── 他CI/CDと共有したい → Custom Docker
有料プランを使っているなら、迷わずPrivate Orbsを選びましょう。 Custom Dockerの役割（実行環境の定義）もexecutorでカバーできるため、「CircleCIに最適化されたCustom Docker」として機能します。