atlassian/bitbucket-pipelines-importer repository overview

⁠Bitbucket Pipelines Importer

Bitbucket Pipelines Importer helps automate your migration to Bitbucket Pipelines from another CI platform. Currently it supports Jenkins and Bamboo(Beta).

⁠Getting Started

Bitbucket Pipelines Importer is distributed as a Docker image. You can also compile and run it as a Java application. This allows you to extend the tool to map additional CI plugins to Bitbucket Pipelines features.

⁠Using Docker

⁠Prerequisites

The Docker CLI must be installed⁠ and running.

⁠Usage

(Optional) Pull the latest Docker image:

This step is only required if you have pulled or run the Docker image before and want to ensure you have the latest version.

docker pull atlassian/bitbucket-pipelines-importer

Print the help message:

docker run -it --rm atlassian/bitbucket-pipelines-importer --help

To migrate a CI configuration to Bitbucket Pipelines:

1. Export a variable for the mount path in the Docker container:

   export MOUNT_PATH=/files
   

   Copy

2. Run the Docker container:

   Jenkins:

   docker run -it --rm \
     -e MOUNT_PATH=$MOUNT_PATH \
     -v $PWD/workDir:$MOUNT_PATH \
     atlassian/bitbucket-pipelines-importer migrate jenkins \
     -i "${MOUNT_PATH}/Jenkinsfile" \
     -o "${MOUNT_PATH}/bitbucket-pipelines.yml"
   

   Copy

   Bamboo:

   docker run -it --rm \
     -e MOUNT_PATH=$MOUNT_PATH \
     -v $PWD/workDir:$MOUNT_PATH \
     atlassian/bitbucket-pipelines-importer migrate bamboo \
     -i "${MOUNT_PATH}/bamboo_file.yml" \
     -o "${MOUNT_PATH}/bitbucket-pipelines.yml"
   

   Copy

⁠Building from Source

⁠Prerequisites

• Java 21 or later
• Maven⁠

⁠Usage

1. Build the JAR file:

   mvn package spring-boot:repackage
   

   Copy

2. Run the JAR file:

   Jenkins:

   java -jar target/bitbucket-pipelines-importer-<version>.jar \
     migrate jenkins \
     -i Jenkinsfile \
     -o bitbucket-pipelines.yml
   

   Copy

   Bamboo:

   java -jar target/bitbucket-pipelines-importer-<version>.jar \
     migrate bamboo \
     -i bamboo_file.yml \
     -o bitbucket-pipelines.yml
   

   Copy

Alternatively, you can build and run the Docker image locally:

1. Build the Docker image:

   docker build -t bitbucket-pipelines-importer .
   

   Copy

2. Run the Docker container:

   docker run -it --rm bitbucket-pipelines-importer --help
   

   Copy

⁠Migrate Command (Bamboo)

The migrate command converts Bamboo plans into a Bitbucket Pipelines bitbucket-pipelines.yml configuration file.

⁠Parameters

⁠Output

⁠Instance-level migration

When migrating an entire instance, files are written under:

<output-dir>/
  <bamboo-hostname>/
    <timestamp>/
      build/
        <PROJECT_KEY>/
          <PLAN_KEY>/
            pipelines.yml       ← the generated Bitbucket Pipelines configuration
            bamboo_plan.yml     ← the original Bamboo plan YAML spec
      deployments/
        <DEPLOYMENT_PROJECT_ID>/
          pipelines.yml       ← generated deployment-compatible config (when applicable)
          bamboo_plan.yml     ← source deployment plan/details (when applicable)

⁠Examples

Migrate an entire Bamboo instance:

export MOUNT_PATH=/files
docker run -it --rm \
  -e MOUNT_PATH=$MOUNT_PATH \
  -v $PWD/workDir:$MOUNT_PATH \
  atlassian/bitbucket-pipelines-importer migrate bamboo \
  --output-dir "${MOUNT_PATH}/migrate-output" \
  --bamboo-instance-url $BAMBOO_INSTANCE_URL \
  --bamboo-access-token $BAMBOO_ACCESS_TOKEN

Migrate specific projects:

export MOUNT_PATH=/files
docker run -it --rm \
  -e MOUNT_PATH=$MOUNT_PATH \
  -v $PWD/workDir:$MOUNT_PATH \
  atlassian/bitbucket-pipelines-importer migrate bamboo \
  --project-key PROJ1 --project-key PROJ2 \
  --output-dir "${MOUNT_PATH}/migrate-output" \
  --bamboo-instance-url $BAMBOO_INSTANCE_URL \
  --bamboo-access-token $BAMBOO_ACCESS_TOKEN

Migrate specific plans:

