Migrating from Azure DevOps

This document provides an overview of how to migrate from Azure DevOps to CircleCI.

Tips provided by ImagineX Consulting

Source Control Setup

If you are using Azure DevOps Git or TFVC repositories, you will first need to migrate your source code to GitHub or BitBucket. For Azure DevOps Git repos, here are links on how to import into GitHub or BitBucket:

For TFVC repositories, we recommend using the git-tfs tool. Here’s a link to the tool and steps for using it:

GitHub Enterprise

Following are the steps required for using the git command line tool to import your code into GitHub Enterprise:

  1. Create an empty repository on your GitHub Enterprise instance.

  2. Create a bare clone of your external repository on your local machine, fetching all remote tags (refs/tags/*) and copying all remote branch heads (refs/heads/\*) directly to their corresponding local branch heads.

    untranslated: true- git clone https://external-host.com/extuser/repo.git --bare

. Add your GitHub Enterprise repository as a remote reference in your local clone.

cd [repo-name] git remote add enterprise git@[hostname]:[owner]/[repo-name].git

. Push all local references (refs/*) up to your remote GitHub Enterprise repository.

git push enterprise --mirror

If you need to export other Azure DevOps artifacts, you can download most of the data into Excel spreadsheets. Follow the Azure DevOps documentation on https://docs.microsoft.com/en-us/azure/devops/organizations/projects/save-project-data?view=azure-devops[saving project data].

Once you have imported your code into GitHub or BitBucket, you can start creating a project in CircleCI using the https://circleci.com/docs/2.0/getting-started/[Getting Started guide].

== Build Configuration

If you're using Azure DevOps Pipelines or TFS Build and Release, you'll need to migrate your build configuration. In Azure DevOps Pipelines, the build configuration is defined in a file called `azure-pipelines.yml` in the root directory of your source code repository. In TFS Build and Release, the build configuration is done through the web interface and can be exported to a json file. In either case, if you use shell scripts to perform your build, you can reuse those scripts in CircleCI.

First, create a CircleCI build configuration file. In the root directory of your source code repository, create a folder named `.circleci` and create a file in that folder named `config.yml`. Next, follow the CircleCI documentation here to learn how to configure the `config.yml` file.

The Azure DevOps Pipelines and CircleCI configurations will be different. It may be helpful to have both Azure DevOps and CircleCI reference documentation open side-by-side to help with the conversion of the build steps:

* https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema[Azure DevOps YML Reference]

* https://circleci.com/docs/2.0/configuration-reference/[CircleCI YML Reference]

Some differences that are worth calling out:

[cols=2*, options="header", stripes=even]
| Azure DevOps | CircleCI

2+h| Define a job that executes a single build step.


jobs: - job: job1 steps: - script: chmod +x ./script.sh - script: ./script.sh


jobs: job1: steps: - checkout - run: "execute-script-for-job1"

2+h| Specify a docker image to use for a job.


jobs: - job: job1 container: image: node:10


jobs: job1: docker: - image: node:10 auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference

2+h| Define a multi-stage build pipeline. Job1 and Job2 run in concurrently. Once they’re done, Job3 runs. Once Job3 is done, Job4 runs.


stages: - stage: build jobs: - job: job1 steps: - script: make build dependencies - job: job2 steps: - script: make build artifacts - stage: test jobs: - job: job3 steps: - script: make test - stage: deploy jobs: - job: job4 steps: - script: make deploy


version: 2 jobs: job1: steps: - checkout - run: make build dependencies job2: steps: - run: make build artifacts job3: steps: - run: make test job4: steps: - run: make deploy

workflows: version: 2 jobs: - job1 - job2 - job3: requires: - job1 - job2 - job4: requires: - job3

2+h| Execute jobs on multiple platforms. Azure DevOps uses pools and demands to identify build runners. CircleCI provides executors for docker, Linux and MacOS.


jobs: - job: ubuntuJob pool: vmImage: ubuntu-16.04 steps: - script: echo "Hello, $USER!" - job: osxJob pool: vmImage: macOS-10.14 steps: - script: echo "Hello, $USER!"


jobs: ubuntuJob: machine: image: ubuntu-1604:201903-01 steps: - checkout - run: echo "Hello, $USER!" osxJob: macos: xcode: 11.3.0 steps: - checkout - run: echo "Hello, $USER!"


For larger and more complex build files, we recommend moving over the build steps in phases until you get comfortable with the CircleCI platform. We recommend this order:

. Execution of shell scripts and Docker compose files
. https://circleci.com/docs/2.0/workflows/[Workflows]
. https://circleci.com/docs/2.0/artifacts/[Artifacts]
. https://circleci.com/docs/2.0/caching/[Caching]
. https://circleci.com/docs/2.0/triggers/#section=jobs[Triggers]
. https://circleci.com/docs/2.0/optimizations/#section=projects[Performance options]

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.