Introduction
Migration from existing Continuous Integration/Continuous Deployment platforms into GitHub Actions is complex. This is where the GitHub Actions Importer comes in by providing features to help automate this migration process. By analyzing your current pipelines, forecasting usage, and auto-conversion of configurations, GitHub Actions Importer makes the journey of migrating to GitHub Actions easier and faster.
Steps we will cover in this article:
- Prerequisites to Using GitHub Actions Importer
- Key Features of GitHub Actions Importer
- Self-Serve Migrations with IssueOps
- Best Practices for Migrating CI/CD Pipelines
Prerequisites to Using GitHub Actions Importer
Before you start working with GitHub Actions Importer, you will need to meet the following prerequisites:
-
Docker is to be installed and running on your computer.
-
This is dependent upon the GitHub CLI (
gh) which has to be installed to interface with GitHub and the Docker container. -
Credentials towards your existing CI/CD platform and GitHub must be created. This may be done via environment variables through the
.env.localfile.
Once these are in place, the importer's CLI extension can be installed using:
gh extension install github/gh-actions-importer
Output:
✓ Installed extension github/gh-actions-importer
After installing, you can update the extension by executing:
gh actions-importer update
Output:
✓ Successfully updated GitHub Actions Importer to the latest version.
Key Features of GitHub Actions Importer
1. Auditing Existing CI/CD Pipelines
Before migration, you must understand your current pipelines. This is done through the audit command provided within GitHub Actions Importer. It scans your current CI/CD platform and provides you with a comprehensive report of your workflows, their configurations, and the dependencies between them.
Auditing Jenkins Pipelines
To audit Jenkins pipelines:
gh actions-importer audit jenkins
Output:
Analyzing Jenkins instance...
Jenkins Audit Report:
- Total pipelines: 25
- Multi-branch pipelines: 5
- Orphaned jobs: 2
- Estimated conversion rate: 85%
- Recommendations: Review pipeline #12 due to unsupported steps.
The following report summarizes the Jenkins pipelines, possible problems, and conversion rate that resulted.
2. Forecasting GitHub Actions Usage
Migrating to GitHub Actions requires you to estimate the resources you will need for your workflows. The forecast command reviews historical usage data from your existing CI/CD platform, then provides an estimate of the usage for GitHub Actions.
Forecasting for GitLab Pipelines
To do a projection of the usage of GitLab pipelines:
gh actions-importer forecast gitlab
Output:
Forecasting GitHub Actions usage based on GitLab pipeline history...
GitLab Forecast Report:
- Total pipelines analyzed: 48
- Average duration per run: 12 minutes
- Estimated monthly GitHub Actions usage: 2,500 minutes
- Recommendations: Consider optimizing step #4 in pipeline 'build-deploy' to reduce runtime.
This output should help you estimate how much time of GitHub Actions you will need based on historical GitLab pipeline data.
3. Testing the Migration Process with Dry Runs
You can use the dry-run command to test a full migration without committing. The output will be your pipeline converted to its GitHub Actions equivalent and a .yaml workflow file will be generated, but your repository will not be changed.
Dry Runs of the Migration Process
To run a dry run for Jenkins pipelines:
gh actions-importer dry-run jenkins
Output:
Converting Jenkins pipeline to GitHub Actions workflow...
Dry Run Completed:
- Workflow file generated: ./github/workflows/jenkins_migration.yml
- Conversion accuracy: 90%
- Notes: Some custom scripts may require manual intervention.
This will output the YAML workflow that is downloaded to your local system, from where you can have a look and make the changes you would like to do before proceeding.
4. Migrating Pipelines to GitHub Actions
Once you are ready to migrate, the migrate command will convert your existing pipeline into a GitHub Actions workflow and create a pull request with those changes. That makes it really easy to transition, because you can then review and merge in the new workflows directly into your repository.
Migrating from CircleCI to GitHub Actions
To migrate CircleCI pipelines:
gh actions-importer migrate circle-ci
Output:
Migrating CircleCI pipeline to GitHub Actions...
Migration Completed:
- Pull request created: https://github.com/my-org/my-repo/pull/45
- Conversion accuracy: 85%
- Notes: Review the following jobs for custom handling: build, deploy
This command will create a pull request from the converted workflows in order for you to review and approve the migration.
Self-Serve Migrations with IssueOps
For the organizations that want to give the power to their teams to self-serve and perform migrations themselves, IssueOps makes that possible. Once IssueOps is set up, users can start a migration without anything more than opening a GitHub Issue via a pre-built template. This really works well in large organizations because they do not have to install the CLI or Docker.
To understand how to setup IssueOps for GitHub Actions Importer, refer to GitHub Actions Importer IssueOps Repository.
Best Practices for Migrating CI/CD Pipelines
- Start with a Dry Run: First and foremost, what calendar-bot does is allow you to create the GitHub Actions workflow file by doing a dry run. That's the chance to review and change things before finally committing to the migration.
- Audit and Forecast: Perform audit and forecast commands to assess the level of complexity of your pipelines, thereby assisting resource planning. This will help manage the timeline of this migration and resource availability during the transition.
- Inspect Workflows Before Production: While GitHub Actions Importer automates the process of conversion, it is always necessary to manually inspect the correctness of the generated workflow files before using their output in production. The accuracy of conversion it is aimed to achieve is 80%, and some pipelines may require manual adjustments.
- Iterate Gradually: For larger projects, consider migrations of pipelines to be done in phases. It can give one-platform engineers much more controlled testing and feedback for smooth transitions that least disrupt the user.
Conclusion
The migration of CI/CD pipelines can be automated to GitHub Actions and does not have to be an activity done by hand, which may be really time-consuming. You will be capable of automating most of the auditing and forecasting to dry runs, and final migrations of said migration, thanks to GitHub Actions Importer. With best practices in place and with some assist from IssueOps, your organization will find its footing much quicker on a transition to GitHub Actions and be able to leverage its powerful continuous integration and continuous deployment capabilities. Plan, test, and automate your journey of migration using GitHub Actions Importer today.