atlassian/bitbucket-pipelines-importer

Bitbucket Pipelines Importer

![Bitbucket Pipelines]([***]

镜像概述和主要用途

Bitbucket Pipelines Importer 是一款自动化迁移工具，帮助用户从其他CI平台迁移到Bitbucket Pipelines。目前主要支持从Jenkins迁移，可将Jenkinsfile转换为Bitbucket Pipelines配置文件（bitbucket-pipelines.yml），简化迁移流程。

核心功能和特性

• Jenkins迁移支持：自动将Jenkinsfile转换为Bitbucket Pipelines兼容的配置文件
• Docker分发：提供Docker镜像，便于快速部署和使用，无需复杂环境配置
• 可扩展性：支持通过源码编译扩展功能，映射更多Jenkins插件到Bitbucket Pipelines特性
• 插件架构：允许自定义插件转换处理程序，覆盖或扩展默认转换逻辑
• 多运行方式：可作为Docker容器运行，也可编译为Java应用程序独立运行

使用场景和适用范围

• 需要从Jenkins迁移到Bitbucket Pipelines的开发团队
• 希望自动化转换Jenkins构建配置，减少手动调整的场景
• 需要自定义Jenkins插件映射规则的高级用户
• CI/CD流程标准化或平台迁移项目

详细使用方法和配置说明

快速开始

Bitbucket Pipelines Importer 主要通过Docker镜像分发，也可编译为Java应用程序运行。以下是两种使用方式的详细说明。

使用Docker

先决条件

• Docker CLI已安装并运行

基本用法

打印帮助信息：

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

迁移Jenkinsfile到Bitbucket Pipelines

1. 定义Docker容器内的挂载路径环境变量：

   shell
   export MOUNT_PATH=/files
   

2. 运行Docker容器执行迁移：

   shell
   docker run -it --rm \
     -e MOUNT_PATH=$MOUNT_PATH \  # 容器内文件挂载路径
     -v $PWD/workDir:$MOUNT_PATH \  # 将本地工作目录挂载到容器内路径
     atlassian/bitbucket-pipelines-importer migrate jenkins \
     -i "${MOUNT_PATH}/Jenkinsfile" \  # 输入Jenkinsfile路径（容器内）
     -o "${MOUNT_PATH}/bitbucket-pipelines.yml"  # 输出配置文件路径（容器内）
   

参数说明：

• -i/--input：指定输入的Jenkinsfile路径（容器内路径）
• -o/--output：指定输出的bitbucket-pipelines.yml路径（容器内路径）
• -v：本地目录与容器目录挂载，用于文件输入输出
• -e MOUNT_PATH：容器内挂载路径环境变量，需与挂载目录保持一致

从源码构建

先决条件

• Java 21 或更高版本
• Maven 构建工具

构建并运行Java应用

1. 编译JAR文件：

   shell
   mvn package spring-boot:repackage
   

2. 运行JAR文件执行迁移：

   shell
   java -jar target/bitbucket-pipelines-importer-<version>.jar \
     migrate jenkins \
     -i Jenkinsfile \  # 本地Jenkinsfile路径
     -o bitbucket-pipelines.yml  # 输出配置文件路径
   

本地构建Docker镜像

1. 构建镜像：

   shell
   docker build -t bitbucket-pipelines-importer .
   

2. 运行本地镜像：

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

定制与扩展

插件架构

工具采用插件化架构，支持以下扩展方式：

• 自定义插件转换处理程序：为未覆盖的Jenkins插件添加转换逻辑
• 覆盖现有插件：替换默认插件转换实现，满足特定需求

添加自定义插件转换处理程序

1. 创建实现PluginTranslationHandler接口的类：

   java
   public class CustomPluginHandler implements PluginMappingStrategy {
       @Override
       public PluginMappingResult map(MappingContext context, JenkinsStep jenkinsStep) {
           // 自定义转换逻辑实现
           return;
       }
   }
   

2. 注册为Spring组件并设置优先级和支持的命令：

   java
   @Component
   @Order(BeanPrecedence.DEFAULT_MID_IMPLEMENTATION)  // 设置优先级
   @SupportedCommands({"custom"})  // 指定支持的Jenkins命令
   public class CustomPluginHandler implements PluginMappingStrategy {}
   

覆盖现有插件

1. 创建覆盖默认实现的类

2. 使用@Order注解设置更高优先级（值越小优先级越高）：

   java
   public interface BeanPrecedence {
       int CUSTOM_IMPLEMENTATION = 1;        // 自定义实现（最高优先级）
       int DEFAULT_MID_IMPLEMENTATION = 10;  // 默认中等优先级实现
       int DEFAULT_LOW_FALLBACK = 100;       // 默认低优先级回退实现
   }
   
   @Component
   @Order(BeanPrecedence.CUSTOM_IMPLEMENTATION)  // 高于默认实现
   @SupportedCommands({"sh"})  // 覆盖"sh"命令的处理
   public class CustomPluginHandler implements PluginMappingStrategy {}
   

文档与支持

官方文档

详细使用说明请参考官方文档

演示视频

Jenkins迁移演示

社区支持

加入Bitbucket Pipelines社区，可：

• 提问并获取技术支持
• 分享使用反馈
• 提出需要支持的Jenkins插件需求

本地开发

测试

shell
mvn verify

代码格式化

shell
mvn spotless:apply

编辑器Lombok配置

工具使用Lombok减少样板代码，需在编辑器中安装Lombok插件：

• IntelliJ IDEA
• Eclipse
• Visual Studio Code

贡献

欢迎对Bitbucket Pipelines Importer贡献代码！详情请参见CONTRIBUTING.md

许可证

Copyright (c) 2024 Atlassian US., Inc.
采用Apache 2.0许可证，详见LICENSE文件。

https://raw.githubusercontent.com/atlassian-internal/oss-assets/master/banner-cheers.png]([***]