GitHub Actions Importer を使用した Bitbucket パイプラインからの移行

法的通知

GitHub Actions Importer を使った Bitbucket からの移行について

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

前提条件

• Linux ベースのコンテナーを実行し、必要なツールをインストールできる環境。

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

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

制限事項

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

• プライベート AWS ECR 内のイメージはサポートされていません。

• Bitbucket Pipelines オプション size はサポートされていません。

• ジョブのキュー時間を詳細に示すメトリックは、forecast コマンドではサポートされていません。

• Bitbucket after-scriptは、前の手順の steps.<step_id>.conclusion のチェックと組み合わせて GitHub Actions always() を使用してサポートされます。 詳しくは、「コンテキスト」を参照してください。

  次には、always() とsteps.<step_id>.conclusion の仕様例を示します。

    - name: After Script 1
      run: |-
        echo "I'm after the script ran!"
        echo "We should be grouped!"
      id: after-script-1
      if: "${{ always() }}"
    - name: After Script 2
      run: |-
        echo "this is really the end"
        echo "goodbye, for now!"
      id: after-script-2
      if: "${{ steps.after-script-1.conclusion == 'success' && always() }}"
  

手動タスク

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

• セキュリティで保護されたリポジトリ、ワークスペース、デプロイ変数
• SSH キー

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

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

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

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

2. Bitbucket パイプラインのワークスペース アクセス トークンを作成します。 詳細については、 Bitbucket ドキュメントの ワークスペース アクセス トークンのアクセス許可 を参照してください。 トークンには、 パイプライン、プロジェクト、リポジトリの read スコープが必要です。

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

   gh actions-importer configure
   

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

   • "どの CI プロバイダーを構成していますか?" で、方向キーを使って Bitbucket を選び、Space キーを押して選択し、Enter キーを押します。
   • "GitHub の Personal access token" で、先ほど作成した personal access token の値を入力し、Enter キーを押します。
   • "GitHub インスタンスのベース URL" で、GitHub Enterprise Server インスタンスの URL を入力し、Enter キーを押します。
   • 「Bitbucket の Personal access token」で、先ほど作成したワークスペース アクセス トークンの値を入力し、Enter キーを押します。
   • 「Bitbucket インスタンスのベース URL」で、Bitbucket インスタンスの URL を入力し、Enter キーを押します。

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

   $ gh actions-importer configure
   ✔ Which CI providers are you configuring?: Bitbucket
   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 Bitbucket: ********************
   ✔ Base url of the Bitbucket instance: https://bitbucket.example.com
   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
   

Bitbucket インスタンスの監査を実行する

監査コマンドを使って、Bitbucketサーバー内のパイプラインの高水準ビューを取得できます。

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

1. ワークスペースのすべてのパイプラインをフェッチします。
2. パイプラインを同等の GitHub Actions ワークフローに変換します。
3. GitHub Actions Importer を使って、どの程度完全で複雑な移行が可能かをまとめたレポートを生成します。

監査コマンドの実行

監査を実行するには、ターミナルで次のコマンドを実行し、:workspace を監査する Bitbucket ワークスペースの名前に置き換えます。

gh actions-importer audit bitbucket --workspace :workspace--output-dir tmp/audit

必要に応じて、監査コマンドに --project-key オプションを指定して、結果をプロジェクトに関連付けられているパイプラインのみに制限することもできます。

次の例では、コマンド :project_key は、監査する必要があるプロジェクトのキーに置き換える必要があります。 プロジェクト キーは、ワークスペース プロジェクト ページの Bitbucket にあります。

gh actions-importer audit bitbucket --workspace :workspace --project-key :project_key --output-dir tmp/audit

監査結果の検査

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

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

Pipelines

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

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

