CircleCI Server v3.x Migration

Migrating from 2.19.x to 3.0 requires that you back up your 2.19 installation and then restore the data to the new Server 3.0 installation. It does require an already operating Server 3.0 installation. Depending on the size of your data stores, the migration can take anywhere from a few minutes to a few hours. We recommend using a staging environment before completing this process in a production environment. This will not only allow you to gain a better understanding of the migration process, but will also give you a feel for how long the migration will take to complete.

If you have externalized your data stores (Mongo, Postgres, and Vault), then you need to wait until the Server 3.1 release for migration. Server 3.1 will support externalized data stores, and you will be able to point your 3.1 installation to the data stores you were using for your 2.19 instance.


  • Running the migration script will cause downtime, it is recommend to schedule a maintenance window.

  • This script will stop the 2.19.x instance, and not restart it. It can be restarted manually via the Admin Console.

  • The script works by exporting the content of data stores, then importing that data into the new instance. Exported data will be stored in migrate/circleci_export, this data may be useful in debugging problems.


  1. Your current CircleCI Server installation is 2.19

  2. You have a running CircleCI Server 3.0 installation.

  3. You have successfully run reality check with contexts prior to starting.

  4. The migration script must be run from a machine with

    • kubectl configured for the Server 3.0 instance

    • ssh access to the 2.19 services box


Step 1 - Clone the repository and run the migration script

  1. Run git clone

  2. Change into the migrate directory: cd server-scripts/migrate

  3. Run the migration script, i.e.: ./

  4. You will be prompted for the following information:

    • Username of your Server 2.19 installation

    • Hostname of your Server 2.19 installation

    • The path to your SSH key file for your Server 2.19 installation

    • Kubernetes namespace of your Server 3.0 installation

  5. After the script has completed, the Signing and Encryption keys from the 2.19 instance will need to be added to the new 3.0 instance via the KOTS Admin Console. The keys will be located in migrate/circleci_export/circle-data

  6. The 3.0 instance will either need to be updated to point at the same bucket that the 2.19 instance used, or the data needs to be copied over to a new bucket. The latter will ensure the 2.19 instance continues to work as expected, and so is the recommended approach if this migration is part of a test.

If a different hostname is being used in the 3.0 environment, the GitHub webhooks will still be pointing to the hostname used in the 2.19 environment. The easiest way to update this is to click Stop Building and then Set Up Project. After doing this, the contexts and environment variables associated with the project will still be present.

Step 2 - Validate your migration to Server 3.0

Re-run reality check with contexts on your new Server 3.0 environment by pushing a fresh commit.

Step 3 - Update your team

Once you have successfully run reality check, notify your team of the new CircleCI UI and URL, if it has changed.

Frequently Asked Questions

Where did all my job and build history go?

Why does nothing happen when I select "Start Building" on my project after migration?

  • By default, a newly added project (a project that has never been followed) will trigger a build automatically after it has been followed for the first time. If the project was or ever has been followed in 2.0 or 3.0, it will not be considered a new project or first build and a build will not be triggered after follow. To trigger a build, perform an activity that will trigger a Github webhook such as pushing up a new commit or branch.