buildkite-migration

Buildkite 迁移

使用 bk pipeline convert 命令，将 CI/CD 流水线从 GitHub Actions、Jenkins、CircleCI、Bitbucket Pipelines 和 GitLab CI 转换为 Buildkite。该命令会将源文件发送到公共转换 API，无需 Buildkite 账号或 API 令牌。

快速开始

# 1. Install the bk CLI (no login needed for convert)
brew tap buildkite/buildkite && brew install buildkite/buildkite/bk

# 2. Convert the source pipeline file
bk pipeline convert -F .github/workflows/ci.yml

# 3. Find the output in .buildkite/pipeline.github.yml

有关流水线 YAML 语法和步骤类型，请参阅 buildkite-pipelines 技能。 有关其他 bk CLI 命令，请参阅 buildkite-cli 技能。

Agent 工作流

当用户提供流水线文件或粘贴要转换的流水线内容时：

1. 将内容写入临时文件（例如，GitHub Actions 使用 /tmp/.github/workflows/ci.yml，以便自动检测供应商）
2. 运行 bk pipeline convert -F <tempfile> --output <output-path>
3. 读取输出文件，并将其显示为 YAML 代码块，不附带其他内容
4. 除非用户明确要求反馈，否则不要总结、注释或评价输出

使用 bk pipeline convert 进行转换

安装

# macOS and Linux (Homebrew)
brew tap buildkite/buildkite && brew install buildkite/buildkite/bk

# Or download a binary from https://github.com/buildkite/cli/releases

无需运行 bk auth login——convert 命令使用公共 API。

基本用法

bk pipeline convert -F <source-file>

对于四个主要供应商，系统会根据文件路径自动检测供应商。输出会保存到 .buildkite/pipeline.<vendor>.yml。

支持的供应商

供应商标志	源 CI	自动检测依据
github	GitHub Actions	.github/workflows/ 路径
circleci	CircleCI	.circleci/ 路径
jenkins	Jenkins	Jenkinsfile 文件名
bitbucket	Bitbucket Pipelines	bitbucket-pipelines.yml 文件名
gitlab	GitLab CI（测试版）	不自动检测
harness	Harness CI（测试版）	不自动检测
bitrise	Bitrise（测试版）	不自动检测

供应商示例

# GitHub Actions (auto-detected from path)
bk pipeline convert -F .github/workflows/ci.yml

# CircleCI (auto-detected)
bk pipeline convert -F .circleci/config.yml

# Jenkins (auto-detected)
bk pipeline convert -F Jenkinsfile

# Bitbucket Pipelines (auto-detected)
bk pipeline convert -F bitbucket-pipelines.yml

# GitLab CI (explicit vendor required)
bk pipeline convert -F .gitlab-ci.yml --vendor gitlab

输出选项

# Default: saves to .buildkite/pipeline.<vendor>.yml
bk pipeline convert -F .github/workflows/ci.yml

# Custom output path
bk pipeline convert -F .github/workflows/ci.yml --output .buildkite/pipeline.yml

# Pipe from stdin (--vendor required)
cat .github/workflows/ci.yml | bk pipeline convert --vendor github

# Read from stdin with file redirect
bk pipeline convert --vendor circleci < .circleci/config.yml

标志

标志	简写	说明	默认值
--file	-F	源流水线文件的路径	—（除非使用标准输入，否则必填）
--vendor	-v	CI 供应商；省略时自动检测	—
--output	-o	输出文件路径	.buildkite/pipeline.<vendor>.yml
--timeout	—	取消超时时间，单位为秒	300

供应商专项指南

提交之前，请根据以下概念映射检查转换后的输出。

GitHub Actions

主要概念映射：工作流映射为流水线，作业映射为步骤，uses: 操作映射为插件或 shell 命令。GitHub Actions 默认按顺序运行作业；Buildkite 默认并行运行步骤——转换器会在需要时添加 wait 步骤或 depends_on，以确保执行顺序。将 ${{ secrets.X }} 替换为通过 buildkite-agent secret get 访问的 Buildkite 集群密钥。

