GitHub Actions Importer を使用した CircleCI からの移行

          GitHub Actions Importerを使用して、CircleCI パイプラインのGitHub Actionsへの移行を自動化する方法について説明します。

この記事で

GitHub Actions Importer を使用した CircleCI からの移行について

次の手順では、 GitHub Actions Importer を使用して CircleCI パイプラインを GitHub Actionsに移行するように環境を構成する手順について説明します。

前提条件

  •         GitHub Actionsワークフローに変換するプロジェクトとパイプラインを含む CircleCI アカウントまたは組織。
  • アカウントまたは Organization の CircleCI 個人用 API トークンを作成するためのアクセス。
  • Linux ベースのコンテナーを実行し、必要なツールをインストールできる環境。

    メモ

    GitHub Actions Importer コンテナーと CLI は、CI プラットフォームと同じサーバーにインストールする必要はありません。

制限事項

          GitHub Actionsを使用して CircleCI からGitHub Actions Importerに移行する場合、いくつかの制限があります。
  • 異なるワークフローのジョブ間での自動キャッシュはサポートされていません。
  •         `audit` コマンドは、CircleCI 組織アカウントを使っている場合にのみサポートされます。 
        `dry-run` コマンドと `migrate` コマンドは、CircleCI 組織またはユーザー アカウントで使うことができます。

手動タスク

特定の CircleCI 構成は手動で移行する必要があります。 これには以下が含まれます。

  • コンテキスト
  • プロジェクト レベルの環境変数
  • 不明なジョブ プロパティ
  • 不明な球体

          GitHub Actions Importer CLI 拡張機能のインストール

  1. GitHub Actions Importer CLI 拡張機能のインストール

    Bash
    gh extension install github/gh-actions-importer

  2. 拡張機能がインストールされていることを確認します。

    $ gh actions-importer -h
Options:
  -?, -h, --help  Show help and usage information

Commands:
  update     Update to the latest version of GitHub Actions Importer.
  version    Display the version of GitHub Actions Importer.
  configure  Start an interactive prompt to configure credentials used to authenticate with your CI server(s).
  audit      Plan your CI/CD migration by analyzing your current CI/CD footprint.
  forecast   Forecast GitHub Actions usage from historical pipeline utilization.
  dry-run    Convert a pipeline to a GitHub Actions workflow and output its yaml file.
  migrate    Convert a pipeline to a GitHub Actions workflow and open a pull request with the changes.

資格情報の構成

          `configure` CLI コマンドを使用して、CircleCI と GitHub Actions Importer を操作するときにGitHubに必要な資格情報とオプションを設定します。

1. GitHub personal access token (classic)を作成します。 詳しくは、「個人用アクセス トークンを管理する」をご覧ください。

トークンには、 repo スコープと workflow スコープが必要です。

