Migrating to CircleCI
Cloud Server v3.x Server v2.x Before you start your migration process, it is helpful to have a basic understanding of how CircleCI works.
Here are some basic resources to get you started:
You can also enroll in the migrations course with CircleCI Academy to learn more about migrating to CircleCI.
| If you have Premium or Advanced Support, please reach out to customersuccess@circleci.com for a more tailored migration plan with Gantt charts, custom trainings etc. |
Project migration methodology
Projects can be migrated to CircleCI using the following phases, which are expanded upon in the sections below:
Migration timelines
If you are migrating a simple project in which you just need to run a few scripts and tests, the timeline would be roughly:
-
1 project: < 1 week
-
5 projects: ~3 weeks
-
10 projects: ~1 month
For complex projects with a large-scale test suite migration and large workflows, the migration timeline for completing all phases would be roughly:
-
1 project: ~5 weeks
-
5 projects: ~4 months
-
10 projects: ~9 months+
Assessment phase
Take stock of the current landscape, and understand the differences between CircleCI functionality and that of your current CI tool.
Some things consider during this phase:
-
#Orbs as an alternative to, for example, Jenkins Plugins
-
CircleCI YAML Configuration Reference
Planning phase
Ensure that your VCS org is linked to your CircleCI account and that your plan is applied. Log in using your VCS credentials as described on the Sign Up and Try CircleCI page.
If using the Server product, ensure that you have been provided with your trial license and that all prerequisites are met as described here.
Preparation phase
Prep your team
With your plan and estimated timelines in place, start socializing the details of your migration with stakeholders, and teams who will be impacted, so your users can get started smoothly with minimal disruption to their work. It is best to establish a communications cadence for when, and how often, you will be communicating updates so teams are informed and prepared for the change.
Build your runbook and timeline
Put together a runbook or step-by-step checklist to cover:
-
What needs to happen when
-
Supporting instructions
-
List of owners for each task
-
How long each step will take
Document which steps are dependent on each other, and which have the potential to become blockers. At the end of your runbook, include a mitigation plan with owners in case you need to roll anything back.
Testing phase
In this phase you will:
-
Do a test run and make sure everything is in order
-
Figure out how long the migration will take
-
Uncover any issues before the production migration
Test migration
Do a migration of a smaller, non-mission-critical project as a first step to minimize impact and build confidence in the migration process.
User acceptance testing
Part of the test migration is conducting User Acceptance Testing (UAT) so your end users can ensure that the project works on CircleCI as expected. Through this process you can uncover any issues that will impact your end users and help your teams prepare to work with CircleCI.
Communicate your plan
With final timelines and owners in place, communicate the official plan to your organization. Things to include in your communications are:
-
When the migration will occur
-
Details of downtime users can expect
-
Ask end users to avoid changing anything during the transition
-
Detail what will happen to the current CI solution after migrating, for example, will it still be accessible or readable?
-
Details of what CircleCI onboarding materials are available
Keep in mind that there may be issues that occur during the migration that you need to troubleshoot, so call out an adjustment period to your end users to get everything cleaned up and working as planned.
Migration phase
In this phase you will resolve any last-minute issues, run your project migration, and move your users and data over to CircleCI. Be sure you have completed the plan, prep and test phases before beginning this phase.
Next steps
In the following sections we provide helpful guides and tips for migrating your CI/CD pipelines to CircleCI.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
