|
| 1 | +--- |
| 2 | +title: Extending GitHub Actions Importer with custom transformers |
| 3 | +intro: '{% data variables.product.prodname_actions_importer %} offers the ability to extend its built-in mapping.' |
| 4 | +versions: |
| 5 | + fpt: '*' |
| 6 | + ghec: '*' |
| 7 | + ghes: '*' |
| 8 | + ghae: '*' |
| 9 | +type: how_to |
| 10 | +topics: |
| 11 | + - Migration |
| 12 | + - CI |
| 13 | + - CD |
| 14 | +shortTitle: 'Extending GitHub Actions Importer' |
| 15 | +--- |
| 16 | + |
| 17 | +[Legal notice](#legal-notice) |
| 18 | + |
| 19 | +## About custom transformers |
| 20 | + |
| 21 | +{% data variables.product.prodname_actions_importer %} offers the ability to extend its built-in mapping by creating custom transformers. Custom transformers can be used to: |
| 22 | + |
| 23 | +- Convert items that {% data variables.product.prodname_actions_importer %} does not automatically convert, or modify how items are converted. For more information, see "[Creating custom transformers for items](#creating-custom-transformers-for-items)." |
| 24 | +- Convert references to runners to use different runner labels. For more information, see "[Creating custom transformers for runners](#creating-custom-transformers-for-runners)." |
| 25 | +- Convert environment variable values from your existing pipelines to {% data variables.product.prodname_actions %} workflows. For more information, see "[Creating custom transformers for environment variables](#creating-custom-transformers-for-environment-variables)." |
| 26 | + |
| 27 | +## Using custom transformers with {% data variables.product.prodname_actions_importer %} |
| 28 | + |
| 29 | +A custom transformer contains mapping logic that {% data variables.product.prodname_actions_importer %} can use to transform your plugins, tasks, runner labels, or environment variables to work with {% data variables.product.prodname_actions %}. Custom transformers are written with a domain-specific language (DSL) built on top of Ruby, and are defined within a file with the `.rb` file extension. |
| 30 | + |
| 31 | +You can use the `--custom-transformers` CLI option to specify which custom transformer files to use with the `audit`, `dry-run`, and `migrate` commands. |
| 32 | + |
| 33 | +For example, if custom transformers are defined in a file named `transformers.rb`, you can use the following command to use them with {% data variables.product.prodname_actions_importer %}: |
| 34 | + |
| 35 | +``` |
| 36 | +gh actions-importer ... --custom-transformers transformers.rb |
| 37 | +``` |
| 38 | + |
| 39 | +Alternatively, you can use the glob pattern syntax to specify multiple custom transformer files. For example, if multiple custom transformer files are within a directory named `transformers`, you can provide them all to {% data variables.product.prodname_actions_importer %} with the following command: |
| 40 | + |
| 41 | +``` |
| 42 | +gh actions-importer ... --custom-transformers transformers/*.rb |
| 43 | +``` |
| 44 | + |
| 45 | +{% note %} |
| 46 | + |
| 47 | +**Note:** When you use custom transformers, the custom transformer files must reside in the same directory, or in subdirectores, from where the `gh actions-importer` command is run. |
| 48 | + |
| 49 | +{% endnote %} |
| 50 | + |
| 51 | +## Creating custom transformers for items |
| 52 | + |
| 53 | +You can create custom transformers that {% data variables.product.prodname_actions_importer %} will use when converting existing build steps or triggers to their equivalent in {% data variables.product.prodname_actions %}. This is especially useful when: |
| 54 | + |
| 55 | +- {% data variables.product.prodname_actions_importer %} doesn't automatically convert an item. |
| 56 | +- You want to change how an item is converted by {% data variables.product.prodname_actions_importer %}. |
| 57 | +- Your existing pipelines use custom or proprietary extensions, such as shared libraries in Jenkins, and you need to define how these steps should function in {% data variables.product.prodname_actions %}. |
| 58 | + |
| 59 | +{% data variables.product.prodname_actions_importer %} uses custom transformers that are defined using a DSL built on top of Ruby. In order to create custom transformers for build steps and triggers: |
| 60 | + |
| 61 | +- Each custom transformer file must contain at least one `transform` method. |
| 62 | +- Each `transform` method must return a `Hash`, an array of `Hash`'s, or `nil`. This returned value will correspond to an action defined in YAML. For more information about actions, see "[AUTOTITLE](/actions/learn-github-actions/understanding-github-actions)." |
| 63 | + |
| 64 | +### Example custom transformer for a build step |
| 65 | + |
| 66 | +The following example converts a build step that uses the "buildJavascriptApp" identifier to run various `npm` commands: |
| 67 | + |
| 68 | +```ruby{:copy} |
| 69 | +transform "buildJavascriptApp" do |item| |
| 70 | + command = ["build", "package", "deploy"].map do |script| |
| 71 | + "npm run #{script}" |
| 72 | + end |
| 73 | +
|
| 74 | + { |
| 75 | + name: "build javascript app", |
| 76 | + run: command.join("\n") |
| 77 | + } |
| 78 | +end |
| 79 | +``` |
| 80 | + |
| 81 | +The above example results in the following {% data variables.product.prodname_actions %} workflow step. It is comprised of converted build steps that had a `buildJavascriptApp` identifier: |
| 82 | + |
| 83 | +```yaml |
| 84 | +- name: build javascript app |
| 85 | + run: | |
| 86 | + npm run build |
| 87 | + npm run package |
| 88 | + npm run deploy |
| 89 | +``` |
| 90 | +
|
| 91 | +The `transform` method uses the identifier of the build step from your source CI/CD instance in an argument. In this example, the identifier is `buildJavascriptLibrary`. You can also use comma-separated values to pass multiple identifiers to the `transform` method. For example, `transform "buildJavascriptApp", "buildTypescriptApp" { |item| ... }`. |
| 92 | + |
| 93 | +{% note %} |
| 94 | + |
| 95 | +**Note**: The data structure of `item` will be different depending on the CI/CD platform and the type of item being converted. |
| 96 | + |
| 97 | +{% endnote %} |
| 98 | + |
| 99 | +## Creating custom transformers for runners |
| 100 | + |
| 101 | +You can customize the mapping between runners in your source CI/CD instance and their equivalent {% data variables.product.prodname_actions %} runners. |
| 102 | + |
| 103 | +{% data variables.product.prodname_actions_importer %} uses custom transformers that are defined using a DSL built on top of Ruby. To create custom transformers for runners: |
| 104 | + |
| 105 | +- The custom transformer file must have at least one `runner` method. |
| 106 | +- The `runner` method accepts two parameters. The first parameter is the source CI/CD instance's runner label, and the second parameter is the corresponding {% data variables.product.prodname_actions %} runner label. {% ifversion not ghae %}For more information on {% data variables.product.prodname_actions %} runners, see "[AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)."{% endif %} |
| 107 | + |
| 108 | +### Example custom transformers for runners |
| 109 | + |
| 110 | +The following example shows a `runner` method that converts one runner label to one {% data variables.product.prodname_actions %} runner label in the resulting workflow. |
| 111 | + |
| 112 | +```ruby{:copy} |
| 113 | +runner "linux", "ubuntu-latest" |
| 114 | +``` |
| 115 | + |
| 116 | +You can also use the `runner` method to convert one runner label to multiple {% data variables.product.prodname_actions %} runner labels in the resulting workflow. |
| 117 | + |
| 118 | +```ruby{:copy} |
| 119 | +runner "big-agent", ["self-hosted", "xl", "linux"] |
| 120 | +``` |
| 121 | + |
| 122 | +{% data variables.product.prodname_actions_importer %} attempts to map the runner label as best it can. In cases where it cannot do this, the `ubuntu-latest` runner label is used as a default. You can use a special keyword with the `runner` method to control this default value. For example, the following custom transformer instructs {% data variables.product.prodname_actions_importer %} to use `macos-latest` as the default runner instead of `ubuntu-latest`. |
| 123 | + |
| 124 | +```ruby{:copy} |
| 125 | +runner :default, "macos-latest" |
| 126 | +``` |
| 127 | + |
| 128 | +## Creating custom transformers for environment variables |
| 129 | + |
| 130 | +You can customize the mapping between environment variables in your source CI/CD pipelines to their values in {% data variables.product.prodname_actions %}. |
| 131 | + |
| 132 | +{% data variables.product.prodname_actions_importer %} uses custom transformers that are defined using a DSL built on top of Ruby. To create custom transformers for environment variables: |
| 133 | + |
| 134 | +- The custom transformer file must have at least one `env` method. |
| 135 | +- The `env` method accepts two parameters. The first parameter is the name of the environment variable in the original pipeline, and the second parameter is the updated value for the environment variable for {% data variables.product.prodname_actions %}. For more information about {% data variables.product.prodname_actions %} environment variables, see "[AUTOTITLE](/actions/learn-github-actions/variables)." |
| 136 | + |
| 137 | +### Example custom transformers for environment variables |
| 138 | + |
| 139 | +There are several ways you can set up custom transformers to map your environment variables. |
| 140 | + |
| 141 | +- The following example sets the value of any existing environment variables named `OCTO`, to `CAT` when transforming a pipeline. |
| 142 | + |
| 143 | + ```ruby{:copy} |
| 144 | + env "OCTO", "CAT" |
| 145 | + ``` |
| 146 | + |
| 147 | + You can also remove all instances of a specific environment variable so they are not transformed to an {% data variables.product.prodname_actions %} workflow. The following example removes all environment variables with the name `MONA_LISA`. |
| 148 | + |
| 149 | + ```ruby{:copy} |
| 150 | + env "MONA_LISA", nil |
| 151 | + ``` |
| 152 | + |
| 153 | +- You can also map your existing environment variables to secrets. For example, the following `env` method maps an environment variable named `MONALISA` to a secret named `OCTOCAT`. |
| 154 | + |
| 155 | + ```ruby{:copy} |
| 156 | + env "MONALISA", secret("OCTOCAT") |
| 157 | + ``` |
| 158 | + |
| 159 | + This will set up a reference to a secret named `OCTOCAT` in the transformed workflow. For the secret to work, you will need to create the secret in your GitHub repository. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)." |
| 160 | + |
| 161 | +- You can also use regular expressions to update the values of multiple environment variables at once. For example, the following custom transformer removes all environment variables from the converted workflow: |
| 162 | + |
| 163 | + ```ruby{:copy} |
| 164 | + env /.*/, nil |
| 165 | + ``` |
| 166 | + |
| 167 | + The following example uses a regular expression match group to transform environment variable values to dynamically generated secrets. |
| 168 | + |
| 169 | + ```ruby{:copy} |
| 170 | + env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY) |
| 171 | + ``` |
| 172 | + |
| 173 | + {% note %} |
| 174 | + |
| 175 | + **Note**: The order in which `env` methods are defined matters when using regular expressions. The first `env` transformer that matches an environment variable name takes precedence over subsequent `env` methods. You should define your most specific environment variable transformers first. |
| 176 | + |
| 177 | + {% endnote %} |
| 178 | + |
| 179 | +## Legal notice |
| 180 | + |
| 181 | +{% data reusables.actions.actions-importer-legal-notice %} |
0 commit comments