|
| 1 | +--- |
| 2 | +title: Automating migration with GitHub Actions Importer |
| 3 | +intro: 'Use {% data variables.product.prodname_actions_importer %} to plan and automate your migration to {% data variables.product.prodname_actions %}.' |
| 4 | +versions: |
| 5 | + fpt: '*' |
| 6 | + ghec: '*' |
| 7 | + ghes: '*' |
| 8 | + ghae: '*' |
| 9 | +type: how_to |
| 10 | +miniTocMaxHeadingLevel: 3 |
| 11 | +topics: |
| 12 | + - Migration |
| 13 | + - CI |
| 14 | + - CD |
| 15 | +shortTitle: Automate migration with {% data variables.product.prodname_actions_importer %} |
| 16 | +--- |
| 17 | + |
| 18 | +{% data reusables.actions.enterprise-beta %} |
| 19 | +{% data reusables.actions.enterprise-github-hosted-runners %} |
| 20 | + |
| 21 | +[Legal notice](#legal-notice) |
| 22 | + |
| 23 | +{% note %} |
| 24 | + |
| 25 | +**Note**: {% data variables.product.prodname_actions_importer %} is currently available as a public preview. Visit the [sign up page](https://github.com/features/actions-importer/signup) to request access to the preview. Once you are granted access you'll be able to use the `gh-actions-importer` CLI extension |
| 26 | + |
| 27 | +{% endnote %} |
| 28 | + |
| 29 | +## About {% data variables.product.prodname_actions_importer %} |
| 30 | + |
| 31 | +You can use {% data variables.product.prodname_actions_importer %} to plan and automatically migrate your CI/CD pipelines to {% data variables.product.prodname_actions %} from Azure DevOps, CircleCI, GitLab, Jenkins, and Travis CI. |
| 32 | + |
| 33 | +{% data variables.product.prodname_actions_importer %} is distributed as a Docker container, and uses a [{% data variables.product.prodname_dotcom %} CLI](https://cli.github.com) extension to interact with the container. |
| 34 | + |
| 35 | +Any workflow that is converted by the {% data variables.product.prodname_actions_importer %} should be inspected for correctness before using it as a production workload. The goal is to achieve an 80% conversion rate for every workflow, however, the actual conversion rate will depend on the makeup of each individual pipeline that is converted. |
| 36 | + |
| 37 | +## Supported CI platforms |
| 38 | + |
| 39 | +You can use {% data variables.product.prodname_actions_importer %} to migrate from the following platforms: |
| 40 | + |
| 41 | +- Azure DevOps |
| 42 | +- CircleCI |
| 43 | +- GitLab |
| 44 | +- Jenkins |
| 45 | +- Travis CI |
| 46 | + |
| 47 | +Once you are granted access to the preview, you will be able to access further reference documentation for each of the supported platforms. |
| 48 | + |
| 49 | +## Prerequisites |
| 50 | + |
| 51 | +{% data variables.product.prodname_actions_importer %} has the following requirements: |
| 52 | + |
| 53 | +- You must have been granted access to the public preview for the {% data variables.product.prodname_actions_importer %}. |
| 54 | +{%- ifversion ghes < 3.5 or ghae %} |
| 55 | +- Use a {% data variables.product.pat_generic %} with the `read:packages` scope enabled. |
| 56 | +{%- else %} |
| 57 | +- You must have credentials to authenticate to the {% data variables.product.prodname_registry %} {% data variables.product.prodname_container_registry %}. For more information, see "[Working with the Container registry](/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry)." |
| 58 | +{% endif %} |
| 59 | +- An environment where you can run Linux-based containers, and can install the necessary tools. |
| 60 | + - Docker is [installed](https://docs.docker.com/get-docker/) and running. |
| 61 | + - [{% data variables.product.prodname_dotcom %} CLI](https://cli.github.com) is installed. |
| 62 | + |
| 63 | + {% note %} |
| 64 | + |
| 65 | + **Note**: The {% data variables.product.prodname_actions_importer %} container and CLI do not need to be installed on the same server as your CI platform. |
| 66 | + |
| 67 | + {% endnote %} |
| 68 | + |
| 69 | +### Installing the {% data variables.product.prodname_actions_importer %} CLI extension |
| 70 | + |
| 71 | +1. Install the {% data variables.product.prodname_actions_importer %} CLI extension: |
| 72 | + |
| 73 | + ```bash |
| 74 | + $ gh extension install github/gh-actions-importer |
| 75 | + ``` |
| 76 | +1. Verify that the extension is installed: |
| 77 | + |
| 78 | + ```bash |
| 79 | + $ gh actions-importer -h |
| 80 | + Options: |
| 81 | + -?, -h, --help Show help and usage information |
| 82 | + |
| 83 | + Commands: |
| 84 | + update Update to the latest version of the GitHub Actions Importer. |
| 85 | + version Display the version of the GitHub Actions Importer. |
| 86 | + configure Start an interactive prompt to configure credentials used to authenticate with your CI server(s). |
| 87 | + audit Plan your CI/CD migration by analyzing your current CI/CD footprint. |
| 88 | + forecast Forecast GitHub Actions usage from historical pipeline utilization. |
| 89 | + dry-run Convert a pipeline to a GitHub Actions workflow and output its yaml file. |
| 90 | + migrate Convert a pipeline to a GitHub Actions workflow and open a pull request with the changes. |
| 91 | + ``` |
| 92 | + |
| 93 | +### Updating the {% data variables.product.prodname_actions_importer %} CLI |
| 94 | + |
| 95 | +To ensure you're running the latest version of {% data variables.product.prodname_actions_importer %}, you should regularly run the `update` command: |
| 96 | + |
| 97 | +```bash |
| 98 | +$ gh actions-importer update |
| 99 | +``` |
| 100 | + |
| 101 | +You must be authenticated with the {% data variables.product.prodname_container_registry %} for this command to be successful. Alternatively, you can provide credentials using the `--username` and `--password-stdin` parameters: |
| 102 | + |
| 103 | +```bash |
| 104 | +$ echo $GITHUB_TOKEN | gh actions-importer update --username $GITHUB_HANDLE --password-stdin |
| 105 | +``` |
| 106 | + |
| 107 | +### Authenticating at the command line |
| 108 | + |
| 109 | +You must configure credentials that allow {% data variables.product.prodname_actions_importer %} to communicate with {% data variables.product.prodname_dotcom %} and your current CI server. You can configure these credentials using environment variables or a `.env.local` file. The environment variables can be configured in an interactive prompt, by running the following command: |
| 110 | + |
| 111 | +```bash |
| 112 | +$ gh actions-importer configure |
| 113 | +``` |
| 114 | + |
| 115 | +Once you are granted access to the preview, you will be able to access further reference documentation about using environment variables. |
| 116 | + |
| 117 | +## Using the {% data variables.product.prodname_actions_importer %} CLI |
| 118 | + |
| 119 | +Use the subcommands of `gh actions-importer` to begin your migration to {% data variables.product.prodname_actions %}, including `audit`, `forecast`, `dry-run`, and `migrate`. |
| 120 | + |
| 121 | +### Auditing your existing CI pipelines |
| 122 | + |
| 123 | +The `audit` subcommand can be used to plan your CI/CD migration by analyzing your current CI/CD footprint. This analysis can be used to plan a timeline for migrating to {% data variables.product.prodname_actions %}. |
| 124 | + |
| 125 | +To run an audit, use the following command to determine your available options: |
| 126 | + |
| 127 | +```bash |
| 128 | +$ gh actions-importer audit -h |
| 129 | +Description: |
| 130 | + Plan your CI/CD migration by analyzing your current CI/CD footprint. |
| 131 | + |
| 132 | +[...] |
| 133 | + |
| 134 | +Commands: |
| 135 | + azure-devops An audit will output a list of data used in an Azure DevOps instance. |
| 136 | + circle-ci An audit will output a list of data used in a CircleCI instance. |
| 137 | + gitlab An audit will output a list of data used in a GitLab instance. |
| 138 | + jenkins An audit will output a list of data used in a Jenkins instance. |
| 139 | + travis-ci An audit will output a list of data used in a Travis CI instance. |
| 140 | +``` |
| 141 | + |
| 142 | +Once you are granted access to the preview, you will be able to access further reference documentation about running an audit. |
| 143 | + |
| 144 | +### Forecasting usage |
| 145 | + |
| 146 | +The `forecast` subcommand reviews historical pipeline usage to create a forecast of {% data variables.product.prodname_actions %} usage. |
| 147 | + |
| 148 | +To run a forecast, use the following command to determine your available options: |
| 149 | + |
| 150 | +```bash |
| 151 | +$ gh actions-importer forecast -h |
| 152 | +Description: |
| 153 | + Forecasts GitHub Actions usage from historical pipeline utilization. |
| 154 | + |
| 155 | +[...] |
| 156 | + |
| 157 | +Commands: |
| 158 | + azure-devops Forecasts GitHub Actions usage from historical Azure DevOps pipeline utilization. |
| 159 | + jenkins Forecasts GitHub Actions usage from historical Jenkins pipeline utilization. |
| 160 | + gitlab Forecasts GitHub Actions usage from historical GitLab pipeline utilization. |
| 161 | + circle-ci Forecasts GitHub Actions usage from historical CircleCI pipeline utilization. |
| 162 | + travis-ci Forecasts GitHub Actions usage from historical Travis CI pipeline utilization. |
| 163 | + github Forecasts GitHub Actions usage from historical GitHub pipeline utilization. |
| 164 | +``` |
| 165 | + |
| 166 | +Once you are granted access to the preview, you will be able to access further reference documentation about running a forecast. |
| 167 | + |
| 168 | +### Testing the migration process |
| 169 | + |
| 170 | +The `dry-run` subcommand can be used to convert a pipeline to its {% data variables.product.prodname_actions %} equivalent, and then write the workflow to your local filesystem. |
| 171 | + |
| 172 | +To perform a dry run, use the following command to determine your available options: |
| 173 | + |
| 174 | +```bash |
| 175 | +$ gh actions-importer dry-run -h |
| 176 | +Description: |
| 177 | + Convert a pipeline to a GitHub Actions workflow and output its yaml file. |
| 178 | + |
| 179 | +[...] |
| 180 | + |
| 181 | +Commands: |
| 182 | + azure-devops Convert an Azure DevOps pipeline to a GitHub Actions workflow and output its yaml file. |
| 183 | + circle-ci Convert a CircleCI pipeline to GitHub Actions workflows and output the yaml file(s). |
| 184 | + gitlab Convert a GitLab pipeline to a GitHub Actions workflow and output the yaml file. |
| 185 | + jenkins Convert a Jenkins job to a GitHub Actions workflow and output its yaml file. |
| 186 | + travis-ci Convert a Travis CI pipeline to a GitHub Actions workflow and output its yaml file. |
| 187 | +``` |
| 188 | + |
| 189 | +Once you are granted access to the preview, you will be able to access further reference documentation about performing a dry run. |
| 190 | + |
| 191 | +### Migrating a pipeline to {% data variables.product.prodname_actions %} |
| 192 | + |
| 193 | +The `migrate` subcommand can be used to convert a pipeline to its GitHub Actions equivalent and then create a pull request with the contents. |
| 194 | + |
| 195 | +To run a migration, use the following command to determine your available options: |
| 196 | + |
| 197 | +```bash |
| 198 | +$ gh actions-importer migrate -h |
| 199 | +Description: |
| 200 | + Convert a pipeline to a GitHub Actions workflow and open a pull request with the changes. |
| 201 | + |
| 202 | +[...] |
| 203 | + |
| 204 | +Commands: |
| 205 | + azure-devops Convert an Azure DevOps pipeline to a GitHub Actions workflow and open a pull request with the changes. |
| 206 | + circle-ci Convert a CircleCI pipeline to GitHub Actions workflows and open a pull request with the changes. |
| 207 | + gitlab Convert a GitLab pipeline to a GitHub Actions workflow and open a pull request with the changes. |
| 208 | + jenkins Convert a Jenkins job to a GitHub Actions workflow and open a pull request with the changes. |
| 209 | + travis-ci Convert a Travis CI pipeline to a GitHub Actions workflow and and open a pull request with the changes. |
| 210 | +``` |
| 211 | + |
| 212 | +Once you are granted access to the preview, you will be able to access further reference documentation about running a migration. |
| 213 | + |
| 214 | +## Legal notice |
| 215 | + |
| 216 | +Portions have been adapted from https://github.com/github/gh-actions-importer/ under the MIT license: |
| 217 | + |
| 218 | +``` |
| 219 | +MIT License |
| 220 | +
|
| 221 | +Copyright (c) 2022 GitHub |
| 222 | +
|
| 223 | +Permission is hereby granted, free of charge, to any person obtaining a copy |
| 224 | +of this software and associated documentation files (the "Software"), to deal |
| 225 | +in the Software without restriction, including without limitation the rights |
| 226 | +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| 227 | +copies of the Software, and to permit persons to whom the Software is |
| 228 | +furnished to do so, subject to the following conditions: |
| 229 | +
|
| 230 | +The above copyright notice and this permission notice shall be included in all |
| 231 | +copies or substantial portions of the Software. |
| 232 | +
|
| 233 | +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 234 | +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 235 | +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 236 | +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 237 | +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 238 | +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
| 239 | +SOFTWARE. |
| 240 | +``` |
0 commit comments