Bitbucket Pipelines

The Buildkite migration tool helps you convert your Bitbucket pipelines into Buildkite pipelines. This page lists the Buildkite migration tool's currently supported, partially supported, and unsupported keys (known as properties in Bitbucket Pipelines) when translating from Bitbucket pipelines 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.

The Bitbucket Pipeline configuration that is referred to in various sections below is specified in the central bitbucket-pipelines.yml within a specific Bitbucket workspace repository. In Buildkite, the pipeline configuration can be set in a singular pipeline.yml within a repository or it can also be set and uploaded dynamically through the use of Dynamic Pipelines. Additionally, control and governance of Buildkite pipelines can be achieved through the use of Pipeline Templates to set shared pipeline configuration within a Buildkite organization.

Using the Buildkite migration tool with Bitbucket

To start converting your Bitbucket pipeline into Buildkite Pipelines format:

Open the Buildkite migration interactive web tool in a new browser tab.
Select Bitbucket Pipelines at the top of the left panel.
Copy your Bitbucket 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 Bitbucket pipeline configuration:

image: node:18

pipelines:
  default:
    - step:
        name: Build
        script:
          - npm install

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

---
steps:
- commands:
  - npm install
  plugins:
  - docker#v5.10.0:
      image: node:18
  label: Build

The Buildkite migration tool interface should look similar to this:

Converting a Bitbucket 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.

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

Clone

Bitbucket Pipelines' clone property provides options for controlling how a repository is cloned during a build.

Key	Supported	Notes
Key	`clone`	Supported	Partially	Notes	Clone options for all steps of a Bitbucket pipeline. The majority of these options need to be set on a Buildkite Agent itself through its configuration of properties such as the clone flags (`git-clone-flags` or `git-clone-mirror-flags` if utilizing a Git mirror), fetch flags (`git-fetch-flags`) - or changing the entire checkout process in a customized plugin overriding the default agent `checkout` hook. Sparse-checkout properties of `code-mode`, `enabled`, and `patterns` used in a Bitbucket pipeline will be translated to the respective properties within the sparse-checkout-buildkite-plugin. `clone` properties in a Bitbucket pipeline have higher precedence over these global properties.

Definitions

Bitbucket Pipelines' definitions property is used to define resources used elsewhere in a pipeline configuration.

Key	Supported	Notes
Key	`definitions`	Supported	Partially	Notes	Customized definitions utilized in a Bitbucket pipeline. `caches` and `services` are supported for translation using the Buildkite migration tool.
Key	`definitions.caches`	Supported	Partially	Notes	Customized cache definitions that can be applied to specific Bitbucket pipeline steps - inclusive of folders, single file-cache, or multi-file cache. Targeted into specific steps with the `pipelines.default.step.caches.<name>` property, where the translation will utilize the cache-buildkite-plugin that may require further setup and configuring around specific caching strategies.
Key	`definitions.caches.<name>`	Supported	Yes	Notes	A customized cache name applicable to one or more steps within a Bitbucket pipeline.
Key	`definitions.caches.<name>.path`	Supported	Yes	Notes	The path to a directory that needs to be cached.
Key	`definitions.caches.<name>.key.files`	Supported	Partially	Notes	The list of (one or more) files that are monitored for changes, and stored once the hash changes between file version changes. If multiple files are specified, then multiple cache-plugin definitions are set on the resulting Buildkite Pipelines command step (so the `manifest` properties between each will be different). Note that this may cause issues if the same folder is being maintained by each cache definition.
Key	`definitions.pipeline`	Supported	Partially	Notes	Pipelines that are exported for reuse within the repositories of the same workspace. Similar functionality exists within Buildkite Pipelines, called Pipeline templates.
Key	`definitions.services`	Supported	Partially	Notes	Docker services that are defined and applied within a Bitbucket pipeline. Services defined in a corresponding Bitbucket pipeline step using the `pipelines.default.step.services` property will have this configuration applied with the use of the docker-compose-buildkite-plugin. The generated configuration will need to be saved to a `compose.yaml` file within the repository, and the image utilized by the Buildkite Pipelines command step as `app`. Refer to the Bitbucket Pipelines' Databases and service containers documentation for more details on service containers and configuration references. Authentication-based parameters will not be translated to the corresponding Buildkite pipeline even if defined.

