カスタムトランスフォーマーを使用した GitHub Actions Importer の拡張

カスタムトランスフォーマーについて

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 コマンドを実行します。

Ruby

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 ランナーについては、「[AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)」を参照してください。

ランナー用カスタムトランスフォーマーの例

次の例は、1 つのランナーラベルを、結果のワークフローで 1 つの GitHub Actions のランナーラベルに変換する runner メソッドを示しています。

Ruby

runner "linux", "ubuntu-latest"

runner "linux", "ubuntu-latest"

また、runner メソッドを使って、1 つのランナーラベルを、結果のワークフローで GitHub Actions の複数のランナーラベルに変換することもできます。

Ruby

runner "big-agent", ["self-hosted", "xl", "linux"]

runner "big-agent", ["self-hosted", "xl", "linux"]

GitHub Actions Importer は、ランナーラベルをできるだけ最適にマップしようとします。それができない場合は、ubuntu-latest ランナーラベルが既定値として使用されます。 runner メソッドで特別なキーワードを使うと、この既定値を制御できます。たとえば、次のカスタムトランスフォーマーでは、macos-latest ではなく ubuntu-latest を既定のランナーとして使うように GitHub Actions Importer に指示します。

Ruby

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 環境変数の詳細については、「[AUTOTITLE](/actions/learn-github-actions/variables)」を参照してください。

環境変数のカスタムトランスフォーマーの例

環境変数をマップするカスタムトランスフォーマーを設定するには、いくつかの方法があります。

次の例では、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 メソッドよりも優先されます。最も具体的な環境変数のトランスフォーマーを最初に定義する必要があります。

法務上の通知

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

カスタム トランスフォーマーを使用した GitHub Actions Importer の拡張

この記事で

カスタムトランスフォーマーを使用した GitHub Actions Importer の拡張