export MOUNT_PATH=/files
docker run -it --rm \
  -e MOUNT_PATH=$MOUNT_PATH \
  -v $PWD/workDir:$MOUNT_PATH \
  atlassian/bitbucket-pipelines-importer migrate bamboo \
  --plan-key PROJ1-PLAN1 --plan-key PROJ1-PLAN2 \
  --output-dir "${MOUNT_PATH}/migrate-output" \
  --bamboo-instance-url $BAMBOO_INSTANCE_URL \
  --bamboo-access-token $BAMBOO_ACCESS_TOKEN

Migrate from a local Bamboo YAML file:

export MOUNT_PATH=/files
docker run -it --rm \
  -e MOUNT_PATH=$MOUNT_PATH \
  -v $PWD/workDir:$MOUNT_PATH \
  atlassian/bitbucket-pipelines-importer migrate bamboo \
  -i "${MOUNT_PATH}/bamboo_file.yml" \
  -o "${MOUNT_PATH}/bitbucket-pipelines.yml"

⁠Custom Transformers (Bamboo)

Bamboo plans sometimes contain any-task entries — tasks that reference a third-party or custom plugin the importer does not natively support. The custom transformers feature lets you provide a Python script that converts a specific any-task plugin into a Bitbucket Pipelines pipe or shell script, so the migration is fully automated.

Pass one or more transformer scripts via --custom-transformers:

docker run -it --rm \
  -e MOUNT_PATH=$MOUNT_PATH \
  -v $PWD:$MOUNT_PATH \
  atlassian/bitbucket-pipelines-importer migrate bamboo \
  -i "${MOUNT_PATH}/bamboo_file.yml" \
  -o "${MOUNT_PATH}/bitbucket-pipelines.yml" \
  --custom-transformers "${MOUNT_PATH}/scripts/my-plugin-transformer.py"

Read the Custom Transformers Guide⁠ for the full script contract, step-level configuration (oidc, docker), OIDC setup for AWS, and worked examples.

⁠Audit Command (Bamboo)

The audit command analyzes your Bamboo plans and produces a migration-readiness report.

⁠Parameters

⁠Output

The audit command generates the following files in the specified output directory:

• audit_summary.md — A high-level summary of the audit results across all plans.
• audit.md — Detailed audit information for each plan.

⁠Examples

Audit an entire Bamboo instance:

export MOUNT_PATH=/files
docker run -it --rm \
  -e MOUNT_PATH=$MOUNT_PATH \
  -v $PWD/workDir:$MOUNT_PATH \
  atlassian/bitbucket-pipelines-importer audit bamboo \
  --output-dir "${MOUNT_PATH}/audit-reports" \
  --bamboo-instance-url $BAMBOO_INSTANCE_URL \
  --bamboo-access-token $BAMBOO_ACCESS_TOKEN

Audit specific projects:

export MOUNT_PATH=/files
docker run -it --rm \
  -e MOUNT_PATH=$MOUNT_PATH \
  -v $PWD/workDir:$MOUNT_PATH \
  atlassian/bitbucket-pipelines-importer audit bamboo \
  --project-key PROJ1 --project-key PROJ2 \
  --output-dir "${MOUNT_PATH}/audit-reports" \
  --bamboo-instance-url $BAMBOO_INSTANCE_URL \
  --bamboo-access-token $BAMBOO_ACCESS_TOKEN

Audit specific plans:

export MOUNT_PATH=/files
docker run -it --rm \
  -e MOUNT_PATH=$MOUNT_PATH \
  -v $PWD/workDir:$MOUNT_PATH \
  atlassian/bitbucket-pipelines-importer audit bamboo \
  --plan-key PROJ1-PLAN1 --plan-key PROJ1-PLAN2 \
  --output-dir "${MOUNT_PATH}/audit-reports" \
  --bamboo-instance-url $BAMBOO_INSTANCE_URL \
  --bamboo-access-token $BAMBOO_ACCESS_TOKEN

⁠Forecast Command (Bamboo)

The forecast command analyzes your Bamboo plans and produces a cost and performance forecast report for migrating to Bitbucket Pipelines. This helps you estimate the expected costs, execution times, and optimal runner types before committing to a migration.

⁠Parameters

⁠Output

The forecast command generates the following file in the specified output directory:

• forecast_summary.md — A detailed forecast report containing:
  • Summary — Forecast metadata including the Bamboo instance URL, importer version, forecast date range, and overall estimated cost for the best-match runner.
  • Plan Info — Total number of plans, jobs, and builds analyzed.
  • Execution Info — Execution time statistics (total, P50, P90, max, min, and average) in minutes.
  • Cost — Estimated cost breakdown for all available runner types, including cost savings compared to the best-match runner and time savings compared to Bamboo.