• 成功したパイプラインでは、100% のパイプライン構成と個々の項目が、同等の GitHub Actions に自動的に変換されました。
• 部分的に成功したパイプラインは、すべてのパイプライン構成が変換されましたが、同等の GitHub Actions に自動的に変換されなかった個別項目がいくつかあります。
• 未サポートのパイプラインは、GitHub Actions Importer でサポートされていない定義の種類です。
• 失敗したパイプラインは、変換中に致命的なエラーが発生しました。 これは、次の 3 つの理由のいずれかで発生する可能性があります。
  • パイプラインが正しく構成されず、Bamboo で有効でなかった。
  • 変換時に 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 ファイルには、正常に変換された各パイプラインで使われるすべてのアクション、シークレット、ランナーのコンマ区切りのリストが含まれます。 これは、どのワークフローがどのアクション、シークレット、ランナーを使うかを判断するのに役立ち、セキュリティ レビューを実行するのに役立ちます。

使用状況の予測

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

forecast コマンドの実行

GitHub Actions の潜在的な使用状況の予測を実行するには、ターミナルで次のコマンドを実行し、:workspace を予測する Bitbucket ワークスペースの名前に置き換えます。 既定では、GitHub Actions Importer は予測レポートに過去 7 日間を含みます。

gh actions-importer forecast bitbucket --workspace :workspace --output-dir tmp/forecast_reports

プロジェクトの予測

予測をプロジェクトに限定するには、この --project-key オプションを使用できます。 予測するプロジェクトのプロジェクト キーで :project_key の値を置き換えます。

gh actions-importer forecast bitbucket --workspace :workspace --project-key :project_key --output-dir tmp/forecast_reports

予測レポートの検査

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

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

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

dry-run による移行の実行

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

dry-run コマンドの実行

Bitbucket パイプラインを GitHub Actions に移行するドライ ランを実行するには、ターミナルで次のコマンドを実行し、:workspace をワークスペースの名前で置き換え、:repo を Bitbucket リポジトリの名前に置き換えます。

gh actions-importer dry-run bitbucket --workspace :workspace --repository :repo --output-dir tmp/dry-run

変換されたワークフローの検査

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

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

本番移行を実行する

コマンドを使って、Bitbucket パイプラインを変換し、同等の GitHub Actions ワークフローで プルリクエスト を開くことができます。

migrate コマンドの実行

Bitbucket パイプラインを GitHub Actions に移行するには、ターミナルで次のコマンドを実行し、次の値を置き換えます。

• target-url 値を GitHub リポジトリの URL に置き換えます。
• :repo を、Bitbucket のリポジトリの名前に置き換えます。
• :workspace をワークスペースの名前に置き換えます。

gh actions-importer migrate bitbucket --workspace :workspace --repository :repo --target-url https://github.com/:owner/:repo --output-dir tmp/dry-run

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

gh actions-importer migrate bitbucket --workspace actions-importer --repository custom-trigger --target-url https://github.com/valet-dev-testing/demo-private --output-dir tmp/bitbucket
[2023-07-18 09:56:06] Logs: 'tmp/bitbucket/log/valet-20230718-165606.log'
[2023-07-18 09:56:24] Pull request: 'https://github.com/valet-dev-testing/demo-private/pull/55'

pull request の検査

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

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

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

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

リファレンス

このセクションには、環境変数、省略可能な引数、および GitHub Actions Importer を使って Bitbucket パイプラインから移行するときにサポートされる構文に関する参照情報が記載されています。

環境変数の使用

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

GitHub Actions Importer では、次の環境変数を使って Bitbucket インスタンスに接続されます。

