コンテンツへスキップ

CircleCI から GitHub Actions への移行: ステップごとの手順

最終更新

CircleCIからGitHub Actionsへの移行は、大部分が翻訳作業になります。ジョブはジョブのまま残り、needsがワークフローに、オーブがMarketplaceのアクションに、save_cacheがactions/cacheになります。小規模なパイプラインであれば半日程度で移行できます。難しいのは、シークレット、コンテキスト、そしてresource_classやテストの分割など、CircleCI固有の機能に依存している部分です。このガイドでは、対応関係、実際の移行例、自動インポーター、そしてダウンタイムを避けるための切り替え計画を扱います。

製品レベルの比較については、CircleCI vs GitHub ActionsとCircleCIの代替サービスをご覧ください。

概念の対応関係

CircleCIGitHub 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: - runsteps: - run
checkoutactions/checkout
save_cache / restore_cacheactions/cache、またはsetup-*アクションのcache:
persist_to_workspace / attach_workspaceactions/upload-artifact / actions/download-artifact
store_artifactsactions/upload-artifact
store_test_resultsテストレポーターアクション、またはJUnitファイルのupload-artifact
parallelism: N + テスト分割strategy.matrix。テストシャーディングをご覧ください
オーブMarketplaceアクション、コンポジットアクション、再利用可能なワークフロー
コンテキスト環境、組織のシークレットと変数
プロジェクトの環境変数リポジトリのシークレットと変数
filters: brancheson.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 ドキュメントでご確認ください。

切り替え計画

  1. Importer で監査し、Orb、コンテキスト、スケジュールされたパイプラインを一覧化します。
  2. ワークフローを 1 つ移植し(通常はメインのテストジョブ)、ブランチで実行します。
  3. 1〜2 週間並行して実行します。実行時間と成功率を比較し、不安定な差異を修正します。
  4. シークレットと環境を移行し、その後デプロイジョブを移します。まずはステージング環境でデプロイをテストしてください。
  5. ブランチ保護を更新し、CircleCI のチェックではなく GitHub のチェックを必須にします。
  6. 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 セッションを開けますが、使用前にセキュリティを評価してください。

しばらく両方を並行して動かすことはできますか?

はい、そうすることをお勧めします。結果が一致するまで両方を実行し、その後で必須チェックを切り替えてください。

このワークフローを compiler.dev で実行する カード登録不要 · 200 無料分

無料で試す