Export

Key	Supported	Notes
Key	`export`	Supported	No	Notes	Bitbucket Premium option for sharing pipeline configurations between workspaces. Not applicable within Buildkite as an attribute. However, similar functionality exists in Buildkite Pipelines using Pipeline templates.

Image

Bitbucket Pipelines' image property is used to specify public images or private images, and supports a number of sub-properties.

Key	Supported	Notes
Key	`image`	Supported	Yes	Notes	The container image that applies to each step within a Bitbucket pipeline, using the image specified within the docker-buildkite-plugin. This has a lower precedence over a per-step `image` configuration (see `pipelines.default.step.image`).
Key	`image.aws` `image.aws.oidc` `image.name` `image.username` `image.password`	Supported	Partially	Notes	Supported through the use of the corresponding plugin (Docker Login or ECR).

Options

Bitbucket Pipelines' options property contains global settings that apply throughout a pipeline, or all of a repository's pipelines.

Key	Supported	Notes
Key	`options`	Supported	Partially	Notes	Customized options utilized throughout a Bitbucket pipeline.
Key	`options.max-time`	Supported	Partially	Notes	This property is supported for translation within the Buildkite migration tool into the generated Buildkite Pipelines command step's `timeout_in_minutes`.
Key	`options.size`	Supported	Partially	Notes	This property is supported for translation within the Buildkite migration tool into the generated Buildkite Pipelines command step's agent tag.
Key	`options.docker`	Supported	No	Notes	This property is not supported and will depend on the agent configuration the corresponding Buildkite Pipelines command step is being targeted to run said job has available.

Note that both of these partially supported properties, when defined at the Bitbucket pipeline step-level, will have a higher precedence than when these properties are set at options level.

Pipeline starting conditions

Bitbucket Pipelines allows the configuration of various pipeline start conditions, with each condition supporting different configurations and permissible properties, listed in the following set of tables, such as branches, custom, default, pull-requests, and tags.

Branches

Bitbucket Pipelines' branches property defines all branch-specific build pipelines.

Key	Supported	Notes
Key	`pipelines.branches`	Supported	Yes	Notes	Application of a specific Bitbucket pipeline configuration for specific branches. Translated to a step conditional in the corresponding Buildkite pipeline utilizing the `build.branch`/`BUILDKITE_BRANCH` variable.
Key	`pipelines.branches.<branch>`	Supported	Yes	Notes	The branch name or a wildcard where a specific Bitbucket pipeline step configuration needs to be applied.
Key	`pipelines.branches.<branch>.parallel`	Supported	Yes	Notes	Parallel (concurrent) step configuration for a specific branch within a Bitbucket pipeline. See more information regarding the available pipeline parallel properties supported by the Buildkite migration tool and additional property information in the Bitbucket Pipelines' Parallel step options documentation.
Key	`pipelines.branches.<branch>.step`	Supported	Yes	Notes	Individual step configuration for a specific branch within a Bitbucket pipeline. See more information regarding the available pipeline step properties supported by the migration tool, and additional property information in the Bitbucket Pipelines' Step property options documentation.
Key	`pipelines.branches.<branch>.stage`	Supported	Yes	Notes	Stage configuration for a specific branch within a Bitbucket pipeline. See the available pipeline stage properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Stage options documentation.

Custom

Bitbucket Pipelines' custom property is used to define pipelines that can only be triggered manually.