⁠Examples

Forecast an entire Bamboo instance:

export MOUNT_PATH=/files
docker run -it --rm \
  -e MOUNT_PATH=$MOUNT_PATH \
  -v $PWD/workDir:$MOUNT_PATH \
  atlassian/bitbucket-pipelines-importer forecast bamboo \
  --output-dir "${MOUNT_PATH}/forecast-reports" \
  --bamboo-instance-url $BAMBOO_INSTANCE_URL \
  --bamboo-access-token $BAMBOO_ACCESS_TOKEN

Forecast specific projects:

export MOUNT_PATH=/files
docker run -it --rm \
  -e MOUNT_PATH=$MOUNT_PATH \
  -v $PWD/workDir:$MOUNT_PATH \
  atlassian/bitbucket-pipelines-importer forecast bamboo \
  --project-key PROJ1 --project-key PROJ2 \
  --output-dir "${MOUNT_PATH}/forecast-reports" \
  --bamboo-instance-url $BAMBOO_INSTANCE_URL \
  --bamboo-access-token $BAMBOO_ACCESS_TOKEN

Forecast with a custom date range and agent configuration:

export MOUNT_PATH=/files
docker run -it --rm \
  -e MOUNT_PATH=$MOUNT_PATH \
  -v $PWD/workDir:$MOUNT_PATH \
  atlassian/bitbucket-pipelines-importer forecast bamboo \
  --plan-key PROJ1-PLAN1 \
  --from-date 2026-02-01 \
  --agent-config cpu=4,memory=8 \
  --output-dir "${MOUNT_PATH}/forecast-reports" \
  --bamboo-instance-url $BAMBOO_INSTANCE_URL \
  --bamboo-access-token $BAMBOO_ACCESS_TOKEN

⁠Documentation

Detailed information about how to use Bitbucket Pipelines Importer can be found in the Jenkins migration guide⁠ and the Bamboo migration guide⁠.

⁠Demo

Jenkins⁠

⁠Local Development

⁠Tests

mvn verify

⁠Code Formatting

mvn spotless:apply

⁠Lombok Setup in Editors

We use Lombok⁠ to reduce boilerplate code. To make your editor to be compatible with Lombok, follow the instructions below:

• IntelliJ IDEA⁠
• Eclipse⁠
• Visual Studio Code⁠

⁠Customization and Extensibility

External developers are welcome to contribute to the tool and add support for additional Jenkins plugins. In most cases, though, we expect users to fork the migration tool repository when using source code and make changes privately to support their custom use cases.

⁠Plugin Architecture

The tool's pluggable architecture allows users to:

• Define Custom Plugin Translation Handlers: Add support for custom Jenkins plugins not covered by the default implementation.
• Override Existing Plugins: Replace the default translation of a plugin with a custom implementation

⁠Adding a Custom Plugin Translation Handler

1. Create a new class that implements the PluginTranslationHandler interface provided by the tool.

   public class CustomPluginHandler implements PluginMappingStrategy {
       @Override
       public PluginMappingResult map(MappingContext context, JenkinsStep jenkinsStep) {
           return;
       }
   }
   

   Copy

2. Register the custom handler in the Spring context or by defining it as a spring component, set which commands it supports, and set the plugin Precedence .

   @Component
   @Order(BeanPrecedence.DEFAULT_MID_IMPLEMENTATION)
   @SupportedCommands({"custom"})
   public class CustomPluginHandler implements PluginMappingStrategy {}
   

   Copy

⁠Overriding Existing Plugins

1. Create a new class that overrides the default implementation of the plugin handler.

2. Use the @Order annotation to set the precedence of the custom handler.

   public interface BeanPrecedence {
       int CUSTOM_IMPLEMENTATION = 1;
       int DEFAULT_MID_IMPLEMENTATION = 10;
       int DEFAULT_LOW_FALLBACK = 100;
   }
   
   @Component
   @Order(BeanPrecedence.CUSTOM_IMPLEMENTATION)
   @SupportedCommands({"sh"})
   public class CustomPluginHandler implements PluginMappingStrategy {}
   

   Copy

⁠Contributions

Contributions to Bitbucket Pipelines Importer are welcome! Please see CONTRIBUTING.md⁠ for details.

⁠Support

Become a member of the Bitbucket Pipelines community⁠. This is the perfect place to ask questions, share your feedback, and express which CI plugins you would like to see supported. If you have questions or need assistance, just create a post in this space, and we'll help you get started.

⁠License

Copyright (c) 2024 Atlassian US., Inc. Apache 2.0 licensed, see LICENSE⁠ file.