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

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

以下の手順では、GitHub Actions Importer を使って Travis CI パイプラインを GitHub Actions に移行するように環境を構成する方法について説明します。

前提条件

• GitHub Actions ワークフローに変換したいパイプラインとジョブがある Travis CI アカウントまたは Organization。
• アカウントまたは組織のTravis CI APIアクセス トークンを作成するためのアクセス権。
• Linux ベースのコンテナーを実行し、必要なツールをインストールできる環境。

  • Docker がインストールされていて実行されていること。

  • GitHub CLI がインストールされていること。

  メモ

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

制限事項

Travis CI パイプラインから GitHub Actions Importer を使って GitHub Actions に移行する際には、いくつかの制限があります。

手動タスク

特定の Travis CI コンストラクトは手動で移行する必要があります。 具体的な内容は次のとおりです。

• シークレット
• 不明なジョブ プロパティ

手動移行の詳細については、「Travis CI から GitHub Actions への移行」を参照してください。

Travis CI のプロジェクト言語

GitHub Actions Importer は、構成済みの一連のビルド ツールと既定のビルド スクリプトを変換されたワークフローに追加することで、Travis CI プロジェクト言語を変換します。 言語が明示的に宣言されていない場合、GitHub Actions Importer はプロジェクト言語が Ruby であると見なします。

GitHub Actions Importer でサポートされているプロジェクト言語の一覧については、「サポートされているプロジェクト言語」を参照してください。

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 コマンドを使って、Travis CI と GitHub を操作するときに GitHub Actions Importer に必要な資格情報とオプションを設定します。

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

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

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

2. Travis CI API アクセス トークンを作成します。 詳しくは、Travis CI ドキュメントの「Travis CI API トークンを取得する」を参照してください。

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

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

   gh actions-importer configure
   

          `configure` コマンドでは、次の情報の入力が求められます。
   

   • [どの CI プロバイダーを構成していますか?] で、方向キーを使用して Travis CI を選択し、Space キーを押して選択し、Enter キーを押します。
   • "GitHub の Personal access token" で、先ほど作成した personal access token (classic) の値を入力し、Enter キーを押します。
   • "GitHub インスタンスのベース URL"、
   • "Travis CI の Personal access token" で、先ほど作成した Travis CI API アクセス トークンの値を入力し、Enter キーを押します。
   • "Travis CI インスタンスのベース URL" で、Travis CI インスタンスの URL を入力し、Enter キーを押します。
   • "Travis CI 組織名"で、Travis CI 組織名を入力し、Enterキーを押します。

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

   $ gh actions-importer configure
   ✔ Which CI providers are you configuring?: Travis CI
   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 Travis CI: ***************
   ✔ Base url of the Travis CI instance: https://travis-ci.com
   ✔ Travis CI organization name: actions-importer-labs
   Environment variables successfully updated.
   

4. ターミナルで GitHub Actions Importer update CLI コマンドを実行して GitHub Packages Container registry に接続し、コンテナー イメージが確実に最新バージョンに更新されるようにします。

   gh actions-importer update
   

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

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

Travis CI の監査を実行する

          `audit` コマンドを使って、Travis CI サーバー内のすべてのパイプラインの概要ビューを取得できます。

          `audit` コマンドによって、次のステップが実行されます。

1. Travis CI サーバーで定義されているすべてのプロジェクトを取得します。
2. 各パイプラインを、対応する GitHub Actions ワークフローに変換します。
3. GitHub Actions Importer を使って、どの程度完全で複雑な移行が可能かをまとめたレポートを生成します。

監査コマンドの実行

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

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

監査結果の検査

データ再利用アクションの監査のための検査

潜在的なビルド ランナーの使用状況を予測する

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

forecast コマンドの実行

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

gh actions-importer forecast travis-ci --output-dir tmp/forecast

予測レポートの検査

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

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

• ジョブ数は、完了したジョブの合計数です。
• パイプライン数は、使われた一意のパイプラインの数です。
• 実行時間は、ランナーがジョブに費やした時間を表します。 このメトリックを使うと、GitHub ホステッド ランナーのコストを計画するのに役立ちます。
  • このメトリックは、GitHub Actions に費やすと予想する時間と相関しています。 これは、この時間 (分) に使われるハードウェアによって異なります。 GitHub Actions 料金計算ツールを使って、コストを見積もることができます。
• キュー時間メトリクスは、ランナーが実行できるようになるのを待機するためにジョブが費やした時間を表します。
• 同時実行ジョブ メトリックは、特定の時点で実行されるジョブの量を表します。 このメトリックを使って、構成する必要があるランナーの数を定義できます。

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

Travis CI パイプラインのドライ ラン移行を実行する

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

Travis CI パイプラインを GitHub Actions に移行するドライ ランを実行するには、ターミナルで次のコマンドを実行し、my-travis-ci-repository を Travis CI リポジトリの名前に置き換えます。

gh actions-importer dry-run travis-ci --travis-ci-repository my-travis-ci-repository --output-dir tmp/dry-run

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

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

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

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

migrate コマンドの実行

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

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

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