Key	Supported	Notes
Key	`pipelines.custom`	Supported	Yes	Notes	Bitbucket pipelines that can only be triggered manually. The corresponding Buildkite pipeline is first generated with an input step before any command jobs, to ensure that the triggered builds are processed manually.
Key	`pipelines.custom.<name>`	Supported	Yes	Notes	The name of the custom Bitbucket pipeline.
Key	`pipelines.custom.<name>.import-pipeline.import`	Supported	No	Notes	The specification of importing a pipeline from within a specific repository defined in top-level `definitions`. Consider using trigger steps to invoke builds on a specific Buildkite pipeline.
Key	`pipelines.custom.<name>.parallel`	Supported	Yes	Notes	Parallel (concurrent) step configuration for a custom Bitbucket pipeline. See the available pipeline parallel properties supported by the Buildkite migration tool as well as the additional property information in the Bitbucket Pipelines' Parallel step options documentation.
Key	`pipelines.custom.<name>.stage`	Supported	Yes	Notes	Stage configuration for a custom Bitbucket pipeline. See the available pipeline stage properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Stage options documentation.
Key	`pipelines.custom.<name>.step`	Supported	Yes	Notes	Individual step configuration for a custom Bitbucket pipeline. See the available pipeline step properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Step property options documentation.
Key	`pipelines.custom.<name>.variables`	Supported	Partially	Notes	Variable configuration for a custom Bitbucket pipeline. See the available pipeline variable properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Custom (manual) pipeline variables documenation.

Default

Bitbucket Pipelines' default property contains the pipeline definition for all branches that don't match a pipeline definition in other sections.

Key	Supported	Notes
Key	`pipelines.default`	Supported	Yes	Notes	Bitbucket pipeline configuration that does not meet a specific condition.
Key	`pipelines.default.parallel`	Supported	Yes	Notes	Parallel (concurrent step) configuration for default Bitbucket pipelines. See the available pipeline parallel properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Parallel step options documentation.
Key	`pipelines.default.stage`	Supported	Yes	Notes	Stage configuration for default Bitbucket pipelines. See the available pipeline stage properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Stage options documentation.
Key	`pipelines.default.step`	Supported	Yes	Notes	Individual step configuration for default Bitbucket pipelines. See the available pipeline step properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Step property options documentation.

Pull requests

Bitbucket Pipelines' pull-requests property defines pipelines that only run when a pull request is created.

Key	Supported	Notes
Key	`pipelines.pull-requests`	Supported	Yes	Notes	Application of specific Bitbucket pipeline configuration based for pull requests. Translated to a step conditional in the corresponding Buildkite pipeline utilizing the `pull_request.id`/`BUILDKITE_PULL_REQUEST` and `build.branch`/`BUILDKITE_BRANCH` variables.
Key	`pipelines.pull-requests.<branch>`	Supported	Yes	Notes	The base branch name or a wildcard to be applied within a specific Bitbucket pipeline step configuration. To apply the configuration for all builds, use a `**` wildcard.
Key	`pipelines.pull-requests.<branch>.parallel`	Supported	Yes	Notes	Parallel (concurrent) step configuration for pull request builds of a Bitbucket pipeline. See the available pipeline parallel properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Parallel step options documentation.
Key	`pipelines.pull-requests.<branch>.stage`	Supported	Yes	Notes	Stage configuration for pull request builds of a Bitbucket pipelines. See the available pipeline stage properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Stage options documentation.
Key	`pipelines.pull-requests.<branch>.step`	Supported	Yes	Notes	Individual step configuration for pull requests builds within a Bitbucket pipeline. See the available pipeline step properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Step property options documentation.

