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

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

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

前提条件

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

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

制限事項

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

手動タスク

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

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

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

Travis CI のプロジェクト言語

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

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

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

Bash

gh extension install github/gh-actions-importer

gh extension install github/gh-actions-importer

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

$ 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 Actions Importer を使用する場合に、GitHubに必要な資格情報とオプションを設定するために使用されます。

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

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

トークンは、作成後にコピーして、後で使用できるように安全な場所に保存します。
Travis CI API アクセストークンを作成します。詳しくは、Travis CI ドキュメントの「Travis CI API トークンを取得する」を参照してください。

トークンは、作成後にコピーして、後で使用できるように安全な場所に保存します。
ターミナルで、 GitHub Actions Importerconfigure CLI コマンドを実行します。
```
gh actions-importer configure
```

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

[どの CI プロバイダーを構成していますか?] で、方向キーを使用して Travis CI を選択し、Space キーを押して選択し、Enter キーを押します。
[Personal access token for GitHub] に、先ほど作成した personal access token (classic) の値を入力し、 Enter キーを押します。
[GitHub インスタンスのベース URL] で、の URL をお使いの GitHub Enterprise Server インスタンス入力し、Enter.
[Personal access token for Travis CI] に、先ほど作成した 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.

ターミナルで、 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
```

Travis CI の監査を実行する

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

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

Travis CI サーバーで定義されているすべてのプロジェクトを取得します。
各パイプラインを、同等の GitHub Actions ワークフローに変換します。
GitHub Actions Importerを使用して移行の完了と複雑さを要約したレポートを生成します。

監査コマンドの実行

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

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

監査結果の検査

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

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

Pipelines

"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ホストランナーではない変換されたパイプラインで参照されるランナーのラベルを指します。これらのパイプラインを適切に機能させるには、これらのランナーを手動で定義する必要があります。

Files

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

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

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

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

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

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 リポジトリに追加できます。

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 Actions
`$CONTINUOUS_INTEGRATION`	`$CI`
`$USER`	`${{ github.actor }}`
`$HOME`

| | $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 }} |

法務上の通知

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.

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

この記事で