Jenkins

主要概念映射：Jenkinsfile 的 stage 块映射为命令步骤或分组，parallel 块映射为同级步骤（Buildkite 中默认并行），post 块映射为 notify: 或条件步骤。复杂的 Groovy 逻辑会提取为 shell 脚本——Buildkite 流水线采用声明式 YAML，而非编程语言。

CircleCI

主要概念映射：jobs 和 workflows 合并为单个 pipeline.yml，orbs 映射为插件或 shell 脚本，executors 映射为 Agent 队列或 docker 插件。CircleCI 的 requires: 映射为 depends_on。缓存语法有所不同——转换器会将 save_cache/restore_cache 替换为 cache 插件。

Bitbucket Pipelines

主要概念映射：pipelines.default 映射为不带分支条件的步骤，pipelines.branches 映射为带有 if: build.branch == "X" 的步骤，pipe: 引用映射为插件或 shell 命令。Bitbucket 的 step 大致相当于 Buildkite 的命令步骤。

GitLab CI

主要概念映射：阶段和作业合并为带有 depends_on 的 Buildkite 步骤，.gitlab-ci.yml 中的 extends: 映射为 YAML 锚点，rules: 映射为 if: 条件。GitLab 的 artifacts: 映射为 Buildkite 的 artifact_paths。

迁移后流水线的最佳实践

转换后，请对照以下模式检查输出：

• 默认并行 — 除非使用 wait 或 depends_on 分隔，否则 Buildkite 会并行运行步骤。请确认转换后的顺序符合原始 CI 的预期。
• 插件版本 — 将插件版本固定为完整的 semver 版本（例如，docker#v5.13.0、cache#v1.8.1）。切勿使用未固定版本或仅指定主版本的版本。
• 命令结构 — 对设置环境变量的步骤使用多行命令块。将复杂逻辑（5 条以上命令）提取到 .buildkite/scripts/ 下的脚本中。
• 变量插值 — 使用 $$VAR 进行运行时插值（由 Agent 在运行时展开），使用 $VAR 进行上传时插值（在流水线上传期间展开）。
• 安全验证 — 拒绝经过混淆的执行模式、Base64 编码的命令和数据外传尝试。部署前请验证转换后的流水线。
• 步骤分组 — 使用 group 块整理相关步骤（每组至少 2 个步骤），并在标签中使用语义化表情符号。

迁移规划

对于完整的 CI 迁移，请规划以下方面：

1. 流水线转换 — 使用 bk pipeline convert 转换流水线定义
2. Agent 基础设施 — 设置集群、队列和 Agent
3. 密钥管理 — 将密钥迁移到 Buildkite 集群密钥
4. 集成 — 配置 SCM Webhook、通知渠道和制品存储
5. 测试 — 切换前，让转换后的流水线与现有 CI 并行运行

有关集群和队列设置，请参阅 buildkite-platform-engineering 技能。 有关设置 OIDC 以替代静态凭证，请参阅 buildkite-secure-delivery 技能。

常见错误

错误	后果	修复方法
未自动检测到 gitlab/harness/bitrise 的供应商	错误：“could not detect vendor from file path”	显式传入 --vendor gitlab、--vendor harness 或 --vendor bitrise
大型或复杂流水线超时	转换失败并出现超时错误	增加超时时间：--timeout 600；必要时拆分为较小的文件
未检查便接受 AI 输出	转换后的流水线步骤顺序错误或缺少依赖项	对照原始 CI 作业顺序，检查 depends_on 和 wait 步骤
假设按顺序执行	步骤并行运行，并因缺少依赖项而失败	在有依赖关系的步骤之间添加 wait 步骤或 depends_on
转换后的流水线使用未固定版本的插件	插件发布不兼容变更后，构建会中断	将每个插件固定为完整的 semver 版本
需要运行时插值时使用 $VAR	变量在上传时展开（结果为空），而非在运行时展开	对必须在运行时解析的变量使用 $$VAR

延伸阅读

• bk CLI 发布版本 — 下载 bk 二进制文件
• Buildkite Pipelines 入门