Key	Supported	Notes
Key	`pipelines.tags`	Supported	Yes	Notes	Application of a specific Bitbucket pipeline configuration based on triggered tag builds. Translated to a step conditional in the corresponding Buildkite pipeline utilizing the `build.tag`/`BUILDKITE_TAG` variable.
Key	`pipelines.tags.<tag>`	Supported	Yes	Notes	The tag name or a wildcard to be applied within a specific Bitbucket pipeline step configuration.
Key	`pipelines.tags.<tag>.parallel`	Supported	Yes	Notes	Parallel (concurrent) step configuration for tag builds of a Bitbucket pipeline. See the available pipeline parallel properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Parallel step options documentation.
Key	`pipelines.tags.<tag>.stage`	Supported	Yes	Notes	Stage configuration for tag builds of a Bitbucket pipeline. See the available pipeline stage properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Stage options documentation.
Key	`pipelines.tags.<tag>.step`	Supported	Yes	Notes	Individual step configuration for tag builds within a Bitbucket pipeline. See the available pipeline step properties supported by the Buildkite migration tool, and additional property information in the Bitbucket Pipelines' Step property options documentation.

Pipeline properties

Each pipeline starting condition in Bitbucket can support various pipeline properties like parallel, step, stage, and variables.

Additionally, implementation of these pipeline properties can be enhanced with best practices by using dynamic pipelines to generate and upload pipeline configuration dynamically and using conditionals at both pipeline level and step level to apply jobs only when certain conditions are met, and setting trigger steps with required attributes and environment variable configurations passed through to the triggered builds.

Parallel

Bitbucket Pipelines' parallel step options allow faster building and testing of code by running a list of steps concurrently.

Key	Supported	Notes
Key	`pipelines.<start-condition>.parallel`	Supported	Yes	Notes	The grouping of multiple steps within a Bitbucket pipeline to be run concurrently. By default, Buildkite executes steps in parallel, unless implicit or explicit dependencies are set. Parallel Bitbucket pipeline steps are transitioned into a group step within the generated Buildkite pipeline without explicit dependencies.
Key	`pipelines.<start-condition>.parallel.fail-fast`	Supported	No	Notes	Whether a Bitbucket pipeline allows this parallel step to fail entirely if it fails (set as `true`), or allows failures (set as `false`). Consider using a combination of `soft_fail` and/or `cancel_on_build_failing` in the corresponding Buildkite Pipelines command steps' attributes for a similar approach.

Step

Bitbucket Pipelines' step property options are used to define build execution units.

