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

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

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

前提条件

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

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

制限事項

GitHub Actions Importer を使った GitLab パイプラインから GitHub Actions へのプロセスの自動移行には、いくつかの制限があります。

異なるワークフローのジョブ間での自動キャッシュはサポートされていません。
audit コマンドは、組織アカウントを使っている場合にのみサポートされます。ただし、dry-run コマンドと migrate コマンドは、組織またはユーザーアカウントで使うことができます。

手動タスク

特定の GitLab 構成は手動で移行する必要があります。具体的な内容は次のとおりです。

マスクされたプロジェクトまたはグループ変数の値
成果物報告書

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

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

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

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

トークンは、作成後にコピーして、後で使用できるように安全な場所に保存します。
GitLab personal access token を作成します。詳しくは、GitLab ドキュメントの「Personal access tokens」を参照してください。

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

トークンは、作成後にコピーして、後で使用できるように安全な場所に保存します。
ターミナルで、GitHub Actions Importer configure CLI コマンドを実行します。
```
gh actions-importer configure
```
```
       `configure` コマンドでは、次の情報の入力が求められます。
```
- [どの CI プロバイダーを構成していますか?] で、方向キーを使用して GitLab を選択し、Space キーを押して選択し、Enter キーを押します。
- "GitHub の Personal access token" で、先ほど作成した personal access token (classic) の値を入力し、Enter キーを押します。
- "GitHub インスタンスのベース URL"、お使いの GitHub Enterprise Server インスタンスの URL を入力し、Enter キーを押します。それ以外の場合は、Enter キーを押して既定値 (https://github.com) を受け入れます。
- "GitLab のプライベートトークン" で、先ほど作成した GitLab personal access token の値を入力し、Enter キーを押します。
- "GitLab インスタンスのベース URL" で、GitLab インスタンスの URL を入力し、Enter キーを押します。
以下に configure コマンドの出力の例を示します。
```
$ gh actions-importer configure
✔ Which CI providers are you configuring?: GitLab
Enter the following values (leave empty to omit):
✔ Personal access token for GitHub: ***************
✔ Base url of the GitHub instance: https://github.com
✔ Private token for GitLab: ***************
✔ Base url of the GitLab instance: http://localhost
Environment variables successfully updated.
```
ターミナルで 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
```

GitLab の監査を実行する

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

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

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

audit コマンドの前提条件

          `audit` コマンドを使うには、GitLab 組織アカウントで personal access token が構成されている必要があります。

audit コマンドの実行

GitLab サーバーの監査を実行するには、ターミナルで次のコマンドを実行します。my-gitlab-namespace は、監査する名前空間またはグループに置き換えます。

gh actions-importer audit gitlab --output-dir tmp/audit --namespace my-gitlab-namespace

監査結果の検査

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

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

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

forecast コマンドの実行

潜在的な GitHub Actions の使用状況の予測を実行するには、ターミナルで次のコマンドを実行します。my-gitlab-namespace は予測する名前空間またはグループに置き換えます。既定では、GitHub Actions Importer による予測レポートに過去 7 日間が含まれます。

gh actions-importer forecast gitlab --output-dir tmp/forecast --namespace my-gitlab-namespace

名前空間全体の予測

名前空間全体とそのすべてのサブグループを予測するには、--namespace 引数または NAMESPACE 環境変数で各サブグループを指定する必要があります。

次に例を示します。

gh actions-importer forecast gitlab --namespace my-gitlab-namespace my-gitlab-namespace/subgroup-one my-gitlab-namespace/subgroup-two ...

予測レポートの検査

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

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

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

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

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

          `dry-run` コマンドを使って、GitLab パイプラインを同等の GitHub Actions ワークフローに変換できます。

dry-run コマンドの実行

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

GitLab パイプラインを GitHub Actions に移行するドライランを実行するには、ターミナルで次のコマンドを実行します。my-gitlab-project を GitLab プロジェクトの置換フィールドに、my-gitlab-namespace をドライランを実行する名前空間またはグループ (サブグループ用の完全なグループパス、例: my-org/my-team) に置換します。

gh actions-importer dry-run gitlab --output-dir tmp/dry-run --namespace my-gitlab-namespace --project my-gitlab-project

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

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

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

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

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

migrate コマンドの実行

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

target-url の値を GitHub リポジトリの URL に設定してください
my-gitlab-project を GitLab プロジェクトのスラッグに置き換える
my-gitlab-namespace を移行する名前空間またはグループ (サブグループ用の完全なパス、例: my-org/my-team) に置換する

gh actions-importer migrate gitlab --target-url https://github.com/:owner/:repo --output-dir tmp/migrate --namespace my-gitlab-namespace --project my-gitlab-project

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

$ gh actions-importer migrate gitlab --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --namespace octo-org --project monas-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 を使って GitLab から移行するときにサポートされる構文に関する参照情報が記載されています。

環境変数の使用

GitHub Actions Importer

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

GITHUB_ACCESS_TOKEN: 変換されたワークフローで pull request を作成するために使われる personal access token (classic) (workflow スコープが必要)。
GITHUB_INSTANCE_URL: ターゲット GitHub インスタンスへの URL (例: https://github.com)。
GITLAB_ACCESS_TOKEN: GitLab リソースの表示に使われる GitLab personal access token。
GITLAB_INSTANCE_URL: GitLab インスタンスの URL。
NAMESPACE: GitLab パイプラインを含む名前空間またはグループ。

これらの環境変数は、実行時に 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 gitlab --output-dir output/ --namespace my-gitlab-namespace --project my-gitlab-project --source-file-path path/to/.gitlab-ci.yml

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

gh actions-importer forecast gitlab --output-dir output/ --namespace my-gitlab-namespace --project my-gitlab-project --source-file-path ./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 gitlab --output-dir path/to/output/ --namespace my-gitlab-namespace --config-file-path path/to/gitlab/config.yml

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

source_files:
  - repository_slug: namespace/project-name
    path: path/to/.gitlab-ci.yml
  - repository_slug: namespace/some-other-project-name
    path: path/to/.gitlab-ci.yml

ドライランの例

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

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

gh actions-importer dry-run gitlab --namespace my-gitlab-namespace --project my-gitlab-project-name --output-dir ./output/ --config-file-path ./path/to/gitlab/config.yml

変換された再利用可能なワークフローのリポジトリを指定する

GitHub Actions Importer では --config-file-path 引数に指定された YAML ファイルを使って、変換された再利用可能なワークフローが移行されるリポジトリを決定します。

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

gh actions-importer audit gitlab --output-dir ./output/

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

reusable_workflows:
  - name: my-reusable-workflow.yml
    target_url: https://github.com/octo-org/octo-repo
    ref: main

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

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

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

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

GitLabパイプライン	GitHub Actions	ステータス
`after_script`	`jobs.<job_id>.steps`	サポートされています
`auto_cancel_pending_pipelines`	`concurrency`	サポートされています
`before_script`	`jobs.<job_id>.steps`	サポートされています
`build_timeout` または `timeout`	`jobs.<job_id>.timeout-minutes`	サポートされています
`default`	該当なし	サポートされています
`image`	`jobs.<job_id>.container`	サポートされています
`job`	`jobs.<job_id>`	サポートされています
`needs`	`jobs.<job_id>.needs`	サポートされています
`only_allow_merge_if_pipeline_succeeds`	`on.pull_request`	サポートされています
`resource_group`	`jobs.<job_id>.concurrency`	サポートされています
`schedule`	`on.schedule`	サポートされています
`script`	`jobs.<job_id>.steps`	サポートされています
`stages`	`jobs`	サポートされています
`tags`	`jobs.<job_id>.runs-on`	サポートされています
`variables`

          `env`、`jobs.<job_id>.env`      |                   サポートされています |

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

環境変数の構文

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

GitLab	GitHub Actions
`CI_API_V4_URL`	`${{ github.api_url }}`
`CI_BUILDS_DIR`	`${{ github.workspace }}`
`CI_COMMIT_BRANCH`	`${{ github.ref }}`
`CI_COMMIT_REF_NAME`	`${{ github.ref }}`
`CI_COMMIT_REF_SLUG`	`${{ github.ref }}`
`CI_COMMIT_SHA`	`${{ github.sha }}`
`CI_COMMIT_SHORT_SHA`	`${{ github.sha }}`
`CI_COMMIT_TAG`	`${{ github.ref }}`
`CI_JOB_ID`	`${{ github.job }}`
`CI_JOB_MANUAL`	`${{ github.event_name == 'workflow_dispatch' }}`
`CI_JOB_NAME`	`${{ github.job }}`
`CI_JOB_STATUS`	`${{ job.status }}`
`CI_JOB_URL`	`${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}`
`CI_JOB_TOKEN`	`${{ github.token }}`
`CI_NODE_INDEX`	`${{ strategy.job-index }}`
`CI_NODE_TOTAL`	`${{ strategy.job-total }}`
`CI_PIPELINE_ID`	`${{ github.repository}}/${{ github.workflow }}`
`CI_PIPELINE_IID`	`${{ github.workflow }}`
`CI_PIPELINE_SOURCE`	`${{ github.event_name }}`
`CI_PIPELINE_TRIGGERED`	`${{ github.actions }}`
`CI_PIPELINE_URL`	`${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}`
`CI_PROJECT_DIR`	`${{ github.workspace }}`
`CI_PROJECT_ID`	`${{ github.repository }}`
`CI_PROJECT_NAME`	`${{ github.event.repository.name }}`
`CI_PROJECT_NAMESPACE`	`${{ github.repository_owner }}`
`CI_PROJECT_PATH_SLUG`	`${{ github.repository }}`
`CI_PROJECT_PATH`	`${{ github.repository }}`
`CI_PROJECT_ROOT_NAMESPACE`	`${{ github.repository_owner }}`
`CI_PROJECT_TITLE`	`${{ github.event.repository.full_name }}`
`CI_PROJECT_URL`	`${{ github.server_url }}/${{ github.repository }}`
`CI_REPOSITORY_URL`	`${{ github.event.repository.clone_url }}`
`CI_RUNNER_EXECUTABLE_ARCH`	`${{ runner.os }}`
`CI_SERVER_HOST`	`${{ github.server_url }}`
`CI_SERVER_URL`	`${{ github.server_url }}`
`CI_SERVER`	`${{ github.actions }}`
`GITLAB_CI`	`${{ github.actions }}`
`GITLAB_USER_EMAIL`	`${{ github.actor }}`
`GITLAB_USER_ID`	`${{ github.actor }}`
`GITLAB_USER_LOGIN`	`${{ github.actor }}`
`GITLAB_USER_NAME`	`${{ github.actor }}`
`TRIGGER_PAYLOAD`	`${{ github.event_path }}`
`CI_MERGE_REQUEST_ASSIGNEES`	`${{ github.event.pull_request.assignees }}`
`CI_MERGE_REQUEST_ID`	`${{ github.event.pull_request.number }}`
`CI_MERGE_REQUEST_IID`	`${{ github.event.pull_request.number }}`
`CI_MERGE_REQUEST_LABELS`	`${{ github.event.pull_request.labels }}`
`CI_MERGE_REQUEST_MILESTONE`	`${{ github.event.pull_request.milestone }}`
`CI_MERGE_REQUEST_PROJECT_ID`	`${{ github.repository }}`
`CI_MERGE_REQUEST_PROJECT_PATH`	`${{ github.repository }}`
`CI_MERGE_REQUEST_PROJECT_URL`	`${{ github.server_url }}/${{ github.repository }}`
`CI_MERGE_REQUEST_REF_PATH`	`${{ github.ref }}`
`CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`	`${{ github.event.pull_request.head.ref }}`
`CI_MERGE_REQUEST_SOURCE_BRANCH_SHA`	`${{ github.event.pull_request.head.sha}}`
`CI_MERGE_REQUEST_SOURCE_PROJECT_ID`	`${{ github.event.pull_request.head.repo.full_name }}`
`CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`	`${{ github.event.pull_request.head.repo.full_name }}`
`CI_MERGE_REQUEST_SOURCE_PROJECT_URL`	`${{ github.event.pull_request.head.repo.url }}`
`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`	`${{ github.event.pull_request.base.ref }}`
`CI_MERGE_REQUEST_TARGET_BRANCH_SHA`	`${{ github.event.pull_request.base.sha }}`
`CI_MERGE_REQUEST_TITLE`	`${{ github.event.pull_request.title }}`
`CI_EXTERNAL_PULL_REQUEST_IID`	`${{ github.event.pull_request.number }}`
`CI_EXTERNAL_PULL_REQUEST_SOURCE_REPOSITORY`	`${{ github.event.pull_request.head.repo.full_name }}`
`CI_EXTERNAL_PULL_REQUEST_TARGET_REPOSITORY`	`${{ github.event.pull_request.base.repo.full_name }}`
`CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME`	`${{ github.event.pull_request.head.ref }}`
`CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_SHA`	`${{ github.event.pull_request.head.sha }}`
`CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME`	`${{ github.event.pull_request.base.ref }}`
`CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_SHA`	`${{ github.event.pull_request.base.sha }}`

法務上の通知

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

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

この記事で