CircleCI

The Buildkite migration tool helps you convert your CircleCI pipelines into Buildkite pipelines. This page lists the Buildkite migration tool's currently supported, partially supported, and unsupported CircleCI keys when translating from CircleCI pipeline configurations to Buildkite pipelines.

For any partially supported and unsupported Keys listed in the tables on this page, you should follow the instructions provided in their relevant Notes, for details on how to successfully complete their translation into a working Buildkite pipeline.

Using the Buildkite migration tool with CircleCI

To start converting your CircleCI pipeline configurations into Buildkite Pipelines format:

Open the Buildkite migration interactive web tool in a new browser tab.
Select CircleCI at the top of the left panel.
Copy your CircleCI pipeline configuration and paste it into the left panel.
Select Convert to reveal the translated pipeline configuration in the Buildkite Pipeline panel.

For example, when converting the following example CircleCI pipeline configuration:

version: 2.1

jobs:
  build:
    docker:
      - image: cimg/node:18.20

    steps:
      - checkout

      - run:
          name: Install dependencies
          command: npm install

workflows:
  build-workflow:
    jobs:
      - build

The Buildkite migration tool should translate this to the following output:

---
steps:
- commands:
  - "# No need for checkout, the agent takes care of that"
  - echo '~~~ Install dependencies'
  - npm install
  plugins:
  - docker#v5.10.0:
      image: cimg/node:18.20
  agents:
    executor_type: docker
  key: build

The Buildkite migration tool interface should look similar to this:

Converting a CircleCI pipeline in Buildkite migration tool's web UI

You might need to adjust the converted Buildkite pipeline output to ensure it is consistent with the step configuration conventions used in Buildkite Pipelines.

The Buildkite migration tool supports the use of YAML aliases in CircleCI pipeline configurations, which are reusable configuration snippets that can applied to specific points in a pipeline configuration. A YAML alias is defined by an & (anchor, for example, &tests) within the top-level aliases key and substituted into a CircleCI pipeline configuration with an * (for example, *tests). A configuration defined by an alias is respected and parsed at its specified section in the pipeline configuration. Also note that more complex (for example, multi-line) anchors defined as a YAML alias in a CircleCI pipeline configuration are expanded upon their translation into Buildkite pipeline format.

Remember that not all the features of CircleCI can be fully converted to the Buildkite Pipelines format. See the following sections to learn more about the compatibility, workarounds, and limitation of converting CircleCI pipelines to Buildkite Pipelines.

Logical operators (helpers)

Key	Supported	Notes
Key	`and`	Supported	Partially	Notes	Logical operator for denoting that all inputs required to be true. Supported alongside the `when` key within setting up conditional `workflow` runs.
Key	`or`	Supported	Partially	Notes	Logical operator for describing whether any of the inputs are true. Supported alongside the `when` key within setting up conditional `workflow` runs.
Key	`not`	Supported	Partially	Notes	Logical operator for negating input. Supported alongside the `when` key within setting up conditional `workflow` runs.

Commands

Key	Supported	Notes
Key	`commands`	Supported	Yes	Notes	A `command` defined in a CircleCI pipeline is a reusable set of instructions with parameters that can be inserted into required `job` executions. Commands can have their own lists of `steps` that are translated through to the generated command step's `commands`. If a `command` contains a `parameters` key, these parameters are respected when used in jobs and workflows. When not specified, the parameters' default values are used.

Executors

Key	Supported	Notes
Key	`executors`	Supported	Yes	Notes	The `executor` key defined at the top level in a CircleCI workflow is mapped to the use of the `executor` key specified within a specific `job`. Supported execution environments include `machine`, `docker`, `macos`, and `windows`. Further information can be found in the Jobs > Executors table below. The execution environment in Buildkite Pipelines is specified with each environment's applied tags in their generated command step, which can be targeted when creating builds.

Jobs

General

