Buildkite migration tool overview
The Buildkite migration tool serves as a compatibility layer, enabling the conversion of your existing CI configurations into a format compatible with Buildkite's pipeline definitions.
You can start the translation of your pipelines from other CI providers to Buildkite Pipelines by seeing how workflows from other CI/CD platforms map to the Buildkite Pipelines' concepts and architecture. Rather than serving as a complete automated migration solution, the Buildkite migration tool demonstrates how configurations from these other CI/CD platforms could be structured in a Buildkite pipeline configuration format.
The Buildkite migration tool:
-
Supports the following CI providers:
- GitHub Actions
- CircleCI
- Bitbucket Pipelines
- Jenkins (currently in Beta)
Can be used as a standalone tool or potentially integrated into your Buildkite Migration Services process, offering a way to leverage existing CI configurations within the Buildkite ecosystem.
Interactive web-based version
The fastest way to get started with the Buildkite migration tool is to use its interactive web version, also known as the Buildkite migration interactive web tool.
To start translating your existing pipeline or workflow configuration into a Buildkite pipeline:
- If you are using a CI/CD platform other than GitHub Actions, select it from this drop-down.
- In the left panel, enter the pipeline definition to translate into a Buildkite pipeline definition.
- Select the Convert button to reveal the translated pipeline definition in the right panel.
- Copy the resulting Buildkite pipeline YAML configuration on the right and create a new Buildkite pipeline with it.
Conversion errors
If the pipeline configuration you are trying to convert to a Buildkite pipeline contains syntax or other errors, you might see the following Conversion failed message.
In such cases, ensure that the original pipeline configuration you are translating to a Buildkite pipeline is a valid pipeline definition for the CI/CD platform you are migrating from.
Local version
If you would like to run the Buildkite migration tool locally, because you're are interested in developing this tool further, or you'd prefer to work with your pipeline conversions locally, clone the Buildkite migration tool repository to run the migration tool using Puma, which you can then access through its HTTP-based API.
To do this, after cloning this repository, start the Buildkite migration tool's web interface using the following Docker command:
docker compose up webui
After the Docker image has started, you'll be able to access the web interface of the Buildkite migration tool at http://localhost:9292
.
You can also use the docker run
command to start the Buildkite migration tool, although you will need to override the entrypoint:
$ docker run --rm -ti -p 9292:9292 --entrypoint '' --workdir /app $IMAGE:$TAG puma --port 9292
Once the Buildkite migration tool is running locally, you can also interact with it programmatically, for example:
$ curl -X POST -F 'file=@app/examples/circleci/legacy.yml' http://localhost:9292
which should then return output like this:
---
steps:
- commands:
- "# No need for checkout, the agent takes care of that"
- pip install -r requirements/dev.txt
plugins:
- docker#v5.7.0:
image: circleci/python:3.6.2-stretch-browsers
agents:
executor_type: docker
key: build
You could also pipe the output directly to buildkite-agent pipeline upload
.
Next steps
For more tools and recommendations regarding migrating from your existing CI/CD platform to Buildkite, see: