{"meta":{"title":"カスタム トランスフォーマーを使用した GitHub Actions Importer の拡張","intro":"GitHub Actions Importer は、組み込みのマッピングを拡張する機能を提供します。","product":"GitHub Actions","breadcrumbs":[{"href":"/ja/enterprise-cloud@latest/actions","title":"GitHub Actions"},{"href":"/ja/enterprise-cloud@latest/actions/reference","title":"リファレンス"},{"href":"/ja/enterprise-cloud@latest/actions/reference/github-actions-importer","title":"GitHub Actions Importer"},{"href":"/ja/enterprise-cloud@latest/actions/reference/github-actions-importer/custom-transformers","title":"カスタム トランスフォーマー"}],"documentType":"article"},"body":"# カスタム トランスフォーマーを使用した GitHub Actions Importer の拡張\n\nGitHub Actions Importer は、組み込みのマッピングを拡張する機能を提供します。\n\n## カスタム トランスフォーマーについて\n\nGitHub Actions Importer は、カスタム トランスフォーマーを作成することで、組み込みのマッピングを拡張する機能を提供します。 カスタム トランスフォーマーを使うと、次のことができます。\n\n* 自動的に変換されない GitHub Actions Importer 項目を変換したり、項目の変換方法を変更したりします。 詳細については、「[項目のカスタム トランスフォーマーの作成](#creating-custom-transformers-for-items)」を参照してください。\n* ランナーへの参照を変えて、異なるランナーラベルを使用する。 詳細については、「[ランナーのカスタム トランスフォーマーの作成](#creating-custom-transformers-for-runners)」を参照してください。\n* 環境変数の値を既存のパイプラインから GitHub Actions ワークフローに変換します。 詳細については、「[環境変数のカスタム トランスフォーマーの作成](#creating-custom-transformers-for-environment-variables)」を参照してください。\n\n## GitHub Actions Importer でカスタムトランスフォーマーを使用する\n\nカスタム トランスフォーマーには、 GitHub Actions Importer プラグイン、タスク、ランナー ラベル、または環境変数を変換して GitHub Actionsを操作するために使用できるマッピング ロジックが含まれています。 カスタム トランスフォーマーは、Ruby に基づいて構築されるドメイン固有言語 (DSL) を使って記述され、`.rb` ファイル拡張子を持つファイル内で定義されます。\n\n`--custom-transformers` CLI オプションを使うと、`audit`、`dry-run`、`migrate` コマンドで使うカスタム トランスフォーマー ファイルを指定できます。\n\nたとえば、カスタム トランスフォーマーが `transformers.rb` という名前のファイルで定義されている場合は、次のコマンドを使用して、 GitHub Actions Importerで使用できます。\n\n```shell\ngh actions-importer ... --custom-transformers transformers.rb\n```\n\nまたは、glob パターン構文を使って、複数のカスタム トランスフォーマー ファイルを指定することもできます。 たとえば、 `transformers`という名前のディレクトリ内に複数のカスタム トランスフォーマー ファイルがある場合は、次のコマンドを使用して、すべてを GitHub Actions Importer できます。\n\n```shell\ngh actions-importer ... --custom-transformers transformers/*.rb\n```\n\n> \\[!NOTE]\n> カスタム トランスフォーマーを使う場合、そのカスタム トランスフォーマーのファイルは、`gh actions-importer` コマンドの実行元と同じディレクトリ、またはサブディレクトリ内に存在している必要があります。\n\n## アイテムのカスタム トランスフォーマーの作成\n\n既存のビルドステップまたはトリガーを GitHub Actions Importer 内の対応するビルドステップまたはトリガーに変換するときに GitHub Actions が使用するカスタム トランスフォーマーを作成できます。 これは、次の場合に特に便利です。\n\n* GitHub Actions Importer は項目を自動的に変換しません。\n* GitHub Actions Importerによって項目を変換する方法を変更する必要があります。\n* 既存のパイプラインでは、Jenkins の共有ライブラリなどのカスタムまたは独自の拡張機能が使用されるため、 GitHub Actionsでこれらの手順がどのように機能するかを定義する必要があります。\n\nGitHub Actions Importer では、Ruby 上に構築された DSL を使用して定義されたカスタム トランスフォーマーが使用されます。 ビルド ステップとトリガー用のカスタム トランスフォーマーを作成するには:\n\n* 各カスタム トランスフォーマー ファイルには、少なくとも 1 つの `transform` メソッドを含める必要があります。\n* 各 `transform` メソッドは、`Hash`、`Hash` の配列、または `nil` を返す必要があります。 この戻り値は、YAML で定義されているアクションに対応します。 アクションの詳細については、「[GitHub Actionsについて](/ja/enterprise-cloud@latest/actions/get-started/understand-github-actions)」を参照してください。\n\n### ビルド ステップ用のカスタム トランスフォーマーの例\n\n次の例では、\"buildJavaScriptApp\" 識別子を使うビルド ステップを変換して、さまざまな `npm` コマンドを実行します。\n\n```ruby copy\ntransform \"buildJavaScriptApp\" do |item|\n  command = [\"build\", \"package\", \"deploy\"].map do |script|\n    \"npm run #{script}\"\n  end\n\n  {\n    name: \"build javascript app\",\n    run: command.join(\"\\n\")\n  }\nend\n```\n\n上記の例では、次の GitHub Actions ワークフロー ステップが作成されます。 これは、変換済みの `buildJavaScriptApp` 識別子を持っていたビルド ステップで構成されています。\n\n```yaml\n- name: build javascript app\n  run: |\n    npm run build\n    npm run package\n    npm run deploy\n```\n\n`transform` メソッドでは、ソース CI/CD インスタンスのビルド ステップの識別子を引数で使用します。 この例では、識別子は `buildJavaScriptLibrary` です。 コンマ区切りの値を使って、複数の識別子を `transform` メソッドに渡すこともできます。 たとえば、「 `transform \"buildJavaScriptApp\", \"buildTypeScriptApp\" { |item| ... }` 」のように入力します。\n\n> \\[!NOTE]\n> `item` のデータ構造は、CI/CD プラットフォームと変換される項目の種類によって異なります。\n\n## ランナーのカスタム トランスフォーマーの作成\n\nソース CI/CD インスタンス内のランナーと、それに対応する GitHub Actions ランナーとの対応付けをカスタマイズできます。\n\nGitHub Actions Importer では、Ruby 上に構築された DSL を使用して定義されたカスタム トランスフォーマーが使用されます。 ランナー用のカスタムトランスフォーマーを作成するには:\n\n* カスタム トランスフォーマー ファイルには、少なくとも 1 つの `runner` メソッドを含める必要があります。\n* `runner` メソッドには 2 つのパラメーターを指定できます。 最初のパラメーターはソース CI/CD インスタンスのランナー ラベルで、2 番目のパラメーターは対応する GitHub Actions ランナー ラベルです。\n  GitHub Actions ランナーの詳細については、「[GitHub ホステッド ランナー リファレンス](/ja/enterprise-cloud@latest/actions/reference/runners/github-hosted-runners#supported-runners-and-hardware-resources)」を参照してください。\n\n### ランナー用カスタムトランスフォーマーの例\n\n次の例は、結果のワークフローで 1 つのランナー ラベルを 1 つの`runner` ランナー ラベルに変換するGitHub Actions メソッドを示しています。\n\n```ruby copy\nrunner \"linux\", \"ubuntu-latest\"\n```\n\n`runner` メソッドを使用して、結果のワークフローで 1 つのランナー ラベルを複数のGitHub Actionsランナー ラベルに変換することもできます。\n\n```ruby copy\nrunner \"big-agent\", [\"self-hosted\", \"xl\", \"linux\"]\n```\n\nGitHub Actions Importer は、ランナー ラベルを可能な限りマップしようとします。 それができない場合は、`ubuntu-latest` ランナー ラベルが既定値として使用されます。\n`runner` メソッドで特別なキーワードを使うと、この既定値を制御できます。 たとえば、次のカスタム トランスフォーマーは、GitHub Actions Importerの代わりに既定のランナーとして`macos-latest`を使用するように`ubuntu-latest`に指示します。\n\n```ruby copy\nrunner :default, \"macos-latest\"\n```\n\n## 環境変数のカスタム トランスフォーマーの作成\n\nソース CI/CD パイプライン内の環境変数間のマッピングを、 GitHub Actions内の値にカスタマイズできます。\n\nGitHub Actions Importer では、Ruby 上に構築された DSL を使用して定義されたカスタム トランスフォーマーが使用されます。 環境変数のカスタム トランスフォーマーを作成するには:\n\n* カスタム トランスフォーマー ファイルには、少なくとも 1 つの `env` メソッドを含める必要があります。\n* `env` メソッドには 2 つのパラメーターを指定できます。 最初のパラメーターは元のパイプラインの環境変数の名前で、2 番目のパラメーターは GitHub Actionsの環境変数の更新された値です。\n  GitHub Actions環境変数の詳細については、[変数に情報を格納する](/ja/enterprise-cloud@latest/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables) を参照してください。\n\n### 環境変数のカスタム トランスフォーマーの例\n\n環境変数をマップするカスタム トランスフォーマーを設定するには、いくつかの方法があります。\n\n* 次の例では、`OCTO` という名前の既存の環境変数の値を、パイプラインの変換時に `CAT` に設定します。\n\n  ```ruby copy\n  env \"OCTO\", \"CAT\"\n  ```\n\n  特定の環境変数のすべてのインスタンスを削除して、 GitHub Actions ワークフローに変換されないようにすることもできます。 次の例では、`MONA_LISA` という名前のすべての環境変数を削除します。\n\n  ```ruby copy\n  env \"MONA_LISA\", nil\n  ```\n\n* 既存の環境変数をシークレットにマップすることもできます。 たとえば、次の `env` メソッドは、`MONALISA` という名前の環境変数を `OCTOCAT` という名前のシークレットにマップします。\n\n  ```ruby copy\n  env \"MONALISA\", secret(\"OCTOCAT\")\n  ```\n\n  これにより、変換されたワークフローでは `OCTOCAT` という名前のシークレットへの参照が設定されます。 シークレットを機能させるには、GitHub リポジトリにシークレットを作成する必要があります。 詳しくは、「[GitHub Actions でのシークレットの使用](/ja/enterprise-cloud@latest/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository)」をご覧ください。\n\n* 正規表現を使って、複数の環境変数の値を一度に更新することもできます。 たとえば、次のカスタム トランスフォーマーでは、変換されたワークフローからすべての環境変数を削除します。\n\n  ```ruby copy\n  env /.*/, nil\n  ```\n\n  次の例では、正規表現の一致グループを使って、環境変数の値を動的に生成されたシークレットに変換します。\n\n  ```ruby copy\n  env /^(.+)_SSH_KEY/, secret(\"%s_SSH_KEY)\n  ```\n\n  > \\[!NOTE]\n  > 各 `env` メソッドを定義する順序は、正規表現を使う場合に重要となります。 環境変数名と一致する最初の `env` トランスフォーマーは、後続の `env` メソッドよりも優先されます。 最も具体的な環境変数のトランスフォーマーを最初に定義する必要があります。\n\n## 法務上の通知\n\nMIT ライセンスのもとで <https://github.com/github/gh-actions-importer/> から一部を引用しています。\n\n```text\nMIT License\n\nCopyright (c) 2022 GitHub\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```"}