Key	Supported	Notes
Key	`jobs.<name>`	Supported	Yes	Notes	Named, individual `jobs` that make up a part of a given `workflow`.
Key	`jobs.<name>.environment`	Supported	Yes	Notes	The `job`-level environment variables of a CircleCI pipeline. Applied in the generated command step as step-level environment variables with the `env` key.
Key	`jobs.<name>.parallelism`	Supported	No	Notes	A `parallelism` parameter (if greater than `1` is defined) will create a separate execution environment and will run the `steps` of the specific `job` in parallel. In Buildkite Pipelines, a similar `parallelism` key can be set to a command step, which will run the defined `command` over separate jobs (sharing the same agent queues and tags targeting).
Key	`jobs.<name>.parameters`	Supported	Yes	Notes	Reusable keys that are used within `step` definitions within a `job`. Default parameters that are specified in a `parameters` block are passed through into the command step's `commands` if specified.
Key	`jobs.<name>.shell`	Supported	No	Notes	The `shell` property sets the default shell that is used across all commands within all steps. This should be configured on the Buildkite Agent itself, or by defining the `shell` option when starting a Buildkite Agent, which sets the shell command used to interpret all build commands.
Key	`jobs.<name>.steps`	Supported	Partially	Notes	A collection of non-`orb` `jobs` commands that are executed as part of a CircleCI `job`. Steps can be defined within an `alias`. All the `steps` within a singular `job` are translated to the `commands` of a shared command step within the generated Buildkite pipeline to ensure they share the same execution environment.
Key	`jobs.<name>.working_directory`	Supported	Yes	Notes	The location of the executor where steps are run. If set, a "change directory" (`cd`) command is created within the shared `commands` of a Buildkite Pipelines' command step to the desired location.

Executors

While the Buildkite migration tool will translate the following listed executor types, to use the generated steps in your translated Buildkite pipeline, your targeted agents must have the relevant operating system (OS), as well as dependencies, and tooling (for example, Docker or XCode) available on them. Buildkite offers the Elastic CI Stack for AWS as a fully scalable Buildkite Agent fleet on AWS with a suite of tooling installed by default. Additionally, customized agents can be set up to target builds that requires a specific OS, tooling, or both. Or you can use Buildkite hosted agents—a fully-managed solution offered by Buildkite.

Key	Supported	Notes
Key	`jobs.<name>.docker`	Supported	Yes	Notes	Specifies that the `job` will run within a Docker container (using the `image` property) with the help of the Docker Buildkite Plugin or Docker Compose Buildkite Plugin. Additionally, the Docker Login Plugin is appended if an `auth` property is defined, or the ECR Buildkite Plugin if an `aws-auth` property is defined within the `docker` property. Sets the agent targeting for the generated command step to `executor_type: docker`.
Key	`jobs.<name>.executor`	Supported	Yes	Notes	Specifies the execution environment based on an executor definition supplied in the top-level `executors` key.
Key	`jobs.<name>.macos`	Supported	Yes	Notes	Specifies that the `job` will run on a macOS-based execution environment. The agent targeting tags for the generated command step will be set to `executor_type: osx` and the specified version of `xcode` from the `macos` parameters will be set as `executor_xcode: <version>`.
Key	`jobs.<name>.machine`	Supported	Yes	Notes	Specifies that the `job` will run on a machine execution environment. This translates to agent targeting for the generated command step through the tags of `executor_type: machine` and `executor_image: self-hosted`.
Key	`jobs.<name>.resource_class`	Supported	Yes	Notes	The specification of compute that the executor will require for running a job. This is used to specify the `resource_class` agent targeting tag for the corresponding command step.
Key	`jobs.<name>.windows`	Supported	Yes	Notes	Specifies that the `job` will run on a Windows-based execution environment. The agent targeting tags for the generated command step will be set to `executor_type: windows`.

Orbs

