Interested in bringing GitHub Enterprise to your organization?
Start your free trial for 30 days and increase your team’s collaboration. $21 per user/month after trial expires.
Curious about other plans?
We’re excited to announce a public preview of GitHub Actions Importer, which helps you forecast, plan, and facilitate migrations from your current CI/CD tool to GitHub Actions.
Doing individual migrations is relatively easy in isolation. However, for companies that have a large and established CI/CD footprint, having tooling available to assist with migrations is key to their ability to adopt Actions at scale. In the time that we’ve been developing and using GitHub Actions Importer in its private preview form, we’ve already encountered numerous customers that have thousands of pipelines—even in excess of 15K—in their legacy environments that need to be migrated. GitHub Actions Importer is designed to help when manual migration is not feasible, such as when customers have a large number of teams that depend on hundreds or thousands of workflows.
Using GitHub Actions Importer to facilitate a migration to Actions can be conceptualized in distinct phases.
A migration typically starts with an analysis of your existing CI/CD usage and approach, which includes addressing such questions as:
Once you begin your migration efforts, you can expect that a small subset of migrated workflows will require manual work to complete. Although the actual conversion rate for a customer will depend on the makeup of each individual pipeline, in practice we’ve found that, on average, GitHub Actions Importer can successfully convert in excess of 90% of the tasks and constructs used in a workflow.
To finalize your migration, you should plan to iterate on the new GitHub Actions workflow to validate that it functions equivalently to the existing pipeline and that constructs that could not be migrated automatically are implemented. This could include—but is not limited to—configuring secrets, self-hosted runners, environments, and branch protection rules. In addition, if you were using any custom tasks or less commonly used public tasks, you will need to port or re-implement that logic manually.
The user interface for GitHub Actions Importer is an extension to the official GitHub CLI, which delegates to a Docker container. When you get access to GitHub Actions Importer, have installed it and the GitHub CLI, and are ready to try it in your own environment, you’ll typically want to take the following steps.
GitHub Actions Importer provides an
audit command that is designed to help analyze the complexity of a potential migration, which can be used to formulate a migration plan. This command will fetch all of the pipelines defined in a specified scope of the existing CI/CD environment, attempt a conversion of these pipelines to their equivalent workflow, and write a summary report with statistics gathered from the audit.
Running an audit on the command line will look something like this:
$ gh actions-importer audit jenkins --output-dir .
The Audit summary report provides details aggregated at the pipeline level, aggregated at the build step level, and identifies manual migration tasks that will need to be completed.
This section contains high-level aggregated statistics on GitHub Actions Importer’s ability to migrate the targeted pipeline automatically.
The Pipelines section provides the following key metrics:
The Job types section summarizes which pipeline types are being used and whether they are supported or unsupported. Please refer to the platform-specific documentation to learn which pipeline types are supported.
This section presents an aggregated summary of the individual build steps that are used across all of the target pipelines and how many could be converted automatically.
The Build steps section provides the following details:
In addition, the audit summary report includes an equivalent summary of build triggers, environment variables, and other uncategorized items.
This section presents an overview of the manual tasks that can be identified.
The Manual tasks section can provide the following details:
The final section of the audit summary report provides a manifest of all the files generated during the audit. These files can include:
GitHub Actions Importer cannot migrate everything. It’s important to be mindful of its limitations, which include:
forecast command is designed to help you understand the compute capacity you’re currently using within your CI/CD environment. This command fetches jobs that have been completed over a specified time period and uses that data to calculate usage metrics.
Running a forecast on the command line will look something like this:
$ gh actions-importer audit jenkins –start-date 7/1/22 --output-dir .
The Forecast report includes these metrics:
Additionally, these metrics are presented for each runner queue defined in the source CI/CD system. This is useful if you will need a mix of hosted and self-hosted runners and/or if you use a mix of platforms.
You can use the
dry-run command to convert an existing pipeline to its equivalent GitHub Actions workflow. The console output of the command will list the path to the file or files that GitHub Actions Importer generated. Before migrating, you should perform a dry run of a pipeline and validate the contents are suitable.
If the conversion of a pipeline was only “partially successful” (that is, it included tasks that could not be converted automatically), the task that was not converted will be included in a commented section. For example, if you were to run the following CLI command:
$ gh actions-importer dry-run jenkins --source-url $SOURCE_URL --output-dir
The converted workflow will have contents similar to the following.
In this situation, you will need to decide how to implement this functionality. If this task is used within multiple pipelines, the recommended approach is to implement a custom transformer that can handle this scenario in every pipeline. If this is a one-off scenario, you can edit the converted workflow file manually.
Let’s assume in this example that the
If you were to add these contents to a file named
transformers.rb, they can be provided to GitHub Actions Importer on the command line. For example:
$ gh actions-importer dry-run jenkins --source-url $SOURCE_URL --output-dir . --custom-transformers transformers.rb
You can use the
migrate command to convert an existing pipeline to its equivalent action and open a pull request with the converted workflows and associated files.
$ gh actions-importer migrate jenkins --source-url $SOURCE_URL –target-url $TARGET_URL --output-dir .
Any necessary manual tasks will be included in the description of the pull request. Once these manual tasks and the code reviews are complete, the pull request can be merged and the workflow will have been successfully migrated to GitHub Actions.
The GitHub Actions Importer IssueOps template repository provides the foundational functionality required to run GitHub Actions Importer commands through GitHub Actions and Issues. This approach allows you to migrate pipelines to GitHub Actions without needing to have GitHub Actions Importer and Docker installed on a local machine. Organizations that want to enable self-service migrations to GitHub Actions could find this approach useful.
Request access by completing the waitlist form here.