• GITHUB_ACCESS_TOKEN: 変換されたワークフローで プルリクエスト を作成するために使われる personal access token (repo と workflow スコープが必要)。
• GITHUB_INSTANCE_URL: ターゲット GitHub インスタンスの URL。 (例: https://github.com)
• BITBUCKET_ACCESS_TOKEN: パイプライン、プロジェクト、リポジトリの読み取りスコープを持つワークスペース アクセス トークン。

これらの環境変数は、実行時に GitHub Actions Importer によって読み込まれることとなる .env.local ファイルに指定できます。 配布アーカイブには、これらのファイルの作成に使用できる .env.local.template ファイルが含まれています。

省略可能な引数。

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

--source-file-path

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

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

次に例を示します。

gh actions-importer dry-run bitbucket --workspace :workspace --repository :repo --output-dir tmp/dry-run --source-file-path path/to/my/pipeline/file.yml

--config-file-path

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

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

Audit の例

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

gh actions-importer audit bitbucket --workspace :workspace --output-dir tmp/audit --config-file-path "path/to/my/bitbucket/config.yml"

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

source_files:
  - repository_slug: repo_name
    path: path/to/one/source/file.yml
  - repository_slug: another_repo_name
    path: path/to/another/source/file.yml

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

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

Bitbucket	GitHub のアクション	Status
after-script	jobs.<job_id>.steps[*]	サポートされています
artifacts	actions/upload-artifact & download-artifact	サポートされています
caches	actions/cache	サポートされています
clone	actions/checkout	サポートされています
condition	job.<job_id>.steps[*].run	サポートされています
deployment	jobs.<job_id>.environmen	サポートされています
image	jobs.<job_id>.container	サポートされています
max-time	jobs.<job_id>.steps[*].timeout-minutes	サポートされています
options.docker	なし	サポートされています
options.max-time	jobs.<job_id>.steps[*].timeout-minutes	サポートされています
parallel	jobs.<job_id>	サポートされています
pipelines.branches	on.push	サポートされています
pipelines.custom	on.workflow_dispatch	サポートされています
pipelines.default	on.push	サポートされています
pipelines.pull-requests	on.pull_requests	サポートされています
pipelines.tags	on.tags	サポートされています
runs-on	jobs.<job_id>.runs-on	サポートされています
script	job.<job_id>.steps[*].run	サポートされています
services	jobs.<job_id>.service	サポートされています
stage	jobs.<job_id>	サポートされています
step	jobs.<job_id>.steps[*]	サポートされています
trigger	on.workflow_dispatch	サポートされています
fail-fast	なし	Unsupported
oidc	なし	Unsupported
options.size	なし	Unsupported
size	なし	Unsupported

環境変数のマッピング

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

Bitbucket	GitHub のアクション
CI	true
BITBUCKET_BUILD_NUMBER	${{ github.run_number }}
BITBUCKET_CLONE_DIR	${{ github.workspace }}
BITBUCKET_COMMIT	${{ github.sha }}
BITBUCKET_WORKSPACE	${{ github.repository_owner }}
BITBUCKET_REPO_SLUG	${{ github.repository }}
BITBUCKET_REPO_UUID	${{ github.repository_id }}
BITBUCKET_REPO_FULL_NAME	${{ github.repository_owner }}/${{ github.repository }}
BITBUCKET_BRANCH	${{ github.ref }}
BITBUCKET_TAG	${{ github.ref }}
BITBUCKET_PR_ID	${{ github.event.pull_request.number }}
BITBUCKET_PR_DESTINATION_BRANCH	${{ github.event.pull_request.base.ref }}
BITBUCKET_GIT_HTTP_ORIGIN	${{ github.event.repository.clone_url }}
BITBUCKET_GIT_SSH_ORIGIN	${{ github.event.repository.ssh_url }}
BITBUCKET_EXIT_CODE	${{ job.status }}
BITBUCKET_STEP_UUID	${{ job.github_job }}
BITBUCKET_PIPELINE_UUID	${{ github.workflow }}
BITBUCKET_PROJECT_KEY	${{ github.repository_owner }}
BITBUCKET_PROJECT_UUID	${{ github.repository_owner }}
BITBUCKET_STEP_TRIGGERER_UUID	${{ github.actor_id }}
BITBUCKET_SSH_KEY_FILE	${{ github.workspace }}/.ssh/id_rsa
BITBUCKET_STEP_OIDC_TOKEN	マッピングがありませんでした
BITBUCKET_DEPLOYMENT_ENVIRONMENT	マッピングがありませんでした
BITBUCKET_DEPLOYMENT_ENVIRONMENT_UUID	マッピングがありませんでした
BITBUCKET_BOOKMARK	マッピングがありませんでした
BITBUCKET_PARALLEL_STEP	マッピングがありませんでした
BITBUCKET_PARALLEL_STEP_COUNT	マッピングがありませんでした

システム変数

タスクで使用されるシステム変数は、同等の bash シェル変数に変換され、使用可能であると見なされます。 たとえば、${system.<variable.name>} は $variable_name に変換されます。 ワークフローの適切な操作を確実にするために、これを確認することをお勧めします。

法的通知

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.