Key	Supported	Notes
Key	`pipelines.<start-condition>.step.after-script`	Supported	No	Notes	The actions that a Bitbucket pipeline will undertake after the commands in the `script` key are run. For similar behavior in Buildkite Pipelines, use a repository-level `pre-exit` hook running at the latter end of the job lifecycle.
Key	`pipelines.<start-condition>.step.artifacts`	Supported	Partially	Notes	Build artifacts that will be required for steps later in the Bitbucket pipeline (by default, not obtained unless an explicit `buildkite-agent artifact download` command is run beforehand within the generated Buildkite Pipelines command step). Artifacts that are specified (whether one specific file, or multiple) will be set within the generated command step within the `artifact_paths` key. Each file found matching (or via glob syntax) will be uploaded to Buildkite's Artifact storage that can be obtained in later steps.
Key	`pipelines.<start-condition>.step.caches`	Supported	Yes	Notes	Step-level dependencies downloaded from external sources (for example, Docker, Maven, PyPi) which can be reused in later Bitbucket pipeline steps. Caches that are set at step level (or through the top-level `definition.cache.<name>` property) are translated in the corresponding Buildkite pipeline utilizing the cache-buildkite-plugin to store the downloaded dependencies for reuse between Buildkite builds.
Key	`pipelines.<start-condition>.step.condition`	Supported	Partially	Notes	The configuration for preventing a Bitbucket pipeline step from running unless the specific conditional is met. Translated to an inline conditional (`if`) within the corresponding Buildkite pipelines' command step's `commands`, based on a `git diff` of the base branch.
Key	`pipelines.<start-condition>.step.condition.changeset.includePaths`	Supported	Partially	Notes	The specific file (or files) that need to be detected as changed for the `condition` to apply. This can be set as specific files – or wildcards that match multiple files in a specific directory/directories. Translated to a script that will review the changed files through git. This means that the step itself will actually run and just be marked as passed, which may not be what you want or need. You may want to consider utilizing the monorepo-diff-buildkite-plugin and watching specific folders or files and then uploading the resulting Dynamic pipelines upon a diff detection.
Key	`pipelines.<start-condition>.step.clone`	Supported	Partially	Notes	Clone options for a specific step of a Bitbucket pipeline. The majority of these options should be set directly on a Buildkite Agent via configuration of properties such as the clone flags (`git-clone-flags`, `git-clone-mirror-flags` if utilizing a Git mirror), fetch flags (`git-fetch-flags`) – or changing the entire checkout process in a customized plugin overriding the default agent `checkout` hook. Sparse checkout options are supported (with the `sparse-checkout` sub-property).
Key	`pipelines.<start-condition>.step.deployment`	Supported	No	Notes	The environment set for the Bitbucket Deployments dashboard that has no translatable equivalent within Buildkite Pipelines.
Key	`pipelines.<start-condition>.step.docker`	Supported	No	Notes	The availability of Docker in a specific Bitbucket pipeline step. This will depend on the agent configuration that the corresponding Buildkite command step is being targeted to run the job. Consider tagging agents with `docker=true` to ensure Buildkite Pipelines command steps requiring hosts with Docker installed and configured to accept and run specific jobs.
Key	`pipelines.<start-condition>.step.fail-fast`	Supported	No	Notes	Whether a specific step of a Bitbucket pipeline allows a parallel step to fail entirely if it fails (set as `true`), or allows failures (set as `false`). Consider using a combination of `soft_fail` and/or `cancel_on_build_failing` in the corresponding Buildkite Pipelines command steps' attributes for a similar approach.
Key	`pipelines.<start-condition>.step.image`	Supported	Yes	Notes	The container image that is to be applied to a specific step within a Bitbucket pipeline. Images set at this level will be applied irrespective of the pipeline-level `image` key, and will be applied in the corresponding Buildkite pipeline using the docker-buildkite-plugin. The `aws`, `aws.oidc`, `name`, `username`, and `password` sub-properties are supported through the use of the corresponding plugin (Docker Login or ECR).
Key	`pipelines.<start-condition>.step.max-time`	Supported	Yes	Notes	The maximum allowable time that a step within a Bitbucket pipeline is able to run for. Translates to the corresponding Buildkite Pipelines command step `timeout_in_minutes` attribute.
Key	`pipelines.<start-condition>.step.name`	Supported	Yes	Notes	The name of a specific step within a Bitbucket pipeline. Translates to a Buildkite command step's `label`.
Key	`pipelines.<start-condition>.step.oidc`	Supported	Yes	Notes	Open ID Connect configuration that will be applied for this Bitbucket pipeline step. The generated command step in the corresponding Buildkite pipeline will request an OIDC token and export it into the job environment as `BITBUCKET_STEP_OIDC_TOKEN` (to be passed to `sts` to assume an AWS role for example).
Key	`pipelines.<start-condition>.step.runs-on`	Supported	Yes	Notes	Allocating the Bitbucket pipeline to run on a self-hosted runner with the specific label. All `runs-on` values will be set as agent tags in the Buildkite command step for targeting on specific Buildkite Agents within an organization.
Key	`pipelines.<start-condition>.step.services`	Supported	Partially	Notes	The name of one or more services defined at `definitions.services.<name>` that will be applied for this step. Translated to utilize the service configuration with the docker-compose-buildkite-plugin. Generated configuration will need to be saved to a `compose.yaml` file within the repository, and the image utilized with the Buildkite command step as `app`. Refer to the Bitbucket Pipelines' Databases and service containers documentation for more details on service containers and configuration references. Authentication-based parameters will not be translated to the corresponding Buildkite pipeline if defined.
Key	`pipelines.<start-condition>.step.script`	Supported	Yes	Notes	The individual commands that make up a specific step. Each is translated into a singular command within the `commands` key of a Buildkite command step.
Key	`pipelines.<start-condition>.step.script.pipe`	Supported	No	Notes	Reusable modules to make configuration in Bitbucket pipelines easier and modular. Consider exploring the suite of available Buildkite Plugins for corresponding functionality that is required.
Key	`pipelines.<start-condition>.step.size`	Supported	Yes	Notes	Allocation of sizing options for the given memory for a specific step within a Bitbucket pipeline. The `size` value will be set as an agent tag in the Buildkite command step for targeting on specific Buildkite agents within an organization.
Key	`pipelines.<start-condition>.step.trigger`	Supported	Yes	Notes	The configuration setting for running of a Bitbucket pipeline step manually or automatically (the default setting). For `manual` triggers, an input step is inserted into the generated Buildkite pipeline before the specified `script` within a further command step. Explicit dependencies with `depends_on` are set between the two steps; requires manual processing.