$ gh actions-importer migrate travis-ci --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --travis-ci-repository my-travis-ci-repository
[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 を使って Travis CI から移行する場合の環境変数、省略可能な引数、サポートされる構文に関する参照情報が記載されています。

環境変数の使用

GitHub Actions Importer

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

• GITHUB_ACCESS_TOKEN: 変換されたワークフローで pull request を作成するために使われる personal access token (classic) (workflow スコープが必要)。
• GITHUB_INSTANCE_URL: ターゲット GitHub インスタンスへの URL (例: https://github.com)。
• TRAVIS_CI_ACCESS_TOKEN: Travis CI リソースを表示するために使用される Travis CI API アクセス トークン。
• TRAVIS_CI_ORGANIZATION: Travis CI インスタンスの Organization 名。
• TRAVIS_CI_INSTANCE_URL: Travis CI インスタンスの URL。
• TRAVIS_CI_SOURCE_GITHUB_ACCESS_TOKEN: (省略可能) ソース GitHub インスタンスで認証するために使用される personal access token。 指定しない場合、代わりに GITHUB_ACCESS_TOKEN が使われます。
• TRAVIS_CI_SOURCE_GITHUB_INSTANCE_URL: (省略可能) ソース GitHub インスタンスの URL (https://github.com など)。 指定しない場合、代わりに GITHUB_INSTANCE_URL が使われます。

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

省略可能な引数の使用

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 travis-ci --output-dir ./path/to/output/ --travis-ci-repository my-travis-ci-repository --source-file-path ./path/to/.travis.yml

--allow-inactive-repositories

この引数を使用して、GitHub Actions Importer で非アクティブなリポジトリを監査に含めるかどうかを指定できます。 このオプションが設定されていない場合、非アクティブなリポジトリは監査に含まれません。

gh actions-importer dry-run travis-ci --output-dir ./path/to/output/ --travis-ci-repository my-travis-ci-repository --allow-inactive-repositories

--config-file-path

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

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

監査の例

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

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

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

source_files:
  - repository_slug: travis-org-name/travis-repo-name
    path: path/to/.travis.yml
  - repository_slug: travis-org-name/some-other-travis-repo-name
    path: path/to/.travis.yml

ドライ ランの例

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

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

gh actions-importer dry-run travis-ci --travis-ci-repository travis-org-name/travis-repo-name --output-dir ./output/ --config-file-path ./path/to/travis-ci/config.yml

サポートされているプロジェクト言語

GitHub Actions Importer では、次の言語での Travis CI プロジェクトの移行がサポートされています。

• android
• bash
• c
• clojure
• c++
• crystal
• c#
• d
• dart
• elixir
• erlang
• generic
• go
• groovy
• haskell
• haxe
• java
• julia
• matlab
• minimal
• nix
• node_js
• objective-c
• perl
• perl6
• php
• python
• r
• ruby
• rust
• scala
• sh
• shell
• smalltalk
• swift

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

次の表は、GitHub Actions Importer で現在変換できるプロパティの種類を示しています。 Travis CI パイプライン構文と GitHub Actions の連携の詳細については、「Travis CI から GitHub Actions への移行」を参照してください。

Travis CI	GitHub Actions	ステータス
分岐	on.<push>.<branches>	サポートされています
プルリクエストをビルド	on.<pull_request>	サポートされています
env	env jobs.<job_id>.env jobs.<job_id>.steps.env	サポートされています
もし	jobs.<job_id>.if	サポートされています
ジョブ	jobs.<job_id> jobs.<job_id>.name	サポートされています
マトリックス	jobs.<job_id>.strategy jobs.<job_id>.strategy.fail-fast jobs.<job_id>.strategy.matrix	サポートされています
オペレーティングシステム & ディストリビューション	runners	サポートされています
スクリプト	jobs.<job_id>.steps	サポートされています
段階	jobs	サポートされています
env	on	部分的にサポートされています。
分岐	on.<push>.<tags> on.<push>.paths	サポートされていない
プルリクエストをビルド	on.<pull_request>.<branches> on.<pull_request>.<tags> on.<pull_request>.paths	サポートされていない
cronトリガー	on.schedule on.workflow_run	サポートされていない
env	jobs.<job_id>.timeout-minutes on.<event_name>.types	サポートされていない
ジョブ	jobs.<job_id>.container	サポートされていない
オペレーティングシステム & ディストリビューション	self hosted runners	サポートされていない

サポートされている Travis CI 構成について詳しくは、github/gh-actions-importer リポジトリを参照してください。

環境変数の構文

GitHub Actions Importer では、次の表のマッピングを使って、既定の Travis CI 環境変数を GitHub Actions の最も近い同等の変数に変換します。

Travis CI	GitHub Actions
$CONTINUOUS_INTEGRATION	$CI
$USER	${{ github.actor }}
$HOME	{ raw %}$ を% する { endraw %}%
$TRAVIS_BRANCH	${{ github.ref }}
$TRAVIS_BUILD_DIR	${{ github.workspace }}
$TRAVIS_BUILD_ID	${{ github.run_number }}
$TRAVIS_BUILD_NUMBER	${{ github.run_id }}
$TRAVIS_COMMIT	${{ github.sha }}
$TRAVIS_EVENT_TYPE	${{ github.event_name }}
$TRAVIS_PULL_REQUEST_BRANCH	${{ github.base_ref }}
$TRAVIS_PULL_REQUEST	${{ github.event.number }}
$TRAVIS_PULL_REQUEST_SHA	${{ github.head.sha }}
$TRAVIS_PULL_REQUEST_SLUG	${{ github.repository }}
$TRAVIS_TAG	${{ github.ref }}
$TRAVIS_OS_NAME	${{ runner.os }}
$TRAVIS_JOB_ID	${{ github.job }}
$TRAVIS_REPO_SLUG	${{ github.repository_owner/github.repository }}
$TRAVIS_BUILD_WEB_URL	${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

法務上の通知

データ再利用可能アクション.actions-importer-legal-notice %}