--- title: "Migrate from Azure DevOps" description: "Migrate from Azure DevOps to CircleCI, including source control setup and a side-by-side comparison of build configuration syntax." platform: "Cloud" doc_version: "unversioned" last_updated: "2026-10-06" cloud_plans: "Free, Performance, Scale" version_control: "All supported providers" --- > For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md). > > For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt). # Migrate from Azure DevOps **Cloud plans:** Free, Performance, Scale **Version control:** [All supported providers](https://circleci.com/docs/guides/integration/version-control-system-integration-overview/) 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, Bitbucket or GitLab. For Azure DevOps Git repositories, here are links on how to import: * [GitHub](https://help.github.com/en/articles/importing-a-repository-with-github-importer) * [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/import-a-repository) * [GitLab](https://docs.gitlab.com/ee/user/project/import/repo_by_url.html) For TFVC repositories, we recommend using the git-tfs tool. Here are links to the tool and steps for using it: * [Git-tfs migration tool](https://github.com/git-tfs/git-tfs) * [Git-tfs migration steps](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md) ### 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 branch heads (`refs/heads/\*`). ```shell git clone https://external-host.com/extuser/repo.git --bare ``` 3. Add your GitHub Enterprise repository as a remote reference in your local clone. ```shell cd [repo-name] git remote add enterprise git@[hostname]:[owner]/[repo-name].git ``` 4. Push all local references (refs/\*) up to your remote GitHub Enterprise repository. ```shell 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 [saving project data](https://learn.microsoft.com/en-us/azure/devops/organizations/projects/save-project-data?view=azure-devops). Once you have imported your code into GitHub, Bitbucket, or GitLab, you can start creating a project in CircleCI using the [Getting Started](https://circleci.com/docs/guides/getting-started/getting-started/) guide. ## Build configuration If you are using Azure DevOps Pipelines or TFS Build and Release, you will 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](https://circleci.com/docs/guides/getting-started/config-intro/) 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: * [Azure DevOps YML Reference](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema) * [CircleCI YML Reference](https://circleci.com/docs/reference/configuration-reference/) ## Configuration comparison **Using Docker?** Authenticating Docker pulls from image registries is recommended when using the Docker execution environment. Authenticated pulls allow access to private Docker images, and may also grant higher rate limits, depending on your registry provider. For further information, see [Using Docker Authenticated Pulls](https://circleci.com/docs/guides/execute/private-images/).
Azure DevOpsCircleCI
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"
Specify a Docker image to use for a job.
jobs:
  - job: job1
    container:
      image: node:10
jobs:
  job1:
    docker:
      - image: node:10
Define a multi-stage build pipeline. Job1 and Job2 run concurrently. Once they are 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.1
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:
  jobs:
    - job1
    - job2
    - job3:
        requires:
          - job1
          - job2
    - job4:
        requires:
          - job3
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-2404:current
    steps:
      - checkout
      - run: echo "Hello, $USER!"
  osxJob:
    macos:
      xcode: 27.0.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: 1. Shell scripts and Docker compose files. 2. [Workflows](https://circleci.com/docs/workflows/) 3. [Artifacts](https://circleci.com/docs/artifacts/) 4. [Caching](https://circleci.com/docs/caching/) 5. [Triggers](https://circleci.com/docs/guides/orchestrate/triggers-overview/) 6. [Performance options](https://circleci.com/docs/optimizations/#section=projects)