Stage

Bitbucket Pipelines' stage options allow the grouping of pipeline steps with shared properties.

Key	Supported	Notes
Key	`pipelines.<start-condition>.stage`	Supported	Yes	Notes	The logical grouping of one or more Bitbucket pipeline steps. Bitbucket pipeline stages are translated into the corresponding Buildkite pipeline as a group step.
Key	`pipelines.<start-condition>.stage.condition.changeset.includePaths`	Supported	Partially	Notes	The specific file (or files) that need to be detected as changed for the `condition` to apply. This can be set as specific files or wildcards that match multiple files in the specific directories. Translated into a script that will review the changed files through git. This means that the step itself will actually run and will be marked as passed, which may not be what you want or need. You may want to consider utilizing the monorepo-diff-buildkite-plugin and watching for specific folders and files and uploading the resulting Dynamic pipelines upon diff detection.
Key	`pipelines.<start-condition>.stage.name`	Supported	Yes	Notes	The name of the Bitbucket pipeline stage. Transitioned to the `group` label of the corresponding Buildkite group step.
Key	`pipelines.<start-condition>.stage.steps`	Supported	Yes	Notes	Individual step configuration for a Bitbucket pipeline stage. See the configuration options in this section (`pipelines.default.step.<property>`) for the supported and unsupported properties.
Key	`pipelines.<start-condition>.stage.trigger`	Supported	Yes	Notes	The configuration setting for running of a Bitbucket pipeline stage manually or automatically (the default setting). For `manual` triggers, an input step is inserted into the generated Buildkite pipeline's group step before the specified `steps` of this stage. The explicit dependencies with `depends_on` are set between the input step and the following steps to ensure manual processing is required for these to run.

Variables

Bitbucket Pipelines' Custom (manual) pipeline variables allow defined variables to be set or updated when a custom pipeline is run.

Key	Supported	Notes
Key	`pipelines.<start-condition>.variables`	Supported	Partially	Notes	Custom variables that are passed to Bitbucket pipeline steps. Each variable defined in a Bitbucket pipeline step is translated to a Buildkite input step with/without defaults and allowed values specified below. Variables that are translated into the corresponding input step within the generated Buildkite pipeline will require to be fetched in subsequent steps through a `buildkite-agent meta-data get` command.
Key	`pipelines.<start-condition>.variables.name`	Supported	Yes	Notes	The variables' name: translated to the `key` attribute of a specific `field` of an input step (text entry).
Key	`pipelines.<start-condition>.variables.default`	Supported	Yes	Notes	The default variable value if no value is set. Set as the `default` attribute within the `field` of an input step.
Key	`pipelines.<start-condition>.variables.description`	Supported	Yes	Notes	The description of the variable. Translated to the `text` attribute of a specific `field` within the generated input step.
Key	`pipelines.<start-condition>.variables.allowed-values`	Supported	Yes	Notes	The variable's allowed values: each option is translated to a singular `options` object with given value of a specific `field` of an input step.