カスタム トランスフォーマーについて
GitHub Actions Importer では、カスタム トランスフォーマーを作成することで組み込みのマッピングを拡張できます。 カスタム トランスフォーマーを使うと、次のことができます。
- GitHub Actions Importer が自動的に変換しない項目を変換したり、項目の変換方法を変更したりする。 詳しくは、「項目のカスタム トランスフォーマーの作成」を参照してください。
- ランナーへの参照を変換して、異なるランナー ラベルを使用する。 詳しくは、「ランナーのカスタム トランスフォーマーの作成」を参照してください。
- 環境変数の値を既存のパイプラインから GitHub Actions ワークフローに変換する。 詳しくは、「環境変数のカスタム トランスフォーマーの作成」を参照してください。
GitHub Actions Importer でのカスタム トランスフォーマーの使用
カスタム トランスフォーマーには、GitHub Actions Importer がプラグイン、タスク、ランナーのラベル、または環境変数を GitHub Actions で動作するように変換するために使えるマッピング ロジックが含まれています。 カスタム トランスフォーマーは、Ruby に基づいて構築されるドメイン固有言語 (DSL) を使って記述され、.rb
ファイル拡張子を持つファイル内で定義されます。
--custom-transformers
CLI オプションを使うと、audit
、dry-run
、migrate
コマンドで使うカスタム トランスフォーマー ファイルを指定できます。
たとえば、transformers.rb
という名前のファイルにカスタム トランスフォーマーが定義されている場合は、次のコマンドを使うことでそれらを GitHub Actions Importer で使用できます。
gh actions-importer ... --custom-transformers transformers.rb
または、glob パターン構文を使って、複数のカスタム トランスフォーマー ファイルを指定することもできます。 たとえば、transformers
という名前のディレクトリ内に複数のカスタム トランスフォーマー ファイルがある場合は、次のコマンドを使ってそれらすべてを GitHub Actions Importer に指定できます。
gh actions-importer ... --custom-transformers transformers/*.rb
注: カスタム トランスフォーマーを使う場合、そのカスタム トランスフォーマーのファイルは、gh actions-importer
コマンドの実行元と同じディレクトリ、またはサブディレクトリ内に存在している必要があります。
項目のカスタム トランスフォーマーの作成
既存のビルド ステップまたはトリガーを、GitHub Actions でそれに相当するものに変換するときに GitHub Actions Importer が使う、カスタム トランスフォーマーを作成できます。 これは、次の場合に特に便利です。
- GitHub Actions Importer が自動的に項目を変換しない。
- GitHub Actions Importer による項目の変換方法を変更したい。
- 既存のパイプラインでカスタムまたは独自の拡張機能が使用されており (Jenkins の共有ライブラリなど)、これらのステップが GitHub Actions でどのように機能するかを定義する必要がある。
GitHub Actions Importer では、Ruby に基づいて構築される DSL を使って定義されたカスタム トランスフォーマーが使用されます。 ビルド ステップとトリガー用のカスタム トランスフォーマーを作成するには:
- 各カスタム トランスフォーマー ファイルには、少なくとも 1 つの
transform
メソッドを含める必要があります。 - 各
transform
メソッドは、Hash
、Hash
の配列、またはnil
を返す必要があります。 この戻り値は、YAML で定義されているアクションに対応します。 アクションについて詳しくは、「GitHub Actions を理解する」を参照してください。
ビルド ステップ用のカスタム トランスフォーマーの例
次の例では、"buildJavaScriptApp" 識別子を使うビルド ステップを変換して、さまざまな npm
コマンドを実行します。
transform "buildJavaScriptApp" do |item| command = ["build", "package", "deploy"].map do |script| "npm run #{script}" end { name: "build javascript app", run: command.join("\n") } end
transform "buildJavaScriptApp" do |item|
command = ["build", "package", "deploy"].map do |script|
"npm run #{script}"
end
{
name: "build javascript app",
run: command.join("\n")
}
end
上記の例では、次の GitHub Actions ワークフロー ステップが生成されます。 これは、変換済みの buildJavaScriptApp
識別子を持っていたビルド ステップで構成されています。
- name: build javascript app
run: |
npm run build
npm run package
npm run deploy
transform
メソッドでは、ソース CI/CD インスタンスのビルド ステップの識別子を引数で使用します。 この例では、識別子は buildJavaScriptLibrary
です。 コンマ区切りの値を使って、複数の識別子を transform
メソッドに渡すこともできます。 たとえば、transform "buildJavaScriptApp", "buildTypeScriptApp" { |item| ... }
のようにします。
注: item
のデータ構造は、CI/CD プラットフォームと変換される項目の種類によって異なります。
ランナーのカスタム トランスフォーマーの作成
ソース CI/CD インスタンス内のランナーと、それらに相当する GitHub Actions のランナー間のマッピングをカスタマイズできます。
GitHub Actions Importer では、Ruby に基づいて構築される DSL を使って定義されたカスタム トランスフォーマーが使用されます。 ランナーのカスタム トランスフォーマーを作成するには:
- カスタム トランスフォーマー ファイルには、少なくとも 1 つの
runner
メソッドを含める必要があります。 runner
メソッドには 2 つのパラメーターを指定できます。 最初のパラメーターはソース CI/CD インスタンスのランナーのラベルで、2 番目のパラメーターは対応する GitHub Actions のランナーのラベルです。 GitHub Actions ランナーについて詳しくは、「GitHub ホステッド ランナーの使用」をご覧ください。
ランナーのカスタム トランスフォーマーの例
次の例は、1 つのランナー ラベルを、結果のワークフローで 1 つの GitHub Actions のランナー ラベルに変換する runner
メソッドを示しています。
runner "linux", "ubuntu-latest"
runner "linux", "ubuntu-latest"
また、runner
メソッドを使って、1 つのランナー ラベルを、結果のワークフローで GitHub Actions の複数のランナー ラベルに変換することもできます。
runner "big-agent", ["self-hosted", "xl", "linux"]
runner "big-agent", ["self-hosted", "xl", "linux"]
GitHub Actions Importer は、ランナー ラベルをできるだけ最適にマップしようとします。 それができない場合は、ubuntu-latest
ランナー ラベルが既定値として使用されます。 runner
メソッドで特別なキーワードを使うと、この既定値を制御できます。 たとえば、次のカスタム トランスフォーマーでは、ubuntu-latest
ではなく macos-latest
を既定のランナーとして使うように GitHub Actions Importer に指示します。
runner :default, "macos-latest"
runner :default, "macos-latest"
環境変数のカスタム トランスフォーマーの作成
ソース CI/CD パイプライン内の環境変数から、それらの GitHub Actions での値へのマッピングをカスタマイズできます。
GitHub Actions Importer では、Ruby に基づいて構築される DSL を使って定義されたカスタム トランスフォーマーが使用されます。 環境変数のカスタム トランスフォーマーを作成するには:
- カスタム トランスフォーマー ファイルには、少なくとも 1 つの
env
メソッドを含める必要があります。 env
メソッドには 2 つのパラメーターを指定できます。 最初のパラメーターは元のパイプラインの環境変数の名前で、2 番目のパラメーターは GitHub Actions 用に更新された環境変数の値です。 GitHub Actions 環境変数について詳しくは、「変数に情報を格納する」を参照してください。
環境変数のカスタム トランスフォーマーの例
環境変数をマップするカスタム トランスフォーマーを設定するには、いくつかの方法があります。
-
次の例では、
OCTO
という名前の既存の環境変数の値を、パイプラインの変換時にCAT
に設定します。Ruby env "OCTO", "CAT"
env "OCTO", "CAT"
特定の環境変数の出現箇所をすべて削除して、GitHub Actions ワークフローに変換されないようにすることもできます。 次の例では、
MONA_LISA
という名前のすべての環境変数を削除します。Ruby env "MONA_LISA", nil
env "MONA_LISA", nil
-
既存の環境変数をシークレットにマップすることもできます。 たとえば、次の
env
メソッドは、MONALISA
という名前の環境変数をOCTOCAT
という名前のシークレットにマップします。Ruby env "MONALISA", secret("OCTOCAT")
env "MONALISA", secret("OCTOCAT")
これにより、変換されたワークフローでは
OCTOCAT
という名前のシークレットへの参照が設定されます。 このシークレットを機能させるには、GitHub リポジトリにシークレットを作成する必要があります。 詳しくは、「GitHub Actions でのシークレットの使用」を参照してください。 -
正規表現を使って、複数の環境変数の値を一度に更新することもできます。 たとえば、次のカスタム トランスフォーマーでは、変換されたワークフローからすべての環境変数を削除します。
Ruby env /.*/, nil
env /.*/, nil
次の例では、正規表現の一致グループを使って、環境変数の値を動的に生成されたシークレットに変換します。
Ruby env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY)
env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY)
注: 各
env
メソッドを定義する順序は、正規表現を使う場合に重要となります。 環境変数名と一致する最初のenv
トランスフォーマーは、後続のenv
メソッドよりも優先されます。 最も具体的な環境変数のトランスフォーマーを最初に定義する必要があります。
法的通知
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.