Introduction to CircleCI migration

Cloud

Server v3.x

Why migrate to CircleCI?

CircleCI is a first-class CI tool. CI/CD has been CircleCI’s specialization since the company’s founding over a decade ago. On top of the features you would expect from any CI/CD tool, what sets CircleCI apart are the following productivity-boosting features:

Advanced Caching - On top of normal dependency caching, CircleCI offers caching specific to Docker image layers. This means subsequent builds of your Docker images will run faster, cutting even more time off your commit-to-deploy workflows.
SSH Into Builds - CircleCI offers the ability to securely SSH into an execution environment to tail logs, work with files, and directly interact with an environment. This is highly useful for debugging failing builds.
Resource Classes - You can use various different sizes of executor on our platform, great for adjusting according to lighter or heavier workloads on a node.
Test Parallelism - CircleCI’s platform provides not only concurrent job execution, but also the ability to split tests between parallel environments. You can dramatically cut build times by splitting workloads between different containers.

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
Execution Environments
Testing

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 in the server installation guides ( AWS Prerequisites and GCP Prerequisites).

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.