CircleCI から GitHub Actions への移行: ステップごとの手順
最終更新
CircleCIからGitHub Actionsへの移行は、大部分が翻訳作業になります。ジョブはジョブのまま残り、needsがワークフローに、オーブがMarketplaceのアクションに、save_cacheがactions/cacheになります。小規模なパイプラインであれば半日程度で移行できます。難しいのは、シークレット、コンテキスト、そしてresource_classやテストの分割など、CircleCI固有の機能に依存している部分です。このガイドでは、対応関係、実際の移行例、自動インポーター、そしてダウンタイムを避けるための切り替え計画を扱います。
製品レベルの比較については、CircleCI vs GitHub ActionsとCircleCIの代替サービスをご覧ください。
概念の対応関係
| CircleCI | GitHub Actions |
|---|---|
.circleci/config.yml | .github/workflows/*.yml(ワークフローごとに1ファイル) |
requiresを使ったworkflows: | jobs.<id>.needs |
jobs: | jobs: |
docker: / machine: エグゼキューター | runs-on:、ジョブ用のイメージを使う場合はcontainer:を併用 |
2つ目以降のdocker:イメージ | services: |
resource_class | ランナーラベル(例:より大きなランナーやセルフホストランナーのラベル) |
steps: - run | steps: - run |
checkout | actions/checkout |
save_cache / restore_cache | actions/cache、またはsetup-*アクションのcache: |
persist_to_workspace / attach_workspace | actions/upload-artifact / actions/download-artifact |
store_artifacts | actions/upload-artifact |
store_test_results | テストレポーターアクション、またはJUnitファイルのupload-artifact |
parallelism: N + テスト分割 | strategy.matrix。テストシャーディングをご覧ください |
| オーブ | Marketplaceアクション、コンポジットアクション、再利用可能なワークフロー |
| コンテキスト | 環境、組織のシークレットと変数 |
| プロジェクトの環境変数 | リポジトリのシークレットと変数 |
filters: branches | on.push.branches / if: 条件 |
スケジュール実行のワークフロー(triggers: schedule) | on.schedule。cronスケジュールをご覧ください |
when: / unless: | if: 式 |
実際のパイプラインの比較
CircleCIの場合。Nodeアプリ とPostgresを使い、ビルドとテストを行ったうえでmainからデプロイします:
# .circleci/config.yml
version: 2.1
orbs:
node: circleci/node@5
jobs:
test:
docker:
- image: cimg/node:22.11
- image: cimg/postgres:16.4
environment:
POSTGRES_PASSWORD: postgres
resource_class: large
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:
command: |
TESTS=$(circleci tests glob "test/**/*.test.js" | circleci tests split --split-by=timings)
npm test -- $TESTS
environment:
DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
- store_test_results:
path: reports
deploy:
docker:
- image: cimg/node:22.11
steps:
- checkout
- run: ./scripts/deploy.sh
workflows:
ci:
jobs:
- test
- deploy:
requires: [test]
context: production
filters:
branches:
only: main
GitHub Actionsでの同等の例:
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest # or [self-hosted, Linux, compiler-ci]
strategy:
fail-fast: false
matrix:
shard: [1, 2, 3, 4]
services:
postgres:
image: postgres:16.4
env:
POSTGRES_PASSWORD: postgres
ports: ["5432:5432"]
options: >-
--health-cmd "pg_isready -U postgres"
--health-interval 5s --health-retries 10
env:
DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx jest --shard=${{ matrix.shard }}/4 --ci --reporters=default --reporters=jest-junit
- uses: actions/upload-artifact@v4
if: always()
with:
name: test-results-${{ matrix.shard }}
path: reports
deploy:
needs: test
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v6
- run: ./scripts/deploy.sh
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
変更点とその理由:
- プライマリのDockerイメージは、ランナー自体に置き換わります。
cimg/nodeの代わりにsetup-nodeを使うか、container:でイメージを維持してください。 - 2つ目以降のイメージは
services:になります。ジョブをランナー上で直接実行する場合、サービスはポートマッピングを通じてlocalhostから接続でき、ジョブ自体がcontainer:を使う場合はサービス名で接続します。テストがPostgresの準備完了前に始まらないよう、ヘルスチェックを追加してください。 parallelism: 4とcircleci tests splitの組み合わせは、マトリクスに置き換わります。CircleCIは記録された実行時間をもとに分割しますが、Jestの組み込みの--shardはファイルの順序で分割するため、実行時間を考慮しません。時間の均等な配分が重要な場合は、テストシャーディングをご覧ください。- コンテキスト
productionはenvironment: productionになります。これには承認を必須にしたり、シークレットの適用範囲を限定したりすることもできます。
シークレットと環境変数
CircleCIのプロジェクト変数は、リポジトリのシークレットになります。複数のプロジェクトで共有しているコンテキストは、組織のシークレット(リポジトリ単位で制限)または環境シークレットになります。CircleCIのUIからシークレットの値を読み出すことはできないため、最初に保存していた場所から書き出しておく必要があります。早めに計画してください。機密性のない値はリポジトリまたは組織の変数に入れ、${{ vars.NAME }}として参照します。
クラウドへのアクセスには、保存済みのキーよりも有効期間の短い認証情報の利用をおすすめします。AWSでのGitHub Actions OIDCとGitHub Actionsのセキュリティ対策をご覧ください。フォークから起動されたワークフローには、デフォルトではシークレットは渡されません。
キャッシュとアーティファクト
restore_cache にキーのリストを指定する処理は、key と restore-keys にそのまま対応します。多くの設定は、setup-node、setup-python、setup-go などで cache: を指定するだけに簡略化できます。エコシステムごとのガイドとして、npm、pip、Gradle、Go を、一般的な内容はキャッシュのガイドを参照してください。リポジトリのキャッシュ上限は 10 GB です。詳しくはキャッシュの上限をご確認ください。
persist_to_workspace の代わりに、あるジョブでファイルをアップロードし、次のジョブでダウンロードしてください。
- uses: actions/upload-artifact@v4
with: { name: build, path: dist }
# in the next job
- uses: actions/download-artifact@v4
with: { name: build }
アーティファクトは実行ごとに保存され、保持期間は設定できます。
自動変換:GitHub Actions Importer
GitHub は、CircleCI、Jenkins、GitLab CI、Azure DevOps、Bamboo、Bitbucket Pipelines、Travis CI に対応した gh 拡張機能として Importer を提供しています(GitHub のドキュメントによる、2026 年 10 月時点の確認)。Docker と GitHub CLI が必要です。
gh extension install github/gh-actions-importer
gh actions-importer configure # sets up tokens for GitHub and CircleCI
gh actions-importer audit circle-ci --output-dir audit
gh actions-importer dry-run circle-ci --output-dir out ...
ドキュメントに記載されたコマンドは、audit(パイプラインを分析)、forecast(過去の実行から Actions の利用量を見積もり)、dry-run(変換したワークフローをローカルに書き出し)、migrate(プルリクエストを作成)です。まず audit を実行してください。どの構文が変換でき、どれに手作業が必要かがわかるため、現実的な計画を立てられます。出力は下書きとして扱ってください。Orb やカスタムコマンドは手作業での変換が必要になることが多く、変換後の YAML は冗長になりがちです。正確なフラグはお使いのバージョンの最新の Importer ドキュメントでご確認ください。
切り替え計画
- Importer で監査し、Orb、コンテキスト、スケジュールされたパイプラインを一覧化します。
- ワークフローを 1 つ移植し(通常はメインのテストジョブ)、ブランチで実行します。
- 1〜2 週間並行して実行します。実行時間と成功率を比較し、不安定な差異を修正します。
- シークレットと環境を移行し、その後デプロイジョブを移します。まずはステージング環境でデプロイをテストしてください。
- ブランチ保護を更新し、CircleCI のチェックではなく GitHub のチェックを必須にします。
- CircleCI を無効化します。トリガーは停止し、設定は Git の履歴に残して、1 つのリリースサイクル後に削除します。
移行後:コストと速度
GitHub がホストするデフォルトのランナーは 2 vCPU です。CircleCI のジョブで large や xlarge のリソースクラスを使っていた場合、GitHub のデフォルトランナーは遅く感じられるでしょう。GitHub の大規模ランナーと代替案は GitHub Actions の料金で比較してください。compiler.dev では、runs-on を [self-hosted, Linux, compiler-ci] に変更するだけで、同じワークフローを 8 vCPU / 16 GB のマシンで分あたり $0.008 で実行できます。何か失敗した場合は元のランナーに自動でフォールバックします。詳しくは 料金をご覧ください。
よくある質問
CircleCI から GitHub Actions への移行にはどのくらいかかりますか?
標準の Orb を使う単一のパイプラインなら数時間です。カスタム Orb、コンテキスト、デプロイロジックを含むパイプラインが十数本ある場合は数週間かかり、その大半は検証とシークレットの移行に費やされます。
CircleCI の Orb の代わりは何ですか?
よく使われるツール向けの Marketplace アクション、再利用可能なステップの組み合わせ向けのコンポジットアクション、ジョブ全体を再利用するための再利用可能ワークフローです。
CircleCI のタイミングに基づくテスト分割は維持できますか?
ネイティブにはできません。Jest や Playwright はファイル数やテスト数で分割します。タイミングに基づいて分散させたい場合は、分割用のスクリプトや、そのために作られたツールを使ってください。
CircleCI の SSH デバッグは使えなくなりますか?
組み込みの同等機能はありません。コミュニティのアクションで一時的な SSH や tmate セッションを開けますが、使用前にセキュリティを評価してください。
しばらく両方を並行して動かすことはできますか?
はい、そうすることをお勧めします。結果が一致するまで両方を実行し、その後で必須チェックを切り替えてください。
関連記事
- GitLab CI から GitHub Actions への移行: ステップごとの手順.gitlab-ci.yml の対応表、並列比較による変換、変数、キャッシュ、サービス、Importer、切り替えを使って、GitLab CI から GitHub Actions へ移行します。
- JenkinsからGitHub Actionsへの移行: 手順ごとのガイドJenkinsfile の対応表、並べて見る変換、認証情報、キャッシュ、エージェント、Importer、切り替え計画を使って、Jenkins から GitHub Actions へ移行します。
- CircleCI と GitHub Actions:compiler.dev のランナーで比較compiler.dev のランナーで見る CircleCI と GitHub Actions:クレジット料金、設定の違い、CircleCI が優れる点、実際の YAML を使った移行の概要。
- 2026 年のベスト CircleCI 代替サービスCircleCI の代替候補を比較:GitHub Actions、GitLab CI、Buildkite、Semaphore、Jenkins、compiler.dev を、料金モデル、移行の手間、適合性の観点で紹介します。