--- title: "Migrate from Buildkite" description: "An overview of how to migrate from Buildkite to CircleCI." doc_version: "unversioned" last_updated: "2026-08-20" --- > For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt) # Migrate from Buildkite This document provides an overview of how to migrate from Buildkite to CircleCI. **Tips provided by ImagineX Consulting** ## Source control setup First, you will need to ensure your source code is located in either GitHub, Bitbucket or GitLab. See the following for details on how to import your code: * [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) ### 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 ``` 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 Next, you will need to migrate your build configuration. On Buildkite, the build configuration is either defined in the web interface or in a file called `.pipeline.yml` in the root directory of your source code repository. 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`. Create a file in that folder named config.yml. Follow the CircleCI documentation to learn how to configure the .config.yml file. The Buildkite and CircleCI configurations will be different. It may be helpful to have both Buildkite and CircleCI reference documentation open side-by-side to help with the conversion of the build steps: * [Buildkite Pipeline Reference](https://buildkite.com/docs/pipelines/defining-steps) * [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/execution-managed/private-images/).
BuildkiteCircleCI
Define a job that executes a single build step.
steps:
  - command: 'execute-script-for-job1.sh'
jobs:
  job1:
    steps:
      - checkout
      - run: "execute-script-for-job1"
Specify a Docker image to use for a job.
steps:
  - label: 'job1'
    plugins:
      - docker#v3.2.0:
          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.
steps:
  - label: 'job1'
    command: 'make build dependencies'

  - label: 'job2'
    command: 'make build artifacts'

  - wait

  - label: 'job3'
    command: 'make test'

  - wait

  - label: 'job4'
    command: '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. Buildkite uses tags to identify build agents. CircleCI provides executors for Docker, Linux and macOS.
steps:
  - label: 'ubuntuJob'
    agents:
      ubuntu: '16.04'
    command: 'echo "Hello, $USER!"'

  - label: 'osxJob'
    agents:
      osx: 'true'
    command: 'echo "Hello, $USER!"'

jobs:
  ubuntuJob:
    machine:
      image: ubuntu-2404:current
    steps:
      - checkout
      - run: echo "Hello, $USER!"
  osxJob:
    macos:
      xcode: 26.6.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. Execution of 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)