Key	Supported	Notes
Key	`orbs`	Supported	No	Notes	Orbs are currently not supported by the Buildkite migration tool and should be translated by hand if their equivalent functionality is required within a Buildkite pipeline. In Buildkite Pipelines, reusable plugins can provide a similar functionality for integrating various common (and third-party integration-related) tasks throughout a Buildkite pipeline, such as logging into ECR, running a step within a Docker container, running multiple Docker images through a compose file, triggering builds in a monorepo setup, to list a small number of these plugins.
Key	Docker `orbs`	Supported	Partially	Notes	Docker orbs are converted but their translation is only an approximation. It is recommended that you reconstruct any orb-related logic in a Buildkite pipeline instead based on the recommendations outlined in `orbs`.

Parameters

Key	Supported	Notes
Key	`parameters`	Supported	No	Notes	Pipeline-level parameters that can be used in the pipeline-level configuration. Pipeline-level environment variables allow for utilizing variables in a Buildkite pipeline configuration with conditionals.

Setup

Key	Supported	Notes
Key	`setup`	Supported	No	Notes	Allows for the conditional configuration trigger from outside the `.circleci` directory. While this is not directly compatible with Buildkite Pipelines, Buildkite Pipelines offers trigger steps, which allow for triggering builds from another pipeline.

Version

Key	Supported	Notes
Key	`version`	Supported	No	Notes	The version of the CircleCI pipeline configuration applied to this pipeline. Since Buildkite Pipelines is a fully-SaaS product, there is no equivalent mapping for this key in Buildkite Pipelines, and this key can generally be ignored.

Workflows

Key	Supported	Notes
Key	`workflows`	Supported	Yes	Notes	A collection of `jobs` the order of which defines how a CircleCI pipeline is run.
Key	`workflows.<name>`	Supported	Yes	Notes	An individual named workflow that makes up a part of the CircleCI pipeline's definition. If a CircleCI pipeline has more than one `workflow` specified, each workflow will be transitioned to a group step.
Key	`workflows.<name>.jobs`	Supported	Yes	Notes	The individually named, non-`orb` `jobs` that make up a part of a specific workflow. Customized `jobs` defined as a part of a `workflow` will be translated to a Buildkite command step within the generated pipeline, and `jobs` with the `approval` type will be translated to a Buildkite block step.
Key	`workflows.<name>.jobs.<name>.branches`	Supported	No	Notes	The `branches` that will be allowed or blocked for a singular `job`. At the moment, the Buildkite migration tool supports setting `filters` within `workflows`, and in particular, sub-properties `branches` and `tags` in setting a step conditional in the generated pipeline.
Key	`workflows.<name>.jobs.<name>.filters`	Supported	Yes	Notes	The `branches` and `tag` filters that will determine the eligibility for a CircleCI to run.
Key	`workflows.<name>.jobs.<name>.filters.branches`	Supported	Yes	Notes	The specific `branches` that are applicable to the `job`'s filter. Translated to a step conditional.
Key	`workflows.<name>.jobs.<name>.filters.tags`	Supported	Yes	Notes	The specific `tags` that are applicable to the `job`'s filter. Translated to a step conditional.
Key	`workflows.<name>.jobs.<name>.matrix`	Supported	Yes	Notes	The `matrix` key allows running a specific job as part of a workload with different values. Translated to a build matrix setup within a command step.
Key	`workflows.<name>.jobs.<name>.requires`	Supported	Yes	Notes	A list of `jobs` that require a certain `job` to start. Translated to explicit step dependencies with the `depends_on` key.
Key	`workflows.<name>.when`	Supported	Yes	Notes	Conditional execution key that allows workflows to run under certain conditions, such as those based on pipeline parameters. The Buildkite migration tool allows for the specification using logical operators `and`, `or`, and `not` in creating command conditionals, and maps basic `when` conditions to Buildkite's conditional steps, though complex nested conditions may require manual adjustment.