トークンは、作成後にコピーして、後で使用できるように安全な場所に保存します。

  1. CircleCI 個人用 API トークンを作成します。 詳しくは、CircleCI ドキュメントの「API トークンの管理」を参照してください。

    トークンは、作成後にコピーして、後で使用できるように安全な場所に保存します。

  2. ターミナルで、 GitHub Actions Importerconfigure CLI コマンドを実行します。

    gh actions-importer configure

           `configure` コマンドでは、次の情報の入力が求められます。
    • [どの CI プロバイダーを構成していますか?] で、方向キーを使用して CircleCI を選択し、Space キーを押して選択し、Enter キーを押します。
    • [Personal access token for GitHub] に、先ほど作成した personal access token (classic) の値を入力し、 Enter キーを押します。
    • [GitHub インスタンスのベース URL] で、の URL をお使いの GitHub Enterprise Server インスタンス入力し、Enter.
    • "CircleCI のPersonal access token " には、先ほど作成した CircleCI 個人用 API トークンの値を入力し、 Enter キーを押します。
    • "CircleCI インスタンスのベース URL" で、Enter キーを押して既定値 (https://circleci.com) を受け入れます。
    • 「CircleCI 組織名」のフィールドに、あなたの CircleCI 組織の名前を入力し、Enterキーを押します。

    以下に configure コマンドの例を示します。

    $ gh actions-importer configure
✔ Which CI providers are you configuring?: CircleCI
Enter the following values (leave empty to omit):
✔ Personal access token for GitHub: ***************
✔ Base url of the GitHub instance: https://github.com
✔ Personal access token for CircleCI: ********************
✔ Base url of the CircleCI instance: https://circleci.com
✔ CircleCI organization name: mycircleciorganization
Environment variables successfully updated.

  3. ターミナルで、 GitHub Actions Importerupdate CLI コマンドを実行して GitHub PackagesContainer registry に接続し、コンテナー イメージが最新バージョンに更新されていることを確認します。

    gh actions-importer update

    コマンドの出力は次のようになります。

    Updating ghcr.io/actions-importer/cli:latest...
ghcr.io/actions-importer/cli:latest up-to-date

CircleCI の監査を実行する

          `audit` コマンドを使って、CircleCI Organization 内のすべてのプロジェクトの概要ビューを取得できます。

          `audit` コマンドによって、次のステップが実行されます。
  1. CircleCI組織で定義されているすべてのプロジェクトを取得します。
  2. 各パイプラインを、同等の GitHub Actions ワークフローに変換します。
  3.        GitHub Actions Importerを使用して移行の完了と複雑さを要約したレポートを生成します。

監査コマンドの実行

CircleCI Organization の監査を実行するには、ターミナルで次のコマンドを実行します。

gh actions-importer audit circle-ci --output-dir tmp/audit

監査結果の検査

監査の結果は、指定した出力ディレクトリ内のファイルに含まれます。 監査結果の概要については、audit_summary.md ファイルを参照してください。

監査の概要には、次のセクションがあります。

Pipelines

"パイプライン" セクションには、GitHub Actions Importer によって行われた変換率に関する統計情報の概要が含まれます。

以下に、"パイプライン" セクションに表示される可能性がある主な用語を示します。

  • 成功したパイプラインでは、100% のパイプライン構成と個々の項目が、同等の GitHub Actions に自動的に変換されました。
  • 部分的に成功したパイプラインは、すべてのパイプライン構成が変換されましたが、同等の GitHub Actions に自動的に変換されなかった個別項目がいくつかあります。
  • 未サポートのパイプラインは、GitHub Actions Importer でサポートされていない定義の種類です。
  • 失敗したパイプラインは、変換中に致命的なエラーが発生しました。 これは、次の 3 つの理由のいずれかで発生する可能性があります。
    • パイプラインの構成が元々正しくなかったため、有効でなかった。
    • 変換時に GitHub Actions Importer で内部エラーが発生した。
    • ネットワーク応答が失敗して、パイプラインにアクセスできなくなったが、これは多くの場合、無効な資格情報が原因である。

ビルド ステップ

"ビルド ステップ" セクションには、すべてのパイプラインで使われる個々のビルド ステップの概要と、GitHub Actions Importer によって自動的に変換された数が含まれます。

以下に、"ビルド ステップ" セクションに表示される可能性がある主な用語を示します。

  • 既知のビルド ステップは、同等のアクションに自動的に変換されたステップです。
  • 不明なビルド ステップは、同等のアクションに自動的に変換されなかったステップです。
  • 未サポートのビルド ステップは、次のいずれかのステップです。
    • GitHub Actions で基本的にサポートされていない。
    • GitHub Actions と互換性のない方法で構成されている。
  • アクションは、変換されたワークフローで使われたアクションのリストです。 これは、次の場合に重要である可能性があります。
    • GitHub Enterprise Server を使う場合、インスタンスに同期するアクションのリストを収集する。
    • 使われるアクションの組織レベルの許可リストを定義する。 このアクション リストは、セキュリティ チームまたはコンプライアンス チームの確認を必要とする可能性があるアクションの包括的なリストです。

手動タスク

"手動タスク" セクションには、GitHub Actions Importer で自動的に完了できず、手動で完了する必要があるタスクの概要が含まれます。

以下に、"手動タスク" セクションに表示される可能性がある主な用語を示します。

  • シークレットは、変換されたパイプラインで使われるリポジトリまたは組織レベルのシークレットです。 これらのパイプラインが正常に機能するためには、これらのシークレットを GitHub Actions で手動で作成する必要があります。 詳しくは、「GitHub Actions でのシークレットの使用」をご覧ください。
  • セルフホステッド ランナーとは、変換されたパイプラインで参照されるランナーのラベルのうち、GitHub ホステッド ランナーではないものを指します。 これらのパイプラインを適切に機能させるには、これらのランナーを手動で定義する必要があります。

ファイル

監査レポートの最後のセクションには、監査中にディスクに書き込まれたすべてのファイルのマニフェストが表示されます。

各パイプライン ファイルには、次のようなさまざまなファイルが監査に含まれます。

  • GitHub で定義された元のパイプライン。
  • パイプラインの変換に使われたネットワーク応答のすべて。
  • 変換されたワークフロー ファイル。
  • 失敗したパイプライン変換のトラブルシューティングに使用できるスタック トレース。

さらに、workflow_usage.csv ファイルには、正常に変換された各パイプラインで使われるすべてのアクション、シークレット、ランナーのコンマ区切りのリストが含まれます。 これは、どのワークフローがどのアクション、シークレット、ランナーを使うかを判断するのに役立ち、セキュリティ レビューを実行するのに役立ちます。

潜在的な GitHub Actions の使用状況を予測する

          `forecast` コマンドを使用すると、CircleCI で完了したパイプライン実行のメトリックを計算することで、潜在的なGitHub Actions使用状況を予測できます。

forecast コマンドの実行

潜在的な GitHub Actions 使用状況の予測を実行するには、ターミナルで次のコマンドを実行します。 既定では、 GitHub Actions Importer は予測レポートに過去 7 日間を含みます。

gh actions-importer forecast circle-ci --output-dir tmp/forecast_reports

予測レポートの検査

予測の結果は、指定した出力ディレクトリ内の forecast_report.md ファイルに含まれます。

以下に、予測レポートに表示される可能性がある主な用語を示します。

  •         **ジョブ数**は、完了したジョブの合計数です。

  •         **パイプライン数**は、使われた一意のパイプラインの数です。

  •         **実行時間**は、ランナーがジョブに費やした時間を表します。 このメトリックは、 GitHubホストランナーのコストを計画するのに役立ちます。

    このメトリックは、 GitHub Actionsでの支出が予想される量と関連付けられます。 これは、この時間 (分) に使われるハードウェアによって異なります。 GitHub Actions料金計算ツールを使用して、コストを見積もることができます。

  •         **キュー時間**メトリクスは、ランナーが実行できるようになるのを待機するためにジョブが費やした時間を表します。

  •         **同時実行ジョブ** メトリックは、特定の時点で実行されるジョブの量を表します。 このメトリックを使って、構成する必要があるランナーの数を定義できます。

さらに、これらのメトリックは、CircleCI のランナーの各キューに対して定義されます。 これはホステッド ランナーとセルフホステッド ランナー、またはハイ スペック マシンとロー スペック マシンが混在している場合に特に有用で、異なるタイプのランナーに固有のメトリックを確認できます。

CircleCI パイプラインの dry-run 移行を実行する

          `dry-run` コマンドを使用して、CircleCI パイプラインを同等のGitHub Actionsワークフローに変換できます。 dry-run を実行すると、指定したディレクトリに出力ファイルが作成されますが、パイプラインを移行するための pull request は開かれません。

CircleCI プロジェクトを GitHub Actionsに移行するドライ ランを実行するには、ターミナルで次のコマンドを実行し、 my-circle-ci-project を CircleCI プロジェクトの名前に置き換えます。

gh actions-importer dry-run circle-ci --output-dir tmp/dry-run --circle-ci-project my-circle-ci-project

指定した出力ディレクトリで、ドライ ランのログと変換されたワークフロー ファイルを表示できます。

不明なビルド ステップや部分的に成功したパイプラインなど、GitHub Actions Importer で自動的に変換できなかったものがある場合は、カスタム トランスフォーマーを作成して変換プロセスをさらにカスタマイズできます。 詳しくは、「カスタム トランスフォーマーを使用した GitHub Actions Importer の拡張」をご覧ください。

CircleCI パイプラインの運用移行を実行する

          `migrate` コマンドを使用すると、CircleCI パイプラインを変換し、同等のGitHub Actionsワークフローで pull request を開くことができます。

migrate コマンドの実行

CircleCI パイプラインを GitHub Actionsに移行するには、ターミナルで次のコマンドを実行し、 target-url の値を GitHub リポジトリの URL に置き換え、 my-circle-ci-project を CircleCI プロジェクトの名前に置き換えます。

gh actions-importer migrate circle-ci --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --circle-ci-project my-circle-ci-project

コマンドの出力には、変換されたワークフローをリポジトリに追加する pull request への URL が含まれます。 成功した出力の例は、次のようになります。

$ gh actions-importer migrate circle-ci --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --circle-ci-project my-circle-ci-project
[2022-08-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20220916-014033.log'
[2022-08-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1'

pull request の検査

migrate コマンドが正常に実行された場合、出力には、変換されたワークフローをリポジトリに追加する新しい pull request へのリンクが含まれます。

pull request の重要な要素には、次のようなものがあります。

  • pull request の説明の「手動ステップ」というセクションには、パイプラインの GitHub Actions への移行を終了する前に手動で完了する必要があるステップが列挙されています。 たとえば、このセクションでは、ワークフローで使われるシークレットを作成するように指示する場合があります。
  • 変換されたワークフロー ファイル。 Pull request の [Files changed] タブを選んで、GitHub リポジトリに追加されるワークフロー ファイルを表示します。

Pull request の検査が終了したら、それをマージして、ワークフローを GitHub リポジトリに追加できます。

リファレンス

このセクションには、 GitHub Actions Importer を使用して CircleCI から移行する場合の環境変数、省略可能な引数、およびサポートされる構文に関する参照情報が含まれています。

環境変数の使用

GitHub Actions Importer では、認証構成に環境変数が使われます。 これらの変数は、configure コマンドを使って構成プロセスに従うことで設定します。 詳細については、資格情報の構成に関するセクションを参照してください。

          GitHub Actions Importer では、次の環境変数を使用して CircleCI インスタンスに接続します。

* GITHUB_ACCESS_TOKEN: 変換されたワークフローを使用してプル要求を作成するために使用される personal access token (classic) ( repo スコープと workflow スコープが必要です)。 * GITHUB_INSTANCE_URL: ターゲット GitHub インスタンスへの URL (たとえば、 https://github.com)。 * CIRCLE_CI_ACCESS_TOKEN: CircleCI インスタンスで認証するために使われる CircleCI 個人用 API トークン。 * CIRCLE_CI_INSTANCE_URL: CircleCI インスタンスの URL (例: https://circleci.com)。 変数が未設定のままの場合は、https://circleci.com が既定値として使われます。 * CIRCLE_CI_ORGANIZATION: CircleCI インスタンスの Organization 名。 * CIRCLE_CI_PROVIDER: パイプラインのソース ファイルが格納されている場所 (github など)。 現時点では、GitHub のみがサポートされています。 * CIRCLE_CI_SOURCE_GITHUB_ACCESS_TOKEN(省略可能): ソースのpersonal access token (classic)インスタンスで認証するために使用されるGitHub（repoスコープが必要）。 指定しないと、代わりに GITHUB_ACCESS_TOKEN の値が使われます。 * CIRCLE_CI_SOURCE_GITHUB_INSTANCE_URL (省略可能): ソース GitHub インスタンスへの URL。 指定しないと、代わりに GITHUB_INSTANCE_URL の値が使われます。

これらの環境変数は、実行時に.env.localによって読み込まれるGitHub Actions Importer ファイルで指定できます。

省略可能な引数。

GitHub Actions Importer サブコマンドと一緒に使って、移行をカスタマイズできる省略可能な引数があります。

--source-file-path

          `--source-file-path` 引数は、`forecast`、`dry-run`、または `migrate` サブコマンドと一緒に使うことができます。

既定では、 GitHub Actions Importer はソース管理からパイプラインの内容をフェッチします。 --source-file-path引数は、指定したソース ファイル パスを代わりに使用するようにGitHub Actions Importerに指示します。

次に例を示します。

gh actions-importer dry-run circle-ci --output-dir ./output/ --source-file-path ./path/to/.circleci/config.yml

          `forecast` サブコマンドの実行時に複数のソース ファイルを指定する場合は、ファイル パス値でパターン マッチングを使うことができます。 たとえば、`gh forecast --source-file-path ./tmp/previous_forecast/jobs/*.json`は、GitHub Actions Importer ファイル パスに一致するソース ファイルと`./tmp/previous_forecast/jobs/*.json`を提供します。

--config-file-path

          `--config-file-path` 引数は、`audit`、`dry-run`、および `migrate` サブコマンドと一緒に使うことができます。

既定では、 GitHub Actions Importer はソース管理からパイプラインの内容をフェッチします。 --config-file-path引数は、指定したソース ファイルを代わりに使用するようにGitHub Actions Importerに指示します。

          `--config-file-path` 引数を使って、変換された複合アクションを移行するリポジトリを指定することもできます。
監査の例

この例では、 GitHub Actions Importer は、指定した YAML 構成ファイルを使用して監査を実行します。

gh actions-importer audit circle-ci --output-dir ./output/ --config-file-path ./path/to/circle-ci/config.yml

構成ファイルを使って CircleCI インスタンスを監査するには、構成ファイルが次の形式である必要があり、repository_slug がそれぞれ一意である必要があります。

source_files:
  - repository_slug: circle-org-name/circle-project-name
    path: path/to/.circleci/config.yml
  - repository_slug: circle-org-name/some-other-circle-project-name
    path: path/to/.circleci/config.yml
ドライ ランの例

この例では、 GitHub Actions Importer は、指定した YAML 構成ファイルをソース ファイルとして使用してドライ ランを実行します。

構成ファイルの repository_slug を --circle-ci-organization および --circle-ci-project オプションの値に一致させてパイプラインを選びます。 次に path を使って、指定したソース ファイルをプルします。

gh actions-importer dry-run circle-ci --circle-ci-project circle-org-name/circle-project-name --output-dir ./output/ --config-file-path ./path/to/circle-ci/config.yml
変換された複合アクションのリポジトリを指定する
          GitHub Actions Importer では、 `--config-file-path` 引数に指定された YAML ファイルを使用して、変換された複合アクションが移行されるリポジトリが決定されます。

まず、--config-file-path 引数を指定せずに監査を実行する必要があります。

gh actions-importer audit circle-ci --output-dir ./output/

このコマンドの出力には、config.ymlによって変換されたすべての複合アクションの一覧を含む GitHub Actions Importer という名前のファイルが含まれます。 たとえば、config.yml ファイルの内容は次のようになります。

composite_actions:
  - name: my-composite-action.yml
    target_url: https://github.com/octo-org/octo-repo
    ref: main

このファイルを使って、再利用可能なワークフローまたは複合アクションを追加するリポジトリと参照先を指定できます。 その後、--config-file-path引数を使用してファイルconfig.ymlをGitHub Actions Importer に提供できます。 たとえば、migrate コマンドを実行するときにこのファイルを使って、構成ファイルで定義されている一意のリポジトリごとに pull request を開くことができます。

gh actions-importer migrate circle-ci --circle-ci-project my-project-name --output-dir output/ --config-file-path config.yml --target-url https://github.com/my-org/my-repo

--include-from

          `--include-from` 引数は、`audit` サブコマンドと一緒に使うことができます。

          `--include-from` 引数には、CircleCI Organization の監査に含めるリポジトリの行区切りリストを含むファイルを指定します。 このファイルに含まれていないリポジトリはすべて、監査から除外されます。

次に例を示します。

gh actions-importer audit circle-ci --output-dir ./output/ --include-from repositories.txt

このパラメーターに指定するファイルは、リポジトリの行区切りリストである必要があります。次に例を示します:

repository_one
repository_two
repository_three

CircleCI パイプラインでサポートされている構文

次の表に、現在変換できる GitHub Actions Importer プロパティの種類を示します。

CircleCI パイプラインGitHub Actionsステータス
cronトリガー
  • on.schedule
サポートされています
環境
  • env
  • jobs.<job_id>.env
  • jobs.<job_id>.steps.env
サポートされています
実行者
  • runs-on
サポートされています
仕事
  • jobs
サポートされています
ジョブ
  • jobs.<job_id>
  • jobs.<job_id>.name
サポートされています
マトリックス
  • jobs.<job_id>.strategy
  • jobs.<job_id>.strategy.matrix
サポートされています
パラメータ
  • env
  • workflow-dispatch.inputs
サポートされています
手順
  • jobs.<job_id>.steps
サポートされています
該当する場合、除外
  • jobs.<job_id>.if
サポートされています
トリガー
  • on
サポートされています
実行者
  • container
  • services
部分的にサポートされる
orb
  • actions
部分的にサポートされる
実行者
  • self hosted runners
サポートされていない
セットアップ適用なしサポートされていない
バージョン適用なしサポートされていない

サポートされている CircleCI の概念と orb マッピングについて詳しくは、github/gh-actions-importer リポジトリを参照してください。

環境変数のマッピング

          GitHub Actions Importer では、次の表のマッピングを使用して、既定の CircleCI 環境変数を、 GitHub Actionsで最も近い同等の環境変数に変換します。
CircleCIGitHub Actions
CI$CI
CIRCLE_BRANCH${{ github.ref }}
CIRCLE_JOB${{ github.job }}
CIRCLE_PR_NUMBER${{ github.event.number }}
CIRCLE_PR_REPONAME${{ github.repository }}
CIRCLE_PROJECT_REPONAME${{ github.repository }}
CIRCLE_SHA1${{ github.sha }}
CIRCLE_TAG${{ github.ref }}
CIRCLE_USERNAME${{ github.actor }}
CIRCLE_WORKFLOW_ID${{ github.run_number }}
CIRCLE_WORKING_DIRECTORY${{ github.workspace }}
<< pipeline.id >>${{ github.workflow }}
<< pipeline.number >>${{ github.run_number }}
<< pipeline.project.git_url >>$GITHUB_SERVER_URL/$GITHUB_REPOSITORY
<< pipeline.project.type >>github
<< pipeline.git.tag >>${{ github.ref }}
<< pipeline.git.branch >>${{ github.ref }}
<< pipeline.git.revision >>${{ github.event.pull_request.head.sha }}
<< pipeline.git.base_revision >>${{ github.event.pull_request.base.sha }}

MIT ライセンスのもとで https://github.com/github/gh-actions-importer/ から一部を引用しています。

MIT License

Copyright (c) 